docs: Managing Flags section

README.md

@@ -19,7 +19,7 @@
 
 # [Flagsmith](https://flagsmith.com/) is an Open-Source Feature Flagging Tool to Ship Faster & Control Releases 
 
-Change the way your team releases software. Roll out, segment, and optimise—with granular control. Stay secure with on-premise and private cloud hosting.
+Change the way your team releases software. Roll out, segment, and optimise—with granular control. Stay secure with on-premise and private cloud hosting. 
 
 * Feature flags: Release features behind the safety of a feature flag
 * Make changes remotely: Easily toggle individual features on and off, and make changes without deploying new code

docs/docs/managing-flags/_category_.json

@@ -0,0 +1,4 @@
+{
+    "label": "Managing Flags",
+    "position": 10
+}

docs/docs/managing-flags/core-management.md

@@ -0,0 +1,90 @@
+---
+title: Core Management
+sidebar_label: Core Management
+sidebar_position: 1
+---
+
+Flags in Flagsmith are used to categorise and monitor user actions or events, such as detecting spam or abuse. This guide covers how to create, edit, clone, and delete flags in your project.
+
+---
+
+## Creating a Flag
+
+To create a new feature flag:
+
+1. Go to the **Features** section in your dashboard.
+2. Click **Create Feature**.
+3. Enter a descriptive name for your flag (e.g., `new_ui_enabled`).
+4. Fill in the available fields according to the specifications of your feature. Note that these values are applied to all your [environments]. You can edit each environment individually later.
+    - **Enabled by default**: determines the initial state of the flag for all environments. This can be edited for each environment later.
+    - **Value** (optional): additionally to their boolean value, you can choose a format and a value for your flag.
+    - **Tags** (optional): organise your flags by tags or add `protected` to prevent them from accidentally being deleted.
+    - **Description** (optional): add a feature flag description.
+    - **Server-side only**: enabling this prevents your flag from being accessed by client-side SDKs.
+5. Click **Create Feature**.
+
+:::tip
+
+By clicking the **Create A/B/n Test** button, you can define values for A/B testing. To learn more about this operation, refer to the [A/B Testing guide](../advanced-use/ab-testing).
+
+:::
+
+---
+
+## Editing a Flag
+
+You create feature flags once per project, but you edit them within each environment. To edit an existing flag:
+
+1. While on the **Environments** tab on the dashboard, use the dropdown to select the environment where you want to apply the changes.
+2. Locate the feature flag you want to edit and click on it. You can use the search bar to find the flag by its name.
+
+:::tip
+
+If you just want to toggle the feature flag *on* or *off*, use the switch under the **View** column in the list view.
+
+:::
+
+3. On the **Value** tab, you can set the flag to be on or off, as well as edit a value for it. Click **Update Feature Value** to save your changes.
+4. Optionally, create segment-specific features and define **segment overrides**. Refer to the documentation to learn more about [segments](../basic-features/segments.md). Save any changes by clicking the **Update Segment Overrides** button.
+5. On the **Settings** tab, you can:
+    - Add tags to your feature flag.
+    - Assign it to specific *users* and *groups*.
+    - Update the flag's description.
+    - Mark the flag as **Server-side only** to prevent it from being accessed by client-side SDKs.
+    - Set the **Archived** status to filter the flag as no longer relevant. Note that the flag will still be returned by the endpoint as before.
+  Click **Update Settings** to save your changes.
+
+:::tip
+
+Changes made in the **Settings** tab affect all environments. Changes made in other tabs while editing a feature flag are valid only for the selected environment.
+
+:::
+
+---
+
+## Deleting a Flag
+
+To delete a feature flag:
+
+1. In the **Features** section, locate the flag you want to remove and click the **three dots** icon on the right.
+2. Select the **Remove feature** option.
+3. Type in the name of the feature to confirm the deletion.
+
+:::caution
+
+Deleting a flag is permanent and cannot be undone. Make sure your applications do not contain any reference to this feature before confirming deleting it.
+
+:::
+
+---
+
+## Troubleshooting
+
+### Flags Not Updating
+
+- Make sure you have saved your changes in each tab of the edit feature flag panel.
+- Check that you are in the correct project and environment.
+
+### Permission Issues
+
+- You may need additional permissions to create, edit, clone, or delete flags. If you see permission errors or options are disabled, contact your Flagsmith administrator to review your access rights. For more information, see the [Permissions and Roles](../system-administration/rbac.md) page.

