Attakay78 · Attakay78 · Mar 24, 2026 · Mar 24, 2026
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 <div align="center">
   <img src="api-shield-logo.svg" alt="API Shield" width="600"/>
 
-  <p><strong>Route(API) lifecycle management for ASGI Python web frameworks — maintenance mode, environment gating, deprecation, rate limiting, admin panels, and more. No restarts required.</strong></p>
+  <p><strong>Route(API) lifecycle management for ASGI Python web frameworks — maintenance mode, environment gating, deprecation, rate limiting, feature flags, admin panels, and more. No restarts required.</strong></p>
 
   <a href="https://pypi.org/project/api-shield"><img src="https://img.shields.io/pypi/v/api-shield?color=F59E0B&label=pypi&cacheSeconds=300" alt="PyPI"></a>
   <a href="https://pypi.org/project/api-shield"><img src="https://img.shields.io/pypi/pyversions/api-shield?color=F59E0B" alt="Python versions"></a>
@@ -33,6 +33,7 @@ These features are framework-agnostic and available to any adapter.
 | ⏰ **Scheduled windows** | `asyncio`-native scheduler — maintenance windows activate and deactivate automatically |
 | 🔔 **Webhooks** | Fire HTTP POST on every state change — built-in Slack formatter and custom formatters supported |
 | 🚦 **Rate limiting** | Per-IP, per-user, per-API-key, or global counters — tiered limits, burst allowance, runtime mutation |
