From 8240db4e272135272bf19f8475fb97920b5c2647 Mon Sep 17 00:00:00 2001
From: Aditya Thebe <contact@adityathebe.com>
Date: Fri, 21 Nov 2025 15:47:25 +0545
Subject: [PATCH 1/3] docs

---
 .../docs/guide/permissions/concepts/scope.md  | 92 ++++++++++++++++++
 .../examples/combining-selectors.md           | 38 ++++++++
 .../examples/global-resource-selectors.md     | 61 ++++++++++++
 .../docs/guide/permissions/examples/index.md  | 10 ++
 .../examples/multi-tenancy-patterns.md        | 94 +++++++++++++++++++
 .../examples/multiple-resource-types.md       | 34 +++++++
 .../examples/targeting-by-agent.md            | 16 ++++
 .../permissions/examples/targeting-by-tags.md | 23 +++++
 .../examples/targeting-canaries.md            | 17 ++++
 .../examples/targeting-specific-playbooks.md  | 11 +++
 .../examples/targeting-with-wildcards.md      | 20 ++++
 11 files changed, 416 insertions(+)
 create mode 100644 mission-control/docs/guide/permissions/concepts/scope.md
 create mode 100644 mission-control/docs/guide/permissions/examples/combining-selectors.md
 create mode 100644 mission-control/docs/guide/permissions/examples/global-resource-selectors.md
 create mode 100644 mission-control/docs/guide/permissions/examples/index.md
 create mode 100644 mission-control/docs/guide/permissions/examples/multi-tenancy-patterns.md
 create mode 100644 mission-control/docs/guide/permissions/examples/multiple-resource-types.md
 create mode 100644 mission-control/docs/guide/permissions/examples/targeting-by-agent.md
 create mode 100644 mission-control/docs/guide/permissions/examples/targeting-by-tags.md
 create mode 100644 mission-control/docs/guide/permissions/examples/targeting-canaries.md
 create mode 100644 mission-control/docs/guide/permissions/examples/targeting-specific-playbooks.md
 create mode 100644 mission-control/docs/guide/permissions/examples/targeting-with-wildcards.md