docs/docs/managing-flags/manage-flags/_category_.json

@@ -0,0 +1,4 @@
+{
+    "label": "Manage Flags",
+    "position": 10
+}

docs/docs/managing-flags/manage-flags/feature-health-metrics.md

@@ -0,0 +1,119 @@
+---
+title: Feature Health Metrics
+sidebar_label: Feature Health Metrics
+sidebar_position: 4
+---
+
+Feature health enables you to monitor observability metrics within Flagsmith, specifically in relation to your features and environments. When your observability provider sends alert notifications, Flagsmith can mark features (and optionally environments) as **unhealthy**, providing details about the alerts. This assists your team in responding quickly and making informed decisions.
+
+:::info
+
+Feature Health is in Beta, please email support@flagsmith.com or chat with us <a href="#" class="open-chat" data-crisp-chat-message="Hello, I'm interested in joining the feature health beta.">here</a> if you'd like to join. 
+
+:::
+
+## Prerequisites
+
+- You must have a supported observability provider (see below).
+- You need admin access to your Flagsmith project settings.
+
+---
+
+## How to enable Feature Health
+
+1. Go to your **Project Settings** in Flagsmith.
+2. Navigate to the **Feature Health** section.
+3. Choose your desired provider from the **Provider Name** drop-down menu (e.g., Grafana/Prometheus Alertmanager or Sample).
+4. Click **Create** and copy the webhook URL.
+
+---
+
+## How to integrate with Feature Health providers
+
+### Grafana / Prometheus Alertmanager
+
+[Learn more](/integrations/apm/grafana/#feature-health-provider-setup) about configuring Grafana / Prometheus Alertmanager feature health provider.
+
+### Sample Provider
+
+We provide a Sample Provider for your custom integrations. To create a Sample Feature Health webhook:
+
+1. Go to Project Settings > Feature Health.
+2. Select "Sample" from the Provider Name drop-down menu.
+3. Click Create and copy the webhook URL.
+
+You can use the webhook in your custom integration. Refer to the payload schema below:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SampleEvent",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "type": "string"
+    },
+    "feature": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["healthy", "unhealthy"]
+    },
+    "reason": {
+      "$ref": "#/definitions/FeatureHealthEventReason"
+    }
+  },
+  "required": ["feature", "status"],
+  "definitions": {
+    "FeatureHealthEventReason": {
+      "type": "object",
+      "properties": {
+        "text_blocks": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FeatureHealthEventReasonTextBlock"
+          }
+        },
+        "url_blocks": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/FeatureHealthEventReasonUrlBlock"
+          }
+        }
+      }
+    },
+    "FeatureHealthEventReasonTextBlock": {
+      "type": "object",
+      "properties": {
+        "text": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        }
+      },
+      "required": ["text"]
+    },
+    "FeatureHealthEventReasonUrlBlock": {
+      "type": "object",
+      "properties": {
+        "url": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        }
+      },
+      "required": ["url"]
+    }
+  }
+}
+```
+
+---
+
+## What's next?
+
+- For more on observability integrations, see the [integrations documentation](/integrations/).
+- Need help or want to join the Beta? Contact [support@flagsmith.com](mailto:support@flagsmith.com) or chat with us in-app.

docs/docs/managing-flags/manage-flags/scheduled-flags.md

@@ -0,0 +1,55 @@
+---
+title: Scheduled Flags
+sidebar_label: Scheduled Flags
+sidebar_position: 3
+---
+
+Scheduled flags allow you to queue and automatically apply changes to feature flags at a specified future time, eliminating the need for manual intervention at the exact moment of change. This page shows you how to schedule flag changes.
+
+There are two methods for creating a scheduled flag change:
+
+- As part of a change request.
+- Directly while editing a feature flag, if change requests are not enforced.
+
+## Prerequisites
+
+- To schedule flag changes with a change request, you must [have change requests enabled](../../advanced-use/change-requests.md) in your environment. This is not necessary to directly schedule changes when editing a flag.
+- Scheduled flags are available only for our **Scale-up** and **Enterprise** plans.
+
+---
+
+## How to create a Scheduled Flag change as part of a Change Request
+
+1. Ensure your environment has change requests enabled.
+2. Attempt to change a flag value within the environment. You will be prompted to create a new change request.
+3. Fill in the following details:
+   - The title of the change request
+   - (Optional) A description of the reason for the change request
+   - The date and time at which you want the flag change to take effect
+4. Submit the change request. The scheduled change will appear in the change request area as 'Pending'.
+
+---
+
+## How to create a stand-alone scheduled flag change
+
+If change requests are not enabled for your environment, you can schedule a flag change directly:
+
+1. In the Features list view, go to the feature flag you want to edit.
+2. Choose the new value or state for the flag.
+3. Click the **Schedule Update** button to set the date and time for the change to take effect.
+4. Save your changes. The scheduled change will be queued and applied automatically at the specified time.
+
+---
+
+## Scheduled Flags and Change Requests
+
+Scheduled flags awaiting application will be listed in the change request area as 'Pending'.
+
+Once the scheduled date and time have passed and the flag change has been applied, the scheduled flag will automatically move to the 'Closed' list in the change request area.
+
+---
+
+## What's next?
+
+- To learn more about managing and approving changes to your flags, see the [change requests](../../advanced-use/change-requests.md) page.
+- To learn how to monitor the performance and health of your feature flags, see the [feature health metrics](./feature-health-metrics.md) page.

docs/docs/managing-flags/rollout/_category_.json

@@ -0,0 +1,4 @@
+{
+    "label": "Rollout",
+    "position": 10
+}

docs/docs/managing-flags/rollout/rollout-by-attribute.md

@@ -0,0 +1,58 @@
+---
+title: Rollout by Attribute
+sidebar_label: Rollout by Attribute
+sidebar_position: 1
+---
+
+This guide explains how to enable a feature for specific users based on their attributes (traits) in Flagsmith using segments and segment overrides. Attributes can include user role, subscription plan, application version, or device type.
+
+## Prerequisites
+
+- A Flagsmith project and environment.
+- A feature flag created in your project.
+- Your application's [Flagsmith SDK](../../clients/index.md) integrated and configured.
+
+## Steps
+
+### 1. Identify and Send User Traits
+
+Ensure your application is identifying users and sending their relevant attributes (traits) to Flagsmith. For example, you might send traits like `plan`, `email`, `platform`, or `version` using your SDK:
+
+```javascript
+flagsmith.identify('user_123');
+flagsmith.setTrait('plan', 'pro');
+flagsmith.setTrait('version', '5.4.1');
+```
+
+### 2. Create a Segment Based on Attribute(s)
+
+1. Go to the **Segments** section in the Flagsmith dashboard.
+2. Create a new segment and add rules that match the attribute(s) you want to target. For example:
+  - `plan = pro`
+  - `email Contains @yourcompany.com`
+  - `version SemVer >= 5.4.0`
+3. You can combine multiple rules for more precise targeting.
+
+### 3. Apply a Segment Override to Your Feature Flag
+
+1. In the environment where you want to apply the rollout, go to the **Features** section and select the feature you want to roll out.
+2. Navigate to the **Segment Overrides** tab.
+- Select the segment you created in the dropdown and set the desired flag state or value for users in that segment.
+- Save your changes.
+
+Done! Now you can test with users who match (and don’t match) the segment to ensure the feature is enabled/disabled as expected.
+
+---
+
+## Advanced Use Cases
+
+- You can combine attribute rules with a **% split** rule for staged rollouts (e.g., only 10% of "pro" users).
+- You can use operators such as `In`, `SemVer`, `Modulo`, etc., for more complex targeting.
+
+---
+
+## What's next
+
+- Read the [segments documentation](../../basic-features/segments.md) to understand how they work and their relationship with overrides.
+- See the [staged feature rollouts guide](./rollout-by-percentage.md) to combine attribute rules with percentage-based rollouts for gradual releases.
+- Understand [managing identities](../../basic-features/managing-identities.md) to ensure consistent user identification and attribute management across your application.