diff --git a/docs/web-console-docs/holdout/_category_.json b/docs/web-console-docs/holdout/_category_.json
new file mode 100644
index 00000000..ce4c37e3
--- /dev/null
+++ b/docs/web-console-docs/holdout/_category_.json
@@ -0,0 +1,6 @@
+{
+ "position": 9,
+ "collapsible": true,
+ "collapsed": true,
+ "label": "Holdouts"
+}
diff --git a/docs/web-console-docs/holdout/overview.mdx b/docs/web-console-docs/holdout/overview.mdx
new file mode 100644
index 00000000..00f4a9e1
--- /dev/null
+++ b/docs/web-console-docs/holdout/overview.mdx
@@ -0,0 +1,253 @@
+---
+sidebar_position: 1
+title: "Overview"
+description: "Holdouts measure the combined impact of your experiments by keeping a small group of visitors out of them."
+---
+
+import Image from "../../../src/components/Image";
+
+# Overview
+
+## What is a holdout
+
+Individual experiments tell you the impact of a single change. A **holdout** tells you the
+impact of everything you shipped, together.
+
+A holdout keeps a small, randomly selected group of visitors out of the experiments it covers.
+Their behaviour becomes a baseline. By comparing that baseline with visitors who are exposed to
+your experiments as normal, you can measure the cumulative effect of your experimentation
+programme over a period of months rather than the effect of one change at a time.
+
+This answers questions that individual experiment results cannot:
+
+- Do the wins we recorded across dozens of experiments add up at the aggregate level?
+- Are the effects of our changes still present months after launch, or did they decay?
+- Is there an interaction between our experiments that no single test would reveal?
+
+
+
+## Tracking units and teams
+
+Every holdout has a **tracking unit** and is owned by one or more **teams**.
+
+The tracking unit mirrors how experiments work. An experiment that randomises on Device ID can
+only be held out from a group defined by Device ID, so a holdout only covers experiments that share
+its tracking unit. The tracking unit is chosen when the holdout is created and cannot be changed
+afterwards.
+
+A holdout's teams play two roles. They own it, so their Team Admins manage it. They also decide
+which experiments it covers: a holdout holds out the experiments of its teams and of their child
+teams. Holdouts are always owned by teams, never by individual users, even where user-level
+ownership is enabled for other assets.
+
+A **general holdout** is owned by your top-level team, the team named after your organisation.
+Every other team sits under it, so a general holdout covers experiments from all teams. Only
+`FullAdmin` users can create a general holdout.
+
+A team can only own one holdout per tracking unit. There is therefore at most one general holdout
+per tracking unit. For example, you could run a general User ID holdout for the whole
+organisation and a separate User ID holdout for the landing pages team, but not two User ID holdouts
+for the landing pages team.
+
+Holdouts can overlap. An experiment from the Development team, a child of Engineering, can be
+covered on the same tracking unit by a Development holdout, an Engineering holdout and the general
+holdout. A visitor can be held out by more than one of them.
+
+:::info
+To understand how tracking units are defined on your platform, see
+[Tracking Unit](/docs/web-console-docs/experiments/creating-an-experiment#tracking-unit).
+:::
+
+## Simple and advanced holdouts
+
+A holdout is either **simple** or **advanced**.
+
+A **simple holdout** (the default) keeps one group of visitors out of all experiments and compares
+it with everyone else. It is the best way to measure the total cumulative impact of your
+experimentation programme.
+
+An **advanced holdout** adds a second held-out group. This group is also kept out of experiments,
+but it does see the features that have already been shipped to 100% of traffic. This separates two
+effects which a simple holdout measures together: the impact of what you shipped, and the impact of
+being exposed to experiments which were tested but not kept.
+
+An advanced holdout needs a second held-out group of the same size, so it takes more of your
+traffic. Fewer visitors remain available for experiments, which may then need to run longer to
+collect enough participants for reliable results.
+
+## How the comparison works
+
+A holdout report compares groups of equal size. Every variant is compared with the control.
+
+| Group | Role | What it sees | Holdout type |
+| --- | --- | --- | --- |
+| **Holdout** | Control | No experiments. The baseline experience. | Simple and advanced |
+| **No Holdout** | Variant 1 | Experiments as normal, exactly like the rest of your population. | Simple and advanced |
+| **Full on only** | Variant 2 | No experiments, but features already shipped to 100% of traffic. | Advanced only |
+
+The **No Holdout** group is not simply "everyone else". It is a sample drawn from the full
+experiment-exposed population and sized to match the holdout group. Comparing a 3% holdout against
+the remaining 97% directly would put a small group next to a very large one, and the imbalance
+costs you statistical power. Sampling an equal-size comparison group keeps the two sides balanced
+and the comparison fair.
+
+The relative impact of **No Holdout** therefore reads as: how much the experiment-exposed group
+differs from the holdout baseline. In an advanced holdout, the relative impact of **Full on only**
+reads as: how much the features you shipped, on their own, changed behaviour compared with the
+baseline.
+
+## Traffic allocation
+
+The traffic allocation is the share of the tracking unit's traffic kept out of experiments. It can
+be set between **1% and 10%**.
+
+| Holdout type | Default allocation |
+| --- | --- |
+| Simple | **3%**, all of it in the holdout group |
+| Advanced | **6%**, with 3% in each of the two held-out groups |
+
+The **No Holdout** comparison group is not part of the allocation. It is sampled from the
+experiment-exposed population to match the size of the holdout group.
+
+The size of the allocation is a trade-off. A larger holdout detects smaller cumulative effects, but
+it also means more visitors are kept away from the improvements you have shipped.
+
+## Which experiments are included
+
+Each holdout has an **experiment inclusion** setting, which decides how experiments join it. Like
+the rest of the holdout's configuration, a change to this setting applies from the next period.
+
+**Opt-out** (the default): every experiment on the holdout's tracking unit, from its teams
+and their child teams, is included automatically. An experiment's owners can request to exclude it,
+and the people who can edit the holdout decide whether to grant the exclusion. Grant exclusions
+sparingly. Each exclusion means the holdout group has seen that experiment after all, so the
+baseline drifts a little further from "the product as it was". Reserve exclusions for cases where
+withholding a change is not acceptable, such as a legal or compliance requirement, or a fix that
+must reach all visitors.
+
+**Opt-in**: experimenters add their experiment to the holdout from the experiment form. Only
+experiments on the holdout's tracking unit, from its teams and their child teams, can be
+added, and anyone who can edit such an experiment can add it. Only opted-in experiments take part.
+
+## Periods and resets
+
+A holdout runs for a **duration** chosen at setup: **3 months**, **6 months**, **12 months**, or
+**until stopped**.
+
+When a fixed duration ends, the holdout can restart automatically: a new period begins immediately
+with the same configuration, and visitors are randomised again from scratch. A holdout set to run
+until stopped has no end date, so it runs as a single period and does not restart automatically.
+
+Fresh randomisation matters. A visitor who was held out during one period is unlikely to be held out
+in the next, which stops the same people from being excluded from your product improvements
+indefinitely, and prevents the holdout group from slowly diverging into an unrepresentative
+population.
+
+Each period is an **independent dataset** with its own results. Periods are not merged or averaged.
+When a period ends its results are archived and stay accessible, so you can look back at how the
+cumulative impact of your experimentation changed from one period to the next.
+
+## Reading results before the period ends
+
+You do not have to wait for the period to end to learn something. Holdouts are analysed once per
+day using **Fully Sequential testing**, so results are valid whenever you look at them and can be
+checked at any point during the period.
+
+## Metrics
+
+The metrics used to evaluate a holdout (max 5 of them) are selected from your existing metric
+catalogue, filtered to those compatible with the holdout's tracking unit. A metric defined on User
+ID cannot be computed for a Device ID holdout, so it is not offered.
+
+Because a holdout measures broad, long-run impact rather than the effect of one change, favour your
+top-line business metrics over narrow, feature-specific ones.
+
+## Permissions
+
+Holdouts are Experiment Assets, like experiments and metrics, and follow the
+[ownership model](/docs/web-console-docs/users-teams-permissions/ownership-and-permissions). They
+are always owned by one or more teams, and can be shared with other users and teams. They have
+their own permissions, separate from those for experiments.
+
+A holdout takes traffic from every experiment of the teams that own it, so some rules differ from
+other assets. These are described below.
+
+### Team roles
+
+The built-in team roles grant the following on holdouts owned by the team:
+
+| Team role | On the team's holdouts |
+| --- | --- |
+| **Team Admin** | Create, edit, start, stop, archive and view |
+| **Team Contributor** | View only |
+| **Team Viewer** | View only |
+
+If a holdout is owned by several teams, the Team Admins of each of them can manage it.
+
+As with other assets, team roles cascade down the team hierarchy, and members of a team with no team
+role cannot see its holdouts. This includes implicit members of parent teams: a member of the
+Development team does not see a holdout owned by Engineering, even if it covers their experiments,
+unless it is shared with them.
+
+### Owning teams
+
+You can only add a team to a holdout if you are a Team Admin of that team. Adding a team gives its
+Team Admins control of the holdout and holds out its experiments, so this stops one team from
+taking traffic from teams it does not manage.
+
+The general holdout is owned by your top-level team. By default, only `FullAdmin` users can create
+and manage it, along with anyone it is shared with using **Can Edit**.
+
+### Sharing a holdout
+
+A holdout can be shared with users and teams:
+
+- **Can View**: find the holdout and view its results. Unlike other assets, Can View does not let
+ anyone use the holdout. Adding an experiment to a holdout is controlled by the experiment, see
+ below.
+- **Can Edit**: manage the holdout, as its Team Admins do. Only users who can edit a holdout can share it
+ with Can Edit.
+
+The general holdout is not visible to everyone by default. To let everyone see its results, share it
+with your top-level team with **Can View**.
+
+### Adding and excluding experiments
+
+- **Adding** an experiment to an opt-in holdout: anyone who can edit the experiment, as long as the
+ experiment belongs to one of the holdout's teams or their child teams.
+- **Excluding** an experiment from an opt-out holdout: the experiment's owners request the exclusion,
+ and the people who can edit the holdout grant or refuse it.
+
+Excluding an experiment weakens the holdout's baseline, so the decision sits with the holdout's
+owning teams rather than with the experiment's owners.
+
+### Holdout permissions
+
+The following permissions can be granted to users through custom global roles.
+
+| Permission | Description |
+| --- | --- |
+| **Create a holdout** | Allows creating a new holdout. |
+| **Edit a holdout** | Allows changing a holdout's configuration and deciding on requests to exclude experiments. Configuration changes apply from the next period. |
+| **Start a holdout** | Allows starting a holdout. |
+| **Stop a holdout** | Allows stopping a running holdout. Stopping a holdout manually disables its automatic restart. |
+| **List holdouts** | Allows finding holdouts in the list of holdouts. |
+| **Get a holdout** | Allows viewing a specific holdout and its configuration. |
+| **Get holdout metrics** | Allows viewing a holdout's results. |
+| **Archive a holdout** | Allows archiving a holdout. |
+| **Unarchive a holdout** | Allows restoring an archived holdout. |
+| **Holdout admin** | Grants all holdout permissions. |
+
+Holdouts cannot be put into development, put Full on or recomputed, so there are no permissions for
+those actions.
+
+:::info
+As with other Experiment Assets, holdout permissions granted through a global role apply to every
+holdout, whichever team owns it. Prefer the team-based model where possible. See
+[Roles](/docs/web-console-docs/users-teams-permissions/roles).
+:::
+
+## Next steps
+
+- [Setting up a holdout](./setting-up-a-holdout) walks through the configuration.
+- [Reading holdout results](./reading-holdout-results) explains the report and the period history.
diff --git a/docs/web-console-docs/holdout/reading-holdout-results.mdx b/docs/web-console-docs/holdout/reading-holdout-results.mdx
new file mode 100644
index 00000000..fe4c0c27
--- /dev/null
+++ b/docs/web-console-docs/holdout/reading-holdout-results.mdx
@@ -0,0 +1,119 @@
+---
+sidebar_position: 3
+title: "Reading Holdout Results"
+description: "Interpret the holdout report, and browse the archived results of previous periods."
+---
+
+import Image from "../../../src/components/Image";
+
+# Reading Holdout Results
+
+A holdout report shows the cumulative impact of your experiments on a tracking unit, measured
+against a group of visitors who were kept out of them.
+
+Open a holdout from the **Holdouts** page to see its detail view. The **Overview** tab shows the
+results of a single period, and the **Iterations** tab lists every period the holdout has run.
+
+Holdout results are visible to users with a team role on a team that owns the holdout, and to
+anyone it is shared with. See [Permissions](./overview#permissions).
+
+## The Overview tab
+
+
+
+The top of the page shows the holdout's name, its description, and badges for its holdout type
+(**Advanced**), its experiment inclusion setting (**Opt-out** or **Opt-in**) and its teams.
+
+Below that, the period header names the period you are looking at, its status and its scheduled
+start and end dates. Use the arrows on the right to move between periods without leaving the tab.
+
+A summary card repeats the holdout's configuration: tracking unit, traffic allocation, duration and
+schedule.
+
+### The variants
+
+Every metric is reported for the same groups. Each variant is compared with the control.
+
+| Variant | Name | What it represents | Holdout type |
+| --- | --- | --- | --- |
+| Control | **Holdout** | Visitors kept out of all experiments. The baseline. | Simple and advanced |
+| Variant 1 | **No Holdout** | A sample of the experiment-exposed population, sized to match the holdout group. | Simple and advanced |
+| Variant 2 | **Full on only** | Visitors held out of experiments who only see features already shipped to 100% of traffic. | Advanced only |
+
+All rows carry equal participant counts by design. **No Holdout** is sampled from the full
+population rather than being every remaining visitor, so that the comparison is between groups of
+the same size. A **Sampling** toggle above the metrics indicates that this equal-size sampling is
+in effect.
+
+### Reading a metric
+
+Each metric card lists every variant with its participants, value and mean, followed by a
+**Metric total** row. For each variant, the statistics of its comparison with the control are
+shown:
+
+- **Confidence**: how confident the test is that the observed difference is real.
+- **Relative impact**: how much the variant differs from the holdout baseline.
+- **Impact per day**: the effect expressed as a daily rate.
+
+Because Control is the holdout, a **positive relative impact on No Holdout means your experiments
+are performing better than the unchanged product**. That is the outcome you are hoping for: the
+changes you shipped add up to a measurable gain over doing nothing.
+
+A negative or flat result is equally informative. It suggests the individual wins you recorded did
+not accumulate, whether through decay over time, interaction between experiments, or effects that
+were smaller than they first appeared.
+
+In an advanced holdout, **Full on only** shows the impact of the features you shipped on their
+own, without exposure to the experiments that were tested but not kept. Comparing it with **No
+Holdout** tells you how much of the overall impact comes from what you shipped, and how much comes
+from running experiments.
+
+:::info
+For a fuller explanation of confidence, impact and the statistics behind them, see
+[Interpreting metrics in experiment results](/docs/web-console-docs/experiments/interpreting-metrics-in-experiment-results).
+:::
+
+### Experiments in this period
+
+Below the metrics, the **Experiments in this period** table lists every experiment that ran at any
+point during the period, with its status, start date, and the date it was stopped or put Full on.
+
+Use it to connect a change in the holdout's results with the experiments that were running at the
+time.
+
+### Checking results before the period ends
+
+Holdouts are analysed once per day using Fully Sequential testing, so the numbers are valid whenever
+you look at them. You can check a running holdout at any point during its period without waiting
+for it to finish, and without the risk of an inflated false positive rate that repeatedly checking
+a fixed horizon test would carry.
+
+Because results refresh daily rather than continuously, the figures you see reflect the most recent
+analysis rather than the last few minutes of traffic.
+
+## The Iterations tab
+
+
+
+Each period the holdout has run appears here, newest first, with its status, date range and total
+participants. The current period shows as **Running**; earlier ones show as **Completed**.
+
+Expand any period to see its results.
+
+### Periods are independent
+
+Each period is a separate dataset with its own randomisation and its own results. Periods are never
+merged or averaged, because the holdout group is drawn fresh each time and the experiments running
+during one period are not the same as those running during the next.
+
+Read the sequence as a trend rather than a single accumulating number. A run of periods each showing
+a positive impact is strong evidence that your experimentation programme is delivering; a series
+that flattens over time is a signal worth investigating.
+
+Completed periods stay accessible indefinitely, so the archive builds into a long-run record of what
+your experimentation has been worth.
+
+## Related
+
+- [Holdout overview](./overview)
+- [Setting up a holdout](./setting-up-a-holdout)
diff --git a/docs/web-console-docs/holdout/setting-up-a-holdout.mdx b/docs/web-console-docs/holdout/setting-up-a-holdout.mdx
new file mode 100644
index 00000000..48f6bcc4
--- /dev/null
+++ b/docs/web-console-docs/holdout/setting-up-a-holdout.mdx
@@ -0,0 +1,172 @@
+---
+sidebar_position: 2
+title: "Setting up a Holdout"
+description: "Create a holdout, configure its type, experiment inclusion, traffic allocation, metrics and schedule, then start it."
+---
+
+import Image from "../../../src/components/Image";
+
+# Setting up a Holdout
+
+A step by step guide to creating a holdout, configuring it and starting it.
+
+Open the **Holdouts** page from the left navigation. It lists every holdout on your platform, along
+with its status, tracking unit, traffic allocation, metrics and schedule.
+
+
+
+## Creating a holdout
+
+Click **New holdout**, then choose:
+
+- **Tracking unit** (required): the unit used to identify visitors. It is fixed once the holdout is
+ created, and only experiments using this unit can join it.
+- **Teams** (optional): the teams that own the holdout. You can choose more than one. The Team
+ Admins of these teams manage the holdout, and it covers the experiments of these teams and their
+ child teams. You can only add teams where you are a Team Admin. Leave it empty to create a general
+ holdout, owned by your top-level team, which covers experiments from all teams. Only `FullAdmin`
+ users can create a general holdout.
+
+A team can only own one holdout per tracking unit, so there can be at most one general holdout per
+tracking unit. Holdouts are always owned by teams, never by individual users. See
+[Permissions](./overview#permissions).
+
+Click **Create holdout** to open its configuration page.
+
+
+
+## General
+
+Give the holdout a **Name** and an optional **Description**. These appear on the Holdouts page and at
+the top of the report, so describe what the holdout covers, for example
+`Holdout group for all experiments tracking visitors by device`.
+
+## Configuration
+
+### Holdout type
+
+Choose whether to hold out one group or two. This affects how the holdout results are compared.
+
+- **Simple holdout** (default): one held-out control group, kept out of all experiments and
+ compared against everyone else. Best for measuring the total cumulative impact of your
+ experimentation programme.
+- **Advanced holdout**: adds a second held-out group that only sees features already shipped to
+ 100% of traffic, so you can isolate the impact of experiments from the impact of what was kept.
+
+:::caution
+Advanced holdouts use more of your traffic. Because of the additional held-out group, fewer visitors
+remain available for experiments, and experiments may need to run longer to collect enough
+participants for reliable results.
+:::
+
+See [Simple and advanced holdouts](./overview#simple-and-advanced-holdouts) for how the two types
+compare.
+
+### Tracking unit
+
+The **tracking unit** chosen when the holdout was created is shown here and cannot be changed. Only
+experiments that track visitors with this unit are part of this holdout.
+
+### Teams
+
+The teams that own the holdout. Their Team Admins manage it, and it covers the experiments of these
+teams and their child teams. You can only add teams where you are a Team Admin. Leave it empty for a
+general holdout.
+
+### Experiment inclusion
+
+Choose how experiments join this holdout.
+
+- **Opt-out** (default): all experiments on the holdout's tracking unit, from its teams and
+ their child teams, are included automatically. An experiment's owners can request to exclude it.
+- **Opt-in**: experimenters add their experiment to this holdout from the experiment form. Only
+ experiments from the holdout's teams and their child teams can be added, and only
+ opted-in experiments take part.
+
+### Traffic allocation
+
+Choose what share of this unit's traffic is held out, between **1% and 10%**.
+
+| Holdout type | Recommended allocation |
+| --- | --- |
+| Simple | **3%** |
+| Advanced | **6%**, with 3% for each held-out group |
+
+The allocation covers the held-out groups only. The **No Holdout** group they are compared against
+is sampled from the rest of the population to match their size.
+
+:::tip
+Increasing the allocation lets you detect smaller cumulative effects, but keeps more visitors away
+from the improvements you have shipped. If you are unsure, start with the recommended allocation.
+:::
+
+## Metrics
+
+Select the metrics used to evaluate the holdout, from your existing metric catalogue. A holdout can
+use up to **5 metrics**.
+
+Only metrics compatible with the holdout's tracking unit are shown, and the active filter is
+displayed above the selector. A metric defined on a different unit cannot be computed for this
+holdout, so it does not appear in the list.
+
+Choose metrics that reflect the overall health of your product rather than the success of any one
+feature. A holdout measures the combined effect of everything you shipped, so top-line business
+metrics are the ones worth watching.
+
+## Schedule
+
+### Duration
+
+Choose a **duration** of **3 months**, **6 months**, **12 months** or **Until stopped**. Set a
+**start date**, and the end date is calculated for you.
+
+A longer period accumulates more experiments and more data, which makes small cumulative effects
+easier to detect. A shorter period gives you a completed, archived result sooner and refreshes the
+randomisation more often. Three months suits platforms running many experiments; six or twelve
+months suit those with fewer experiments or slower-moving metrics.
+
+A holdout set to run **Until stopped** has no end date. It runs as a single period until you stop
+it.
+
+### Restart automatically when holdout ends
+
+When this is enabled, a new holdout period with the same configuration begins immediately once the
+current one ends, and visitors are randomised again from scratch. A visitor who was in the holdout
+group during one period might not be in it during the next.
+
+Automatic restart does not apply to holdouts set to run **Until stopped**, since they have no end
+date. It is also disabled when a holdout is stopped manually.
+
+## Starting and stopping
+
+Save the configuration, then start the holdout when you are ready. Running holdouts show a
+**Running** status on the Holdouts page, along with their current period's dates.
+
+:::caution
+Changes saved while a holdout is running only apply to the **next** period. This covers every
+setting, including experiment inclusion. The current period keeps the configuration it started
+with, so its dataset stays internally consistent. To change a running holdout immediately, stop it
+first, then save.
+:::
+
+## Adding and excluding experiments
+
+With **Opt-in** inclusion, experimenters add their experiment to the holdout from the experiment
+form. Anyone who can edit an experiment can add it.
+
+With **Opt-out** inclusion, every experiment on the holdout's tracking unit, from its teams
+and their child teams, is included automatically. To exclude an experiment, its owners request the
+exclusion, and the people who can edit the holdout grant or refuse it. Owning the experiment is not
+enough on its own.
+
+Grant an exclusion only when withholding a change is genuinely not acceptable, such as a legal or
+compliance requirement, or a fix that has to reach every visitor. Each exclusion means the holdout
+group has been exposed to that experiment, which moves the baseline a little further from the
+unchanged product and weakens the comparison.
+
+If you expect to exclude many experiments, consider **Opt-in** inclusion instead, so that only the
+experiments you choose take part.
+
+## Next steps
+
+Once the holdout is running, see [Reading holdout results](./reading-holdout-results).
diff --git a/docs/web-console-docs/users-teams-permissions/ownership-and-permissions.mdx b/docs/web-console-docs/users-teams-permissions/ownership-and-permissions.mdx
index 455e1934..cec79420 100644
--- a/docs/web-console-docs/users-teams-permissions/ownership-and-permissions.mdx
+++ b/docs/web-console-docs/users-teams-permissions/ownership-and-permissions.mdx
@@ -9,7 +9,7 @@ import Image from "../../../src/components/Image";
Over the last few months we incrementally released many new features related to teams, ownership & collaboration aimed at improving how teams are experimenting and collaborating with each other.
In this document we will discuss those changes and how you can start making use of them.
-Experiment Assets in scope: **Experiments**, **Features**, **Templates**, **Metrics** & **Goals**.
+Experiment Assets in scope: **Experiments**, **Features**, **Templates**, **Metrics**, **Goals** & **Holdouts**.
All other configuration settings are managed using global roles. For more details see our [Roles](./roles) page.
@@ -32,17 +32,17 @@ If you have not done so yet, we encourage you to go to /settings/teams and start
Until now, the ownership of anything created on the ABsmartly platform was set at the individual user level (usually the person who created the item).
While this is often fine, in many cases it is preferable for assets like Experiment or Metrics to be owned by a team and not by an individual.
Team level ownership is more resilient to changes and it makes it easier to manage and share assets at scale.
-Because of this we introduced team level ownership for `Experiments`, `Features`, `Templates`, `Goals` & `Metrics`.
+Because of this we introduced team level ownership for `Experiments`, `Features`, `Templates`, `Goals`, `Metrics` & `Holdouts`.
Other assets like `Applications`, `Tracking Unit`, etc which are platform level settings remain unchanged.
For backward compatibility, existing assets will retain their current individual owners but it won't be possible to add new ones.
:::info
-While Team Ownership is the new default and preferred way of assigning ownership for Experiments, Features, Templates, Goals & Metrics, it is possible to re-enable user level ownership in the platform settings (/settings/platform).
+While Team Ownership is the new default and preferred way of assigning ownership for Experiments, Features, Templates, Goals, Metrics & Holdouts, it is possible to re-enable user level ownership in the platform settings (/settings/platform).
:::
:::tip
-To get the most of the new model we encourage you to move the ownership of your existing Experiments, Features, Templates, Goals & Metrics to the most relevant team in your organisation. To do that, just edit assets that you currently own and re-assign ownership to the correct team. Make sure that you are a member of that team if you want to retain your access to that asset.
+To get the most of the new model we encourage you to move the ownership of your existing Experiments, Features, Templates, Goals, Metrics & Holdouts to the most relevant team in your organisation. To do that, just edit assets that you currently own and re-assign ownership to the correct team. Make sure that you are a member of that team if you want to retain your access to that asset.
:::
---
@@ -53,7 +53,7 @@ Together with the new team structure, you can now also assign members to those t
By default all platform users are members of the Global Team (feel free to rename it so it matches your company name) which represents your entire organisation but you can now also add them to their actual team in the team hierarchy.
When adding a new member to a team, it is also possible to assign this user an optional role in that team.
-The role that a member has in a team will define how this person can interact with the assets owned by that team. Assets here are Experiments, Features, Templates, Goals & Metrics.
+The role that a member has in a team will define how this person can interact with the assets owned by that team. Assets here are Experiments, Features, Templates, Goals, Metrics & Holdouts.
Possible team roles are :
@@ -85,19 +85,19 @@ Make sure to add all platform users to their respective team and assign them the
## Global team permissions & Base user role
The Global Team is unique in the team structure, not only does it automatically contain all the members of the platform (no need to add them),
-it is also where general roles and permissions are defined. As discussed above, team level roles define how users can interact with `Experiments`, `Features`, `Templates`, `Goals` & `Metrics` owned by that team,
+it is also where general roles and permissions are defined. As discussed above, team level roles define how users can interact with `Experiments`, `Features`, `Templates`, `Goals`, `Metrics` & `Holdouts` owned by that team,
everything else (who can create new Applications, who can manage Segments and API Keys) are platform level settings and are managed at the Global Team level.
-For backward compatibility, it is still possible to assign permissions to `Experiments`, `Features`, `Templates`, `Goals` & `Metrics` at the Global Team level but it is not recommended as it would interfere and overwrite anything specified at the team level.
+For backward compatibility, it is still possible to assign permissions to `Experiments`, `Features`, `Templates`, `Goals`, `Metrics` & `Holdouts` at the Global Team level but it is not recommended as it would interfere and overwrite anything specified at the team level.
For example currently users with the built-in `User` role can view and list ANY experiment or metric irrespective of the role members have in their team.
-For the new team level model to work correctly, you should refrain from granting any permissions on Experiments, Features, Templates, Goals & Metrics in a global team role.
+For the new team level model to work correctly, you should refrain from granting any permissions on Experiments, Features, Templates, Goals, Metrics & Holdouts in a global team role.
To facilitate the transition to the new ownership model, we created a new (immutable) `Base User` role which contains all the basic permissions any user of the platform needs.
-This role does not grant the user any permission to view or edit `Experiments`, `Features`, `Templates`, `Goals` & `Metrics`.
+This role does not grant the user any permission to view or edit `Experiments`, `Features`, `Templates`, `Goals`, `Metrics` & `Holdouts`.
In time this role should replace the current User role assigned by default to all new users of the platform.
:::tip action
-Review your current roles & permissions to align with the new model (Ideally no global roles, besides the fulladmin role, should grant permissions to `Experiments`, `Features`, `Templates`, `Goals` & `Metrics`) and start migrating your user from the `User` role to the new `Base User`.
+Review your current roles & permissions to align with the new model (Ideally no global roles, besides the fulladmin role, should grant permissions to `Experiments`, `Features`, `Templates`, `Goals`, `Metrics` & `Holdouts`) and start migrating your user from the `User` role to the new `Base User`.
If you need help automating this step please let us know. Once the migration is done, you can let us know so we can remove it and make `Base User` the new default role for all new users.
:::
@@ -108,7 +108,7 @@ If you need help automating this step please let us know. Once the migration is
All the features described above enable users to collaborate within their team but it does not allow them to share assets with other teams or individuals.
For example a team owning a metric wants to make this metric available to all teams in Engineering or a team working on an experiment wants to allow specific users from other teams to collaborate on that experiment without making them owners.
-To address this we introduced Asset level permissions (for `Experiments`, `Features`, `Templates`, `Goals` & `Metrics`) which is the ability to share an asset with other teams or individuals.
+To address this we introduced Asset level permissions (for `Experiments`, `Features`, `Templates`, `Goals`, `Metrics` & `Holdouts`) which is the ability to share an asset with other teams or individuals.
For now there are 2 types of possible permissions associated with sharing of assets.
- **Can View**: Grants the ability to search for, to view, comment on and to use this specific asset. A good use case for this is if you want to make your metric or a template available to another team or if you want other people to be able to view your experiment on the search page without being able to edit it.
@@ -124,7 +124,7 @@ Following the least privilege principle, and unless there is a good reason, it i
:::
:::tip
-Go over your list of Experiments, Features, Templates, Goals & Metrics that you own (or that your team owns) and make sure to share it with the relevant individual(s) or team(s).
+Go over your list of Experiments, Features, Templates, Goals, Metrics & Holdouts that you own (or that your team owns) and make sure to share it with the relevant individual(s) or team(s).
For example if you want a metric or a goal to be available for everybody to use, then share it with the Global Team with Can View permission.
It is possible that you want all your existing metrics, goals and possibly all your experiments, features and templates to be discoverable and usable by anyone on the platform.
If this is the case, just let us know and we will run a script to automatically grant Can View to all your existing assets saving you loads of manual work.
diff --git a/docs/web-console-docs/users-teams-permissions/roles.mdx b/docs/web-console-docs/users-teams-permissions/roles.mdx
index 9d162dbc..4454e7ac 100644
--- a/docs/web-console-docs/users-teams-permissions/roles.mdx
+++ b/docs/web-console-docs/users-teams-permissions/roles.mdx
@@ -14,7 +14,7 @@ ABsmartly supports two types of roles:
:::info
In ABsmartly Experiment Assets are assets created by teams on the day to day basis as part of their experimentation program.
-Those Experiment Assets include **Experiments**, **Feature Flag**, **Metrics**, **Goals** and **Templates**.
+Those Experiment Assets include **Experiments**, **Feature Flag**, **Metrics**, **Goals**, **Templates** and **Holdouts**.
Access to those Assets can be defined and granted at the global or the team level.
:::
@@ -32,7 +32,7 @@ They provide users with :
:::info
While possible, it is not recommended to assign global read/write access to Experiment Assets like
-**Experiments**, **Feature Flag**, **Metrics**, **Goals** and **Templates**.
+**Experiments**, **Feature Flag**, **Metrics**, **Goals**, **Templates** and **Holdouts**.
It is easier and cleaner to set up proper governance when ownership and permissions of Experiment Assets is defined at the team level.
:::
@@ -44,7 +44,7 @@ custom roles can be created to address specific needs or organisational structur
#### The Base User role
The `Base User` role grants users basic access to the platform. Those users can access the platform and have read-only access to all platform settings.
-By default, this role does not provide any permissions to view or edit Experiment Assets like **Experiments**, **Feature Flag**, **Metrics**, **Goals** and **Templates**.
+By default, this role does not provide any permissions to view or edit Experiment Assets like **Experiments**, **Feature Flag**, **Metrics**, **Goals**, **Templates** and **Holdouts**.
Access to those Experiment Assets will be granted to users as part of their team membership.
#### The FullAdmin role
@@ -101,7 +101,7 @@ A user with the `Team Viewer` can view and comment on, any Experiment Assets in
#### The Team Contributor role
-A user with the `Team Contributor` role can view and comment on, create and manage, any Experiment Assets in that team scope.
+A user with the `Team Contributor` role can view and comment on, create and manage, any Experiment Assets in that team scope, except holdouts, which they can only view.
:::caution
Unless it was disabled, users with the `Team Contributor` role can start/stop/full on all experiments in that team's scope.
@@ -109,7 +109,8 @@ Unless it was disabled, users with the `Team Contributor` role can start/stop/fu
#### The Team Admin role
-Same as `Team Contributor` but the `Team Admin` can also manage the users in that team.
+Same as `Team Contributor` but the `Team Admin` can also manage the users in that team, and manage
+the team's holdouts.
### Assigning Team roles
@@ -117,6 +118,26 @@ Global `FullAdmin` or users with `Team Admin` on that team, can invite users to
---
+## Holdouts
+
+Holdouts are Experiment Assets and follow the team-based model. Because a holdout takes traffic from
+every experiment of the teams that own it, the built-in team roles grant less on holdouts than on
+other assets:
+
+- **Team Admin**: creates, edits, starts, stops, archives and views the team's holdouts.
+- **Team Contributor** and **Team Viewer**: view the team's holdouts only.
+
+Holdouts are always owned by teams, never by individual users. A holdout can be owned by several
+teams, and it covers the experiments of all of them.
+
+Only users who can edit a holdout can share it with **Can Edit**. On a holdout, **Can View** lets
+users find it and view its results, but not use it.
+
+See [Holdout permissions](/docs/web-console-docs/holdout/overview#permissions) for the details and
+the full list of permissions.
+
+---
+
## Ownership and Permissions model for Experiment Assets
Read our [The Ownership Model](./ownership-and-permissions) for a more detailed explanation on how to manage ownership and permissions for Experiment Assets.
diff --git a/static/img/holdout/configure-holdout.png b/static/img/holdout/configure-holdout.png
new file mode 100644
index 00000000..dd5d945a
Binary files /dev/null and b/static/img/holdout/configure-holdout.png differ
diff --git a/static/img/holdout/holdout-iterations.png b/static/img/holdout/holdout-iterations.png
new file mode 100644
index 00000000..bd4486e5
Binary files /dev/null and b/static/img/holdout/holdout-iterations.png differ
diff --git a/static/img/holdout/holdout-results.png b/static/img/holdout/holdout-results.png
new file mode 100644
index 00000000..52eb8fef
Binary files /dev/null and b/static/img/holdout/holdout-results.png differ
diff --git a/static/img/holdout/holdouts-list.png b/static/img/holdout/holdouts-list.png
new file mode 100644
index 00000000..24865ce8
Binary files /dev/null and b/static/img/holdout/holdouts-list.png differ