diff --git a/mission-control/docs/guide/permissions/concepts/scope.md b/mission-control/docs/guide/permissions/concepts/scope.md
new file mode 100644
index 00000000..0734f6ec
--- /dev/null
+++ b/mission-control/docs/guide/permissions/concepts/scope.md
@@ -0,0 +1,92 @@
+---
+title: Scopes
+sidebar_position: 4
+---
+
+Scopes define collections of resources that can be used for fine-grained access control in Mission Control. A Scope allows you to group resources by various criteria (agent, namespace, name, tags) and use these groups in permission rules to control who can access what resources.
+
+Scopes work as building blocks for [ABAC](abac.md) permission policies and enable [multi-tenancy](multi-tenancy.md) by allowing you to partition resources across different teams, environments, or organizational boundaries.
+
+## Core Concepts
+
+### Scope Structure
+
+A Scope consists of one or more **targets**, where each target defines a collection of resources. Multiple targets within a Scope are combined with **OR logic**, meaning a resource matches the Scope if it matches any of the targets.
+
+:::info
+Each target must specify exactly **one** resource type. You cannot mix different resource types within a single target.
+:::
+
+### Resource Selectors
+
+Each target uses a `ScopeResourceSelector` to filter resources. The selector supports four fields:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `agent` | Filter by agent ID or name | `agent-prod-1` |
+| `namespace` | Filter by Kubernetes namespace | `production` |
+| `name` | Filter by resource name. Supports wildcard `*` to match any resource | `nginx-*` is **NOT** supported, but `*` matches all |
+| `tagSelector` | Filter by tags using label selector syntax | `env=prod,region=us-west` |
+
+:::info Wildcard Limitations
+The `name` field supports only the special wildcard directive `*` which matches **any** resource. Prefix and suffix wildcards (e.g., `nginx-*` or `*-prod`) are **NOT** supported.
+:::
+
+### Resource Types
+
+Scopes can target six different resource types:
+
+1. **`config`** - Configuration items from config-db
+2. **`component`** - Topology components from the catalog
+3. **`playbook`** - Runnable playbooks and automation
+4. **`canary`** - Health checks and synthetic monitors
+5. **`view`** - Custom dashboards and views
+6. **`global`** - Wildcard selector that applies to all resource types
+
+## Integration with ABAC
+
+Scopes are designed to work seamlessly with [Attribute-Based Access Control (ABAC)](abac.md). When using ABAC, you reference Scopes in your permission policies to define the resource boundaries for access control.
+
+```yaml
+apiVersion: mission-control.flanksource.com/v1
+kind: Permission
+metadata:
+  name: dev-team-access
+spec:
+  subjects:
+    - kind: Group
+      name: dev-team
+  scopes:
+    - prod-agent-configs  # Reference to Scope
+  actions:
+    - read
+    - update
+```
+
+This permission grants the `dev-team` group read and update access to all resources defined in the `prod-agent-configs` Scope.
+
+### Scope Evaluation
+
+When a user attempts to access a resource:
+
+1. The system evaluates all Scopes referenced in the user's permissions
+2. If the resource matches any target in any of the user's Scopes, access is granted (subject to action restrictions)
+3. Multiple Scopes are combined with OR logic
+
+## Integration with Multi-Tenancy
+
+Scopes are fundamental to implementing [multi-tenancy](multi-tenancy.md) in Mission Control. They allow you to partition resources across different tenants, teams, or organizational units.
+
+Common multi-tenancy patterns include:
+- **Environment Isolation** - Separate Scopes for dev, staging, and production environments
+- **Team-Based Isolation** - Partition resources by team using namespaces or agents
+- **Customer Isolation** - For SaaS scenarios, isolate customer resources by tags or agents
+
+See the [multi-tenancy patterns examples](../examples/multi-tenancy-patterns.md) for detailed implementation patterns.
+
+## See Also
+
+- [Scope Examples](../examples) - Practical examples of Scope configurations
+- [Attribute-Based Access Control (ABAC)](abac.md) - Using Scopes in permission policies
+- [Multi-Tenancy](multi-tenancy.md) - Implementing tenant isolation with Scopes
+- [Permission Actions](/reference/permissions/actions) - Available actions for Scope-based permissions
diff --git a/mission-control/docs/guide/permissions/examples/combining-selectors.md b/mission-control/docs/guide/permissions/examples/combining-selectors.md
new file mode 100644
index 00000000..b45019e1
--- /dev/null
+++ b/mission-control/docs/guide/permissions/examples/combining-selectors.md
@@ -0,0 +1,38 @@
+---
+title: Combining Selectors
+---
+
+Within a single `ScopeResourceSelector`, you can combine multiple fields. All specified fields must match (AND logic).
+
+```yaml
+apiVersion: mission-control.flanksource.com/v1
+kind: Scope
+metadata:
+  name: prod-west-configs
+  namespace: default
+spec:
+  description: Production configs in us-west region from specific agent
+  targets:
+    - config:
+        agent: agent-west-1
+        namespace: production
+        tagSelector: "region=us-west"
+```
+
+This target matches configs that:
+- Come from `agent-west-1` **AND**
+- Are in the `production` namespace **AND**
+- Have the tag `region=us-west`
+
+All three conditions must be satisfied for a config to match this target.
+
+**Use Cases:**
+- Highly specific resource filtering
+- Regional + environment isolation
+- Agent-specific namespaced resources
+- Complex compliance requirements
+
+**Selector Logic Summary:**
+- Fields within a single selector: **AND** logic (all must match)
+- Multiple targets in a Scope: **OR** logic (any target can match)
+- Multiple tags in `tagSelector`: **AND** logic (all tags must match)
diff --git a/mission-control/docs/guide/permissions/examples/global-resource-selectors.md b/mission-control/docs/guide/permissions/examples/global-resource-selectors.md
new file mode 100644
index 00000000..d3ba1341
--- /dev/null
+++ b/mission-control/docs/guide/permissions/examples/global-resource-selectors.md
@@ -0,0 +1,61 @@
+---
+title: Global Resource Selectors
+---
+
+The `global` resource type creates a Scope that applies to all resource types simultaneously. This is useful for namespace-wide or agent-wide restrictions.
+
+```yaml
+apiVersion: mission-control.flanksource.com/v1
+kind: Scope
+metadata:
+  name: namespace-restricted
+  namespace: default
+spec:
+  description: All resources in specific namespace
+  targets:
+    - global:
+        namespace: restricted-zone
+```
+
+This Scope matches configs, components, playbooks, canaries, and views in the `restricted-zone` namespace.
+
+## When to Use Global Selectors
+
+**Use global selectors when:**
+- Applying namespace-based isolation across all resource types
+- Creating agent-wide restrictions
+- Implementing broad organizational boundaries
+- Simplifying Scope definitions for common patterns
+
+**Avoid global selectors when:**
+- You need fine-grained control per resource type
+- Different resource types have different access requirements
+- You want to apply different tag filters to different resource types
+
+## Global vs. Multiple Targets
+
+These two Scopes are functionally equivalent:
+
+**Using global:**
+```yaml
+targets:
+  - global:
+      namespace: myapp
+```
+
+**Using individual targets:**
+```yaml
+targets:
+  - config:
+      namespace: myapp
+  - component:
+      namespace: myapp
+  - playbook:
+      namespace: myapp
+  - canary:
+      namespace: myapp
+  - view:
+      namespace: myapp
+```
+
+The `global` approach is more concise but less flexible if you later need to apply different filters to different resource types.
diff --git a/mission-control/docs/guide/permissions/examples/index.md b/mission-control/docs/guide/permissions/examples/index.md
new file mode 100644
index 00000000..5bd099a0
--- /dev/null
+++ b/mission-control/docs/guide/permissions/examples/index.md
@@ -0,0 +1,10 @@
+---
+title: Examples
+sidebar_position: 5
+sidebar_custom_props:
+  icon: tutorial
+---
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />
diff --git a/mission-control/docs/guide/permissions/examples/multi-tenancy-patterns.md b/mission-control/docs/guide/permissions/examples/multi-tenancy-patterns.md
new file mode 100644
index 00000000..b61de4bf
--- /dev/null
+++ b/mission-control/docs/guide/permissions/examples/multi-tenancy-patterns.md
@@ -0,0 +1,94 @@
+---
+title: Multi-Tenancy Patterns
+---
+
+Scopes are fundamental to implementing multi-tenancy in Mission Control. Here are common patterns for partitioning resources across different tenants, teams, or organizational units.
+
+## Environment Isolation
+
+Create separate Scopes for different environments to prevent accidental changes to production:
+
+```yaml
+apiVersion: mission-control.flanksource.com/v1
+kind: Scope
+metadata:
+  name: production-resources
+  namespace: default
+spec:
+  description: All production resources
+  targets:
+    - config:
+        tagSelector: "env=production"
+    - component:
+        tagSelector: "env=production"
+    - playbook:
+        tagSelector: "env=production"
+```
+
+Grant developers read-only access to production resources and full access to development resources.
+
+## Team-Based Isolation
+
+Partition resources by team using namespace or agent:
+
+```yaml
+apiVersion: mission-control.flanksource.com/v1
+kind: Scope
+metadata:
+  name: platform-team-resources
+  namespace: default
+spec:
+  description: Resources managed by platform team
+  targets:
+    - config:
+        namespace: platform-team
+    - component:
+        namespace: platform-team
+```
+
+Each team gets their own namespace, and Scopes ensure teams can only access their designated resources.
+
+## Customer Isolation (SaaS)
+
+For SaaS scenarios, isolate customer resources by agent or tags:
+
+```yaml
+apiVersion: mission-control.flanksource.com/v1
+kind: Scope
+metadata:
+  name: customer-acme-resources
+  namespace: default
+spec:
+  description: All resources for ACME Corp
+  targets:
+    - config:
+        tagSelector: "customer=acme"
+```
+
+Each customer's resources are tagged appropriately, and Scopes ensure customer data isolation.
+
+## Multi-Dimensional Isolation
+
+Combine multiple isolation dimensions (environment + team + region):
+
+```yaml
+apiVersion: mission-control.flanksource.com/v1
+kind: Scope
+metadata:
+  name: team-a-prod-west
+  namespace: default
+spec:
+  description: Team A production resources in west region
+  targets:
+    - config:
+        namespace: team-a
+        tagSelector: "env=production,region=west"
+```
+
+This provides granular control for complex organizational structures.
+
+**Key Principles:**
+- Use consistent tagging strategies across all resources
+- Document your tenant isolation model
+- Start with broader Scopes and refine as needed
+- Combine Scopes with [ABAC](../concepts/abac.md) policies for complete access control
diff --git a/mission-control/docs/guide/permissions/examples/multiple-resource-types.md b/mission-control/docs/guide/permissions/examples/multiple-resource-types.md
new file mode 100644
index 00000000..2de48b8b
--- /dev/null
+++ b/mission-control/docs/guide/permissions/examples/multiple-resource-types.md
@@ -0,0 +1,34 @@
+---
+title: Multiple Resource Types
+---
+
+A single Scope can include multiple resource types by using multiple targets. Each target must specify exactly one resource type, and targets are combined with OR logic.
+
+```yaml
+apiVersion: mission-control.flanksource.com/v1
+kind: Scope
+metadata:
+  name: monitoring-stack
+  namespace: default
+spec:
+  description: Complete monitoring stack resources
+  targets:
+    - config:
+        tagSelector: "app=prometheus"
+    - component:
+        tagSelector: "app=prometheus"
+    - canary:
+        tagSelector: "app=prometheus"
+```
+
+This Scope includes configs, components, and canaries that all have the tag `app=prometheus`. A resource matches the Scope if it matches **any** of the three targets.
+
+**Use Cases:**
+- Application stack ownership (all resources for an app)
+- Feature-based access (configs + playbooks for a feature)
+- Platform team permissions (infrastructure + monitoring)
+- Cross-cutting concerns (observability resources across types)
+
+:::info
+Remember: Each target can only specify **one** resource type, but a single Scope can have multiple targets for different resource types.
+:::
diff --git a/mission-control/docs/guide/permissions/examples/targeting-by-agent.md b/mission-control/docs/guide/permissions/examples/targeting-by-agent.md
new file mode 100644
index 00000000..1b7d38bd
--- /dev/null
+++ b/mission-control/docs/guide/permissions/examples/targeting-by-agent.md
@@ -0,0 +1,16 @@
+---
+title: Targeting by Agent
+---
+
+This example shows how to scope configs based on which agent reported them. This is useful for creating permissions that apply to specific infrastructure components or regions.
+
+```yaml title="prod-agent-configs.yaml" file=<rootDir>/modules/mission-control/fixtures/scopes/prod-agent-configs.yaml
+
+```
+
+This Scope includes all configs reported by either `agent-prod-1` or `agent-prod-2`. The multiple targets use OR logic, so any config from either agent will match this Scope.
+
+**Use Cases:**
+- Granting access to resources from specific production agents
+- Regional isolation (agents in different regions)
+- Infrastructure team boundaries (different teams managing different agents)
diff --git a/mission-control/docs/guide/permissions/examples/targeting-by-tags.md b/mission-control/docs/guide/permissions/examples/targeting-by-tags.md
new file mode 100644
index 00000000..94093671
--- /dev/null
+++ b/mission-control/docs/guide/permissions/examples/targeting-by-tags.md
@@ -0,0 +1,23 @@
+---
+title: Targeting by Tags
+---
+
+This example shows how to use tag selectors to dynamically scope resources based on their labels. Tag-based scoping is the most flexible approach as it allows resources to be added or removed from the scope by simply updating their tags.
+
+```yaml title="homelab-all-resources.yaml" file=<rootDir>/modules/mission-control/fixtures/scopes/homelab-all-resources.yaml
+
+```
+
+The `tagSelector` uses label selector syntax to match configs with `cluster=homelab` AND `namespace=monitoring` tags. All specified tags must match (AND logic within a single selector).
+
+**Advantages of Tag-Based Scoping:**
+- **Dynamic**: Resources automatically join/leave the scope when tags change
+- **Flexible**: No need to update Scope definitions when adding new resources
+- **Expressive**: Combine multiple tags to create precise filters
+- **Maintainable**: Centralize resource categorization through tagging strategy
+
+**Use Cases:**
+- Environment-based access (dev, staging, prod)
+- Application-based grouping
+- Compliance and regulatory boundaries
+- Cost center or team ownership
diff --git a/mission-control/docs/guide/permissions/examples/targeting-canaries.md b/mission-control/docs/guide/permissions/examples/targeting-canaries.md
new file mode 100644
index 00000000..985a2dec
--- /dev/null
+++ b/mission-control/docs/guide/permissions/examples/targeting-canaries.md
@@ -0,0 +1,17 @@
+---
+title: Targeting Canaries
+---
+
+This example demonstrates scoping canary health checks by name.
+
+```yaml title="canary-localhost.yaml" file=<rootDir>/modules/mission-control/fixtures/scopes/canary-localhost.yaml
+
+```
+
+This Scope targets all canaries with the name `localhost`, which is useful for:
+
+**Use Cases:**
+- Granting access to specific monitoring checks
+- Isolating development canaries from production
+- Team-specific health check ownership
+- SRE visibility boundaries
diff --git a/mission-control/docs/guide/permissions/examples/targeting-specific-playbooks.md b/mission-control/docs/guide/permissions/examples/targeting-specific-playbooks.md
new file mode 100644
index 00000000..8fe464a5
--- /dev/null
+++ b/mission-control/docs/guide/permissions/examples/targeting-specific-playbooks.md
@@ -0,0 +1,11 @@
+---
+title: Targeting Specific Playbooks
+---
+
+This example demonstrates how to create a Scope that targets specific playbooks by name within a namespace.
+
+```yaml title="echo-playbooks.yaml" file=<rootDir>/modules/mission-control/fixtures/scopes/echo-playbooks.yaml
+
+```
+
+This Scope includes only the two named playbooks (`echo-secret-parameter` and `loki-logs`) in the `guest1-ns` namespace. Multiple targets are combined with OR logic, so the Scope matches if the playbook name matches either of the specified names.
diff --git a/mission-control/docs/guide/permissions/examples/targeting-with-wildcards.md b/mission-control/docs/guide/permissions/examples/targeting-with-wildcards.md
new file mode 100644
index 00000000..9770b5c8
--- /dev/null
+++ b/mission-control/docs/guide/permissions/examples/targeting-with-wildcards.md
@@ -0,0 +1,20 @@
+---
+title: Targeting with Wildcards
+---
+
+This example demonstrates using the wildcard `*` to match all resources of a specific type.
+
+```yaml title="all-topology.yaml" file=<rootDir>/modules/mission-control/fixtures/scopes/all-topology.yaml
+
+```
+
+Using `name: "*"` matches all components (topology items) in the system without any filtering.
+
+:::info Wildcard Limitations
+The `name` field only supports the special wildcard directive `*` which matches **any** resource. Prefix and suffix wildcards (e.g., `nginx-*` or `*-prod`) are **NOT** supported.
+:::
+
+**Use Cases:**
+- Creating broad access policies for all resources of a type
+- Testing and development environments
+- Admin-level permissions