+| 🚩 **Feature flags** | Boolean, string, integer, float, and JSON flags — targeting rules, user segments, percentage rollouts, prerequisites, and a live evaluation stream. Built on the [OpenFeature](https://openfeature.dev/) standard |
 | 🏗️ **Shield Server** | Centralised control plane for multi-service architectures — SDK clients sync state via SSE with zero per-request latency |
 | 🌐 **Multi-service CLI** | `SHIELD_SERVICE` env var scopes every command; `shield services` lists connected services |
 
@@ -193,6 +194,70 @@ Requires `api-shield[rate-limit]`. Powered by [limits](https://limits.readthedoc
 
 ---
 
+## Feature flags
+
+api-shield ships a full feature flag system built on the [OpenFeature](https://openfeature.dev/) standard. All five flag types, multi-condition targeting rules, user segments, percentage rollouts, and a live evaluation stream — managed from the dashboard or CLI with no code changes.
+
+```python
+from shield.core.feature_flags.models import (
+    FeatureFlag, FlagType, FlagVariation, RolloutVariation,
+    TargetingRule, RuleClause, Operator, EvaluationContext,
+)
+
+engine.use_openfeature()
+
+# Define a boolean flag with a 20% rollout and individual targeting
+await engine.save_flag(
+    FeatureFlag(
+        key="new-checkout",
+        name="New Checkout Flow",
+        type=FlagType.BOOLEAN,
+        variations=[
+            FlagVariation(name="on",  value=True),
+            FlagVariation(name="off", value=False),
+        ],
+        off_variation="off",
+        fallthrough=[
+            RolloutVariation(variation="on",  weight=20_000),  # 20%
+            RolloutVariation(variation="off", weight=80_000),  # 80%
+        ],
+        targets={"on": ["beta_tester_1"]},   # individual targeting
+        rules=[
+            TargetingRule(
+                description="Enterprise users always get the new flow",
+                clauses=[RuleClause(attribute="plan", operator=Operator.IS, values=["enterprise"])],
+                variation="on",
+            )
+        ],
+    )
+)
+
+# Evaluate in an async route handler
+ctx = EvaluationContext(key=user_id, attributes={"plan": user.plan})
+enabled = await engine.flag_client.get_boolean_value("new-checkout", False, ctx)
+
+# Evaluate in a sync def handler (thread-safe)
+enabled = engine.sync.flag_client.get_boolean_value("new-checkout", False, {"targeting_key": user_id})
+```
+
+Manage flags and segments from the CLI:
+
+```bash
+shield flags list
+shield flags eval new-checkout --user user_123
+shield flags disable new-checkout          # kill-switch
+shield flags enable new-checkout
+shield flags stream                        # live evaluation events
+
+shield segments create beta_users --name "Beta Users"
+shield segments include beta_users --context-key user_123,user_456
+shield segments add-rule beta_users --attribute plan --operator in --values pro,enterprise
+```
+
+Requires `api-shield[flags]`.
+
+---
+
 ## Framework support
 
 api-shield is built on the **ASGI** standard. The core (`shield.core`) is completely framework-agnostic and has zero framework imports. Any ASGI framework can be supported — either via a Starlette `BaseHTTPMiddleware` (for Starlette-based frameworks) or a raw ASGI callable for frameworks like Quart and Django that implement the ASGI spec independently.
@@ -265,6 +330,7 @@ Full documentation at **[attakay78.github.io/api-shield](https://attakay78.githu
 | [Tutorial](https://attakay78.github.io/api-shield/tutorial/installation/) | Get started in 5 minutes |
 | [Decorators reference](https://attakay78.github.io/api-shield/reference/decorators/) | All decorator options |
 | [Rate limiting](https://attakay78.github.io/api-shield/tutorial/rate-limiting/) | Per-IP, per-user, tiered limits |
+| [Feature flags](https://attakay78.github.io/api-shield/tutorial/feature-flags/) | Targeting rules, segments, rollouts, live events |
 | [ShieldEngine reference](https://attakay78.github.io/api-shield/reference/engine/) | Programmatic control |
 | [Backends](https://attakay78.github.io/api-shield/tutorial/backends/) | Memory, File, Redis, Shield Server, custom |
 | [Admin dashboard](https://attakay78.github.io/api-shield/tutorial/admin-dashboard/) | Mounting ShieldAdmin |

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -15,6 +15,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ### Added
 
+- **Feature flags** (`api-shield[flags]`): a full feature flag system built on the [OpenFeature](https://openfeature.dev/) standard, supporting boolean, string, integer, float, and JSON flag types with multi-condition targeting rules, reusable user segments (explicit included/excluded lists plus attribute-based rules), percentage rollouts, prerequisite flags, individual user targeting, and a live SSE evaluation stream. Flags and segments are manageable from the admin dashboard (`/shield/flags`, `/shield/segments`) and the CLI (`shield flags *`, `shield segments *`) — including a new `shield segments add-rule` command and an "Add Rule" panel in the Edit Segment modal that lets operators add attribute-based targeting rules without touching code or the REST API directly.
+
 - **`SHIELD_SERVICE` env var fallback on all `--service` CLI options**: `shield status`, `shield enable`, `shield disable`, `shield maintenance`, and `shield schedule` all read `SHIELD_SERVICE` automatically — set it once with `export SHIELD_SERVICE=payments-service` and every command scopes itself to that service without repeating `--service`. An explicit `--service` flag always wins.
 - **`shield current-service` command**: shows the active service context from the `SHIELD_SERVICE` environment variable, or a hint to set it when the variable is absent.
 - **`shield services` command**: lists all distinct service names registered with the Shield Server, so you can discover which services are connected before switching context.

diff --git a/docs/index.md b/docs/index.md
@@ -104,6 +104,7 @@ These features are framework-agnostic and available to every adapter.
 | ⏰ **Scheduled windows** | `asyncio`-native scheduler that activates and deactivates maintenance windows automatically |
 | 🔔 **Webhooks** | Fire HTTP POST on every state change, with a built-in Slack formatter and support for custom formatters |
 | 🚦 **Rate limiting** | Per-IP, per-user, per-API-key, or global counters with tiered limits, burst allowance, and runtime policy mutation |
+| 🚩 **Feature flags** | Boolean, string, integer, float, and JSON flags with targeting rules, user segments, percentage rollouts, prerequisites, and a live evaluation stream — built on the OpenFeature standard |
 
 ### Framework adapters
 
@@ -162,7 +163,9 @@ api-shield is an **ASGI-native** library. The core (`shield.core`) is framework-
 - [**Tutorial: Installation**](tutorial/installation.md): get up and running in seconds
 - [**Tutorial: First Decorator**](tutorial/first-decorator.md): put your first route in maintenance mode
 - [**Tutorial: Rate Limiting**](tutorial/rate-limiting.md): per-IP, per-user, tiered limits, and more
+- [**Tutorial: Feature Flags**](tutorial/feature-flags.md): targeting rules, segments, rollouts, and live events
 - [**Reference: Decorators**](reference/decorators.md): full decorator API
 - [**Reference: Rate Limiting**](reference/rate-limiting.md): `@rate_limit` parameters, models, and CLI commands
 - [**Reference: ShieldEngine**](reference/engine.md): programmatic control
+- [**Reference: Feature Flags**](reference/feature-flags.md): full flag/segment API, models, and CLI commands
 - [**Reference: CLI**](reference/cli.md): all CLI commands