Workspace governance

docs/.vitepress/config.ts

@@ -399,6 +399,7 @@ if(n<200&&document.readyState==="loading")requestAnimationFrame(function(){bar(n
               },
             ],
           },
+          { text: "Workspace Governance", link: "/workspace-administration/workspace-governance" },
           {
             text: "Authentication",
             collapsed: true,

docs/automations/custom-automations.md

@@ -17,6 +17,26 @@ Every custom automation has three components. When [trigger] happens, if [condit
 - **Conditions** are optional filters that must be satisfied for the automation to proceed. If you add multiple conditions, all of them must be met (AND logic).
 - **Actions** are what the automation does when fired. Multiple actions execute in sequence.
 
+## Where automations live depends on your plan
+
+Every plan builds automations the same way, with the same triggers, conditions, and actions. What differs is **where** they are configured, **which projects** they can act on, and **which actions** are available. Find your setup below.
+
+| Plan / setup                                                                                    | Where you configure automations                                | What you get                                                                                                                                                             |
+| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Business**                                                                                    | Inside each project, under **Project Settings → Automations**  | Custom automations scoped to one project, with the **Change property** and **Add comment** actions.                                                                      |
+| **Enterprise Grid** (project-managed)                                                           | Project settings, plus **Workspace Settings → Automations**    | Everything above, plus **workspace automations** that span all projects or a chosen subset, the **Send webhook** and **Run script** actions, and **scheduled** triggers. |
+| **Enterprise Grid with [Workspace Governance](/workspace-administration/workspace-governance)** | Once for the whole workspace, under **Settings → Automations** | Automations are managed centrally by a workspace admin and applied to projects. Project admins no longer create or edit automations inside a project.                    |
+
+**In short**
+
+- On **Business**, automations live in **project settings** and act on that one project.
+- On **Enterprise Grid without governance**, you keep project automations and can also create **workspace automations** and use the webhook and script actions.
+- On **Enterprise Grid with [Workspace Governance](/workspace-administration/workspace-governance)**, automation management moves to the **workspace level**. Project admins can no longer edit automations inside a project. See [Automations under workspace g`overnance](#automations-under-workspace-governance).
+
+:::warning Turning on governance moves automations to the workspace
+Enabling Workspace Governance is a one-way change that relocates automation management from individual projects to the workspace. Existing project automations are migrated up and keep running. Read [Workspace Governance](/workspace-administration/workspace-governance) before enabling it.
+:::
+
 ## Create a custom project automation
 
 Project automations apply to work items within a single project.
@@ -291,6 +311,18 @@ Conditions are what make an automation surgical. They let you say "only run this
 
 One thing worth knowing: when a work item is first created, some fields like assignees and labels can take a moment to register, even if someone filled them in during creation. Plane handles this - it checks the latest state of those fields before evaluating your conditions, so a filter like "assignee is X" on a creation trigger will work as expected.
 
+## Automations under workspace governance <Badge type="warning" text="Enterprise Grid" />
+
+On **Enterprise Grid with [Workspace Governance](/workspace-administration/workspace-governance)** enabled, automations are managed once for the entire workspace instead of project by project. A workspace admin owns all automation configuration, and project admins can no longer create or edit automations inside a project.
+
+You build these automations exactly as described above. This section covers only what's different when governance is on:
+
+- **Project-level automation editing is locked.** Project admins can no longer create or edit automations inside a project. Opening an automation in a project shows it as read-only, with a message that automations are managed at the workspace level.
+- **Existing project automations are preserved.** When governance is enabled, each project's automations are migrated up to the workspace level and scoped back to their original project, so they keep running exactly as before.
+- **All automations are managed centrally.** A workspace admin creates and edits every automation under **Settings → Automations**, choosing whether each one applies to all projects or a specific subset.
+
+See [Workspace governance](/workspace-administration/workspace-governance) for the full picture of what centralizes and what changes for projects.
+
 ## Common use cases
 
 Some common things people use automations for.

docs/core-concepts/issues/states.md

@@ -1,14 +1,25 @@
 ---
-title: Workflow States
+title: Work Item States
 description: Manage work item progress with customizable states in Plane. Organize tasks through backlog, unstarted, started, completed, and cancelled state groups.
 ---
 
 # Work Item States
 
 Managing work items effectively is at the heart of every project, and Plane provides a robust system for organizing them into states that represent the stages of a work item's lifecycle. As work items transition through these states—from backlog to completion—they reflect the progression of work in your project, forming a clear and efficient workflow for your team.
 
+## Where to configure states
+
+Each project defines its own states, managed by a **project admin** under **Settings → (project) → States**. This is the default.
+
+**Enterprise Grid - workspace level**  
+With [workspace governance](/workspace-administration/workspace-governance) enabled, states become a single shared set for the whole workspace, managed by a **workspace admin** under **Workspace Settings → States**, then applied to every project. Project admins use the shared set but can't edit it. See [Under Enterprise Grid governance](#under-enterprise-grid-governance).
+
+The concept and most mechanics are identical either way; only where you configure them, who can, and a few behaviors differ.
+
 ## State groups
 
+Every state belongs to one of five groups. The group is the meaning Plane attaches to the state; the name is your label for it.
+
 ![Work item states](https://media.docs.plane.so/projects/issue-states.webp#hero)
 
 Plane organizes work item states into five primary groups, each serving a distinct purpose in your project’s workflow:
@@ -27,27 +38,86 @@ Plane organizes work item states into five primary groups, each serving a distin
 
 - **Cancelled**: Use this group for work items that are no longer relevant or actionable. Plane provides a default state called **Cancelled** for this purpose.
 
-## Customize states
+### What groups drive
+
+The group, not the state name, determines behavior across Plane:
+
+- **Completion and progress** - only work items in the **Completed** group count as done. Cycle and module progress, burndown, and analytics bucket work items by group.
+- **Archiving** - only work items in **Completed** or **Cancelled** states are eligible for automatic archiving.
+- **Ordering** - states sort by group first, then by position within the group.
+
+Because of this, **changing a state's group changes how its work items are counted**. Moving a state into Completed, for example, makes its work items count as done in every chart and progress bar.
+
+## The default state
+
+Exactly one state is the **default** - the state new work items get when none is chosen. New projects start with Backlog as the default.
+
+To change it, open a state and choose **Mark as default**. The previous default is cleared automatically; there is always exactly one.
+
+::: info **Enterprise Grid**
+The default is not a flag on the state and there is no "Mark as default." The default is the **starting state of the workflow**, set on the [Workflows](/workflows-and-approvals/workflows) page. A governed workspace's default workflow starts at **Todo**.
+:::
+
+## Triage state
 
-You can customize each state group to match your project's workflow by adding, editing, or removing states.
+Triage is a special, system-managed state used as the holding area for [intake](#) submissions - items land in Triage before being accepted into the project's normal flow.
 
-Navigate to the **States** tab under **Project > Settings**.
+- There is **one triage state per project**, or **one per workspace** under governance.
+- **"Triage" is a reserved name** - you cannot name a state Triage.
+- You **cannot create** a state in the Triage group, and you **cannot delete** the triage state.
+- Triage is kept out of normal state lists and excluded from analytics.
 
-![Modify states](https://media.docs.plane.so/projects/project-new-state.webp#hero)
+## Manage states
 
-### Add state
+States are shown grouped. Use the **+** on a group to add a state to it.
+
+**Create** - set a **name**, a **color**, and an optional **description**. The group is determined by which group you add the state under. A duplicate name is rejected.
+
+::: info **Enterprise Grid:**
+State names must be unique across the **whole workspace**, and the check is **case-insensitive** - "Todo" and "todo" are treated as the same. (When governance is first enabled, same-named states from different projects are merged into one.)
+:::
+
+**Edit** - change the name, color, or description at any time. To change a state's group, drag it into another group.
+
+**Reorder and regroup** - drag a state to reorder it within its group, or drag it into a different group to reassign it. You **cannot drag away the last state in a group** - every group must keep at least one state.
+
+**Delete** - remove a state, subject to these rules:
+
+- The **default state cannot be deleted**. Set a different default first.
+- A state with **work items cannot be deleted** - there is no automatic reassignment. Move its work items to another state first, then delete it.
+- The **triage state cannot be deleted**.
+- A group's **last remaining state cannot be deleted**.
+
+Deleting a state is permanent.
+
+:::info **Enterprise Grid**
+A state also **cannot be deleted while a workflow uses it** - the error names the workflows. Remove the state from those workflows first. Project admins cannot create, edit, or delete states at all; state management happens at the workspace level.
+:::
+
+## Restricting work item creation in a state
+
+Whether work items can be created directly in a given state is a **workflow** setting, not a property of the state itself. In a workflow, each state has an **allow work item creation** toggle; turn it off for states that should only be reached by moving an existing work item (like "Done"). See [Workflows](/workflows-and-approvals/workflows).
+
+---
 
-1. Click the "+" button next to the group where you want the new state.
-2. Rearrange states within the group to reflect your preferred workflow.
+## Under workspace governance
 
-You can also designate a state as the default for the project. New work items without an assigned state will automatically fall into this default state.
+When governance is on, states are a single **shared catalog** for the whole workspace:
 
-### Edit state
+- One shared set that every governed project draws from. A project's visible states are the ones used by the workflows its work item types resolve to.
+- Names are unique across the workspace, case-insensitive.
+- One workspace triage state.
+- The default concept moves to the workflow's starting state.
+- Project admins cannot edit states; deleting a catalog state is blocked while a workflow references it.
 
-1. Hover over the state you want to edit.
-2. Click the pencil icon and change the name and description.
-3. Click **Update** to save changes.
+See [Workspace governance](/workspace-administration/workspace-governance) for how governance works overall.
 
-### Delete state
+## Warnings and limitations
 
-Before removing a state, ensure no work items are currently assigned to it. Once it's clear, you can delete the state by clicking the **x** icon on the state.
+- **The default state cannot be deleted** - reassign the default first.
+- **A state with work items cannot be deleted** - move those work items first; there is no automatic reassignment.
+- **Every group must keep at least one state.**
+- **"Triage" is reserved** and cannot be created as a group or deleted.
+- **State names must be unique** - within the project, or across the workspace (case-insensitive) under governance.
+- **Changing a state's group re-buckets its work items** for progress, analytics, and archiving.
+- **Under governance**, a catalog state can't be deleted while a workflow references it, and project admins can no longer edit states.