From 2b50855b724799984d48755758190da639aeb766 Mon Sep 17 00:00:00 2001
From: Aditya Thebe <contact@adityathebe.com>
Date: Thu, 12 Feb 2026 14:58:19 +0545
Subject: [PATCH 2/3] style(docs): format permission docs with prettier

---
 .../docs/guide/permissions/concepts/scope.md      | 15 ++++++++-------
 .../permissions/examples/combining-selectors.md   |  5 ++++-
 .../examples/global-resource-selectors.md         |  4 ++++
 .../examples/multi-tenancy-patterns.md            | 11 ++++++-----
 .../examples/multiple-resource-types.md           |  7 ++++---
 .../permissions/examples/targeting-by-agent.md    |  1 +
 .../permissions/examples/targeting-by-tags.md     |  2 ++
 .../permissions/examples/targeting-canaries.md    |  1 +
 .../examples/targeting-with-wildcards.md          |  1 +
 9 files changed, 31 insertions(+), 16 deletions(-)

diff --git a/mission-control/docs/guide/permissions/concepts/scope.md b/mission-control/docs/guide/permissions/concepts/scope.md
index 0734f6ec..48ea7164 100644
--- a/mission-control/docs/guide/permissions/concepts/scope.md
+++ b/mission-control/docs/guide/permissions/concepts/scope.md
@@ -21,12 +21,12 @@ Each target must specify exactly **one** resource type. You cannot mix different
 
 Each target uses a `ScopeResourceSelector` to filter resources. The selector supports four fields:
 
-| Field | Description | Example |
-|-------|-------------|---------|
-| `agent` | Filter by agent ID or name | `agent-prod-1` |
-| `namespace` | Filter by Kubernetes namespace | `production` |
-| `name` | Filter by resource name. Supports wildcard `*` to match any resource | `nginx-*` is **NOT** supported, but `*` matches all |
-| `tagSelector` | Filter by tags using label selector syntax | `env=prod,region=us-west` |
+| Field         | Description                                                          | Example                                             |
+| ------------- | -------------------------------------------------------------------- | --------------------------------------------------- |
+| `agent`       | Filter by agent ID or name                                           | `agent-prod-1`                                      |
+| `namespace`   | Filter by Kubernetes namespace                                       | `production`                                        |
+| `name`        | Filter by resource name. Supports wildcard `*` to match any resource | `nginx-*` is **NOT** supported, but `*` matches all |
+| `tagSelector` | Filter by tags using label selector syntax                           | `env=prod,region=us-west`                           |
 
 :::info Wildcard Limitations
 The `name` field supports only the special wildcard directive `*` which matches **any** resource. Prefix and suffix wildcards (e.g., `nginx-*` or `*-prod`) are **NOT** supported.
@@ -57,7 +57,7 @@ spec:
     - kind: Group
       name: dev-team
   scopes:
-    - prod-agent-configs  # Reference to Scope
+    - prod-agent-configs # Reference to Scope
   actions:
     - read
     - update
@@ -78,6 +78,7 @@ When a user attempts to access a resource:
 Scopes are fundamental to implementing [multi-tenancy](multi-tenancy.md) in Mission Control. They allow you to partition resources across different tenants, teams, or organizational units.
 
 Common multi-tenancy patterns include:
+
 - **Environment Isolation** - Separate Scopes for dev, staging, and production environments
 - **Team-Based Isolation** - Partition resources by team using namespaces or agents
 - **Customer Isolation** - For SaaS scenarios, isolate customer resources by tags or agents
diff --git a/mission-control/docs/guide/permissions/examples/combining-selectors.md b/mission-control/docs/guide/permissions/examples/combining-selectors.md
index b45019e1..2b2fb555 100644
--- a/mission-control/docs/guide/permissions/examples/combining-selectors.md
+++ b/mission-control/docs/guide/permissions/examples/combining-selectors.md
@@ -16,10 +16,11 @@ spec:
     - config:
         agent: agent-west-1
         namespace: production
-        tagSelector: "region=us-west"
+        tagSelector: 'region=us-west'
 ```
 
 This target matches configs that:
+
 - Come from `agent-west-1` **AND**
 - Are in the `production` namespace **AND**
 - Have the tag `region=us-west`
@@ -27,12 +28,14 @@ This target matches configs that:
 All three conditions must be satisfied for a config to match this target.
 
 **Use Cases:**
+
 - Highly specific resource filtering
 - Regional + environment isolation
 - Agent-specific namespaced resources
 - Complex compliance requirements
 
 **Selector Logic Summary:**
+
 - Fields within a single selector: **AND** logic (all must match)
 - Multiple targets in a Scope: **OR** logic (any target can match)
 - Multiple tags in `tagSelector`: **AND** logic (all tags must match)
diff --git a/mission-control/docs/guide/permissions/examples/global-resource-selectors.md b/mission-control/docs/guide/permissions/examples/global-resource-selectors.md
index d3ba1341..724c0e18 100644
--- a/mission-control/docs/guide/permissions/examples/global-resource-selectors.md
+++ b/mission-control/docs/guide/permissions/examples/global-resource-selectors.md
@@ -22,12 +22,14 @@ This Scope matches configs, components, playbooks, canaries, and views in the `r
 ## When to Use Global Selectors
 
 **Use global selectors when:**
+
 - Applying namespace-based isolation across all resource types
 - Creating agent-wide restrictions
 - Implementing broad organizational boundaries
 - Simplifying Scope definitions for common patterns
 
 **Avoid global selectors when:**
+
 - You need fine-grained control per resource type
 - Different resource types have different access requirements
 - You want to apply different tag filters to different resource types
@@ -37,6 +39,7 @@ This Scope matches configs, components, playbooks, canaries, and views in the `r
 These two Scopes are functionally equivalent:
 
 **Using global:**
+
 ```yaml
 targets:
   - global:
@@ -44,6 +47,7 @@ targets:
 ```
 
 **Using individual targets:**
+
 ```yaml
 targets:
   - config:
diff --git a/mission-control/docs/guide/permissions/examples/multi-tenancy-patterns.md b/mission-control/docs/guide/permissions/examples/multi-tenancy-patterns.md
index b61de4bf..0c828bc8 100644
--- a/mission-control/docs/guide/permissions/examples/multi-tenancy-patterns.md
+++ b/mission-control/docs/guide/permissions/examples/multi-tenancy-patterns.md
@@ -18,11 +18,11 @@ spec:
   description: All production resources
   targets:
     - config:
-        tagSelector: "env=production"
+        tagSelector: 'env=production'
     - component:
-        tagSelector: "env=production"
+        tagSelector: 'env=production'
     - playbook:
-        tagSelector: "env=production"
+        tagSelector: 'env=production'
 ```
 
 Grant developers read-only access to production resources and full access to development resources.
@@ -62,7 +62,7 @@ spec:
   description: All resources for ACME Corp
   targets:
     - config:
-        tagSelector: "customer=acme"
+        tagSelector: 'customer=acme'
 ```
 
 Each customer's resources are tagged appropriately, and Scopes ensure customer data isolation.
@@ -82,12 +82,13 @@ spec:
   targets:
     - config:
         namespace: team-a
-        tagSelector: "env=production,region=west"
+        tagSelector: 'env=production,region=west'
 ```
 
 This provides granular control for complex organizational structures.
 
 **Key Principles:**
+
 - Use consistent tagging strategies across all resources
 - Document your tenant isolation model
 - Start with broader Scopes and refine as needed
diff --git a/mission-control/docs/guide/permissions/examples/multiple-resource-types.md b/mission-control/docs/guide/permissions/examples/multiple-resource-types.md
index 2de48b8b..7d6ea1e8 100644
--- a/mission-control/docs/guide/permissions/examples/multiple-resource-types.md
+++ b/mission-control/docs/guide/permissions/examples/multiple-resource-types.md
@@ -14,16 +14,17 @@ spec:
   description: Complete monitoring stack resources
   targets:
     - config:
-        tagSelector: "app=prometheus"
+        tagSelector: 'app=prometheus'
     - component:
-        tagSelector: "app=prometheus"
+        tagSelector: 'app=prometheus'
     - canary:
-        tagSelector: "app=prometheus"
+        tagSelector: 'app=prometheus'
 ```
 
 This Scope includes configs, components, and canaries that all have the tag `app=prometheus`. A resource matches the Scope if it matches **any** of the three targets.
 
 **Use Cases:**
+
 - Application stack ownership (all resources for an app)
 - Feature-based access (configs + playbooks for a feature)
 - Platform team permissions (infrastructure + monitoring)
diff --git a/mission-control/docs/guide/permissions/examples/targeting-by-agent.md b/mission-control/docs/guide/permissions/examples/targeting-by-agent.md
index 1b7d38bd..cfacd7d1 100644
--- a/mission-control/docs/guide/permissions/examples/targeting-by-agent.md
+++ b/mission-control/docs/guide/permissions/examples/targeting-by-agent.md
@@ -11,6 +11,7 @@ This example shows how to scope configs based on which agent reported them. This
 This Scope includes all configs reported by either `agent-prod-1` or `agent-prod-2`. The multiple targets use OR logic, so any config from either agent will match this Scope.
 
 **Use Cases:**
+
 - Granting access to resources from specific production agents
 - Regional isolation (agents in different regions)
 - Infrastructure team boundaries (different teams managing different agents)
diff --git a/mission-control/docs/guide/permissions/examples/targeting-by-tags.md b/mission-control/docs/guide/permissions/examples/targeting-by-tags.md
index 94093671..ca0a92ba 100644
--- a/mission-control/docs/guide/permissions/examples/targeting-by-tags.md
+++ b/mission-control/docs/guide/permissions/examples/targeting-by-tags.md
@@ -11,12 +11,14 @@ This example shows how to use tag selectors to dynamically scope resources based
 The `tagSelector` uses label selector syntax to match configs with `cluster=homelab` AND `namespace=monitoring` tags. All specified tags must match (AND logic within a single selector).
 
 **Advantages of Tag-Based Scoping:**
+
 - **Dynamic**: Resources automatically join/leave the scope when tags change
 - **Flexible**: No need to update Scope definitions when adding new resources
 - **Expressive**: Combine multiple tags to create precise filters
 - **Maintainable**: Centralize resource categorization through tagging strategy
 
 **Use Cases:**
+
 - Environment-based access (dev, staging, prod)
 - Application-based grouping
 - Compliance and regulatory boundaries
diff --git a/mission-control/docs/guide/permissions/examples/targeting-canaries.md b/mission-control/docs/guide/permissions/examples/targeting-canaries.md
index 985a2dec..8f1d81dd 100644
--- a/mission-control/docs/guide/permissions/examples/targeting-canaries.md
+++ b/mission-control/docs/guide/permissions/examples/targeting-canaries.md
@@ -11,6 +11,7 @@ This example demonstrates scoping canary health checks by name.
 This Scope targets all canaries with the name `localhost`, which is useful for:
 
 **Use Cases:**
+
 - Granting access to specific monitoring checks
 - Isolating development canaries from production
 - Team-specific health check ownership
diff --git a/mission-control/docs/guide/permissions/examples/targeting-with-wildcards.md b/mission-control/docs/guide/permissions/examples/targeting-with-wildcards.md
index 9770b5c8..1247af30 100644
--- a/mission-control/docs/guide/permissions/examples/targeting-with-wildcards.md
+++ b/mission-control/docs/guide/permissions/examples/targeting-with-wildcards.md
@@ -15,6 +15,7 @@ The `name` field only supports the special wildcard directive `*` which matches
 :::
 
 **Use Cases:**
+
 - Creating broad access policies for all resources of a type
 - Testing and development environments
 - Admin-level permissions

From 66187811d7312e715b016728e8f37d4b80fdf76e Mon Sep 17 00:00:00 2001
From: Aditya Thebe <contact@adityathebe.com>
Date: Thu, 12 Feb 2026 14:59:54 +0545
Subject: [PATCH 3/3] style(docs): convert passive voice to active voice in
 permission docs

---
 mission-control/docs/guide/permissions/concepts/scope.md    | 6 +++---
 .../guide/permissions/examples/multi-tenancy-patterns.md    | 2 +-
 .../docs/guide/permissions/examples/targeting-by-tags.md    | 2 +-
 .../guide/permissions/examples/targeting-with-wildcards.md  | 2 +-
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/mission-control/docs/guide/permissions/concepts/scope.md b/mission-control/docs/guide/permissions/concepts/scope.md
index 48ea7164..f8582554 100644
--- a/mission-control/docs/guide/permissions/concepts/scope.md
+++ b/mission-control/docs/guide/permissions/concepts/scope.md
@@ -11,7 +11,7 @@ Scopes work as building blocks for [ABAC](abac.md) permission policies and enabl
 
 ### Scope Structure
 
-A Scope consists of one or more **targets**, where each target defines a collection of resources. Multiple targets within a Scope are combined with **OR logic**, meaning a resource matches the Scope if it matches any of the targets.
+A Scope consists of one or more **targets**, where each target defines a collection of resources. When a Scope contains multiple targets, the system combines them with **OR logic**, meaning a resource matches the Scope if it matches any of the targets.
 
 :::info
 Each target must specify exactly **one** resource type. You cannot mix different resource types within a single target.
@@ -45,7 +45,7 @@ Scopes can target six different resource types:
 
 ## Integration with ABAC
 
-Scopes are designed to work seamlessly with [Attribute-Based Access Control (ABAC)](abac.md). When using ABAC, you reference Scopes in your permission policies to define the resource boundaries for access control.
+Scopes work seamlessly with [Attribute-Based Access Control (ABAC)](abac.md). When using ABAC, you reference Scopes in your permission policies to define the resource boundaries for access control.
 
 ```yaml
 apiVersion: mission-control.flanksource.com/v1
@@ -70,7 +70,7 @@ This permission grants the `dev-team` group read and update access to all resour
 When a user attempts to access a resource:
 
 1. The system evaluates all Scopes referenced in the user's permissions
-2. If the resource matches any target in any of the user's Scopes, access is granted (subject to action restrictions)
+2. If the resource matches any target in any of the user's Scopes, the system grants access (subject to action restrictions)
 3. Multiple Scopes are combined with OR logic
 
 ## Integration with Multi-Tenancy
diff --git a/mission-control/docs/guide/permissions/examples/multi-tenancy-patterns.md b/mission-control/docs/guide/permissions/examples/multi-tenancy-patterns.md
index 0c828bc8..f9dc3bb1 100644
--- a/mission-control/docs/guide/permissions/examples/multi-tenancy-patterns.md
+++ b/mission-control/docs/guide/permissions/examples/multi-tenancy-patterns.md
@@ -65,7 +65,7 @@ spec:
         tagSelector: 'customer=acme'
 ```
 
-Each customer's resources are tagged appropriately, and Scopes ensure customer data isolation.
+You tag each customer's resources appropriately, and Scopes ensure customer data isolation.
 
 ## Multi-Dimensional Isolation
 
diff --git a/mission-control/docs/guide/permissions/examples/targeting-by-tags.md b/mission-control/docs/guide/permissions/examples/targeting-by-tags.md
index ca0a92ba..dab031b2 100644
--- a/mission-control/docs/guide/permissions/examples/targeting-by-tags.md
+++ b/mission-control/docs/guide/permissions/examples/targeting-by-tags.md
@@ -2,7 +2,7 @@
 title: Targeting by Tags
 ---
 
-This example shows how to use tag selectors to dynamically scope resources based on their labels. Tag-based scoping is the most flexible approach as it allows resources to be added or removed from the scope by simply updating their tags.
+This example shows how to use tag selectors to dynamically scope resources based on their labels. Tag-based scoping is the most flexible approach because you can add or remove resources from the scope by simply updating their tags.
 
 ```yaml title="homelab-all-resources.yaml" file=<rootDir>/modules/mission-control/fixtures/scopes/homelab-all-resources.yaml
 
diff --git a/mission-control/docs/guide/permissions/examples/targeting-with-wildcards.md b/mission-control/docs/guide/permissions/examples/targeting-with-wildcards.md
index 1247af30..a4bbdfb4 100644
--- a/mission-control/docs/guide/permissions/examples/targeting-with-wildcards.md
+++ b/mission-control/docs/guide/permissions/examples/targeting-with-wildcards.md
@@ -11,7 +11,7 @@ This example demonstrates using the wildcard `*` to match all resources of a spe
 Using `name: "*"` matches all components (topology items) in the system without any filtering.
 
 :::info Wildcard Limitations
-The `name` field only supports the special wildcard directive `*` which matches **any** resource. Prefix and suffix wildcards (e.g., `nginx-*` or `*-prod`) are **NOT** supported.
+The `name` field only supports the special wildcard directive `*` which matches **any** resource. Mission Control does **NOT** support prefix and suffix wildcards (e.g., `nginx-*` or `*-prod`).
 :::
 
 **Use Cases:**