fix: Permission docs

mission-control/docs/guide/permissions/concepts/scope.md

@@ -0,0 +1,93 @@
+---
+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. 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.
+:::
+
+### 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 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, the system grants access (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

mission-control/docs/guide/permissions/examples/combining-selectors.md

@@ -0,0 +1,41 @@
+---
+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)

mission-control/docs/guide/permissions/examples/global-resource-selectors.md

@@ -0,0 +1,65 @@
+---
+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.

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 />

mission-control/docs/guide/permissions/examples/multi-tenancy-patterns.md

@@ -0,0 +1,95 @@
+---
+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'
+```
+
+You tag each customer's resources 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

mission-control/docs/guide/permissions/examples/multiple-resource-types.md

@@ -0,0 +1,35 @@
+---
+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.
+:::

mission-control/docs/guide/permissions/examples/targeting-by-agent.md

@@ -0,0 +1,17 @@
+---
+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)

mission-control/docs/guide/permissions/examples/targeting-by-tags.md

@@ -0,0 +1,25 @@
+---
+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 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
+
+```
+
+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