feat: POLICY-CONFIG-001 PR 8 — Policy configuration documentation

docs/concepts/enforcement.md

@@ -135,3 +135,13 @@ Server-Timing: capiscio-auth;dur=0.618;desc="CapiscIO Verification"
 | ✅ Enforce payload integrity (SHA-256 body hash) | ❌ Manage a central registry (coming soon) |
 | ✅ Block replay attacks (timestamp validation) | ❌ Replace your IAM/SSO (human auth) |
 | ✅ Work with keys you provision | ❌ Auto-discover external agent keys (coming soon) |
+
+## Policy-Driven Enforcement
+
+Beyond identity verification, CapiscIO supports **YAML-based policy configurations** that define trust requirements, access rules, and rate limits. Policies are scoped at three levels:
+
+- **Organization**: Baseline rules for all agents
+- **Group**: Rules for named collections of agents
+- **Agent**: Per-agent overrides for fine-grained control
+
+See [Policy Scoping](policy-scoping.md) for the full scoping model, or [Configure Agent Policy](../how-to/configure-agent-policy.md) for a practical walkthrough.

docs/concepts/policy-scoping.md

@@ -0,0 +1,118 @@
+---
+title: Policy Scoping
+description: How CapiscIO's three-level policy scoping model (org → group → agent) enables granular trust and access control.
+---
+
+# Policy Scoping
+
+CapiscIO uses a **three-level scoping model** for policy configuration, providing flexible control over agent trust and access at every level of your organization.
+
+## Scope Levels
+
+```
+┌─────────────────────────────────────────┐
+│              Org Policy                 │  Baseline for all agents
+│  min_trust_level: DV                    │
+│  denied_dids: [did:web:blocked.ex]      │
+├─────────────┬───────────────────────────┤
+│ Group: PII  │ Group: Public             │  Named agent collections
+│ min_trust:  │ min_trust: ""             │
+│   OV        │                           │
+├──────┬──────┼───────────────────────────┤
+│ Agent│Override                          │  Per-agent overrides
+│ EV   │                                  │
+└──────┴──────┴───────────────────────────┘
+```
+
+### 1. Organization Scope (Baseline)
+
+The **org-level policy** is the baseline that applies to every agent in your organization. It defines the minimum trust requirements, default access rules, and rate limits.
+
+```yaml
+# capiscio-policy.yaml (org scope)
+version: "1"
+min_trust_level: "DV"
+denied_dids:
+  - "did:web:known-bad-actor.example.com"
+rate_limits:
+  - did: "did:web:high-volume.example.com"
+    rpm: 100
+```
+
+### 2. Group Scope (Named Collections)
+
+**Policy groups** allow you to apply rules to named collections of agents. For example, you might create a "PII Handlers" group with stricter trust requirements, or a "Public APIs" group with more permissive settings.
+
+Groups have a **precedence** value (lower = higher priority) that determines which group policy takes effect when an agent belongs to multiple groups.
+
+```yaml
+# Group: pii-handlers (precedence: 10)
+version: "1"
+min_trust_level: "OV"
+allowed_dids:
+  - "did:web:trusted-processor.example.com"
+```
+
+### 3. Agent Scope (Per-Agent Overrides)
+
+**Agent-level policies** provide the finest granularity. They override both org and group policies for a specific agent. Use these for agents with unique requirements.
+
+```yaml
+# Agent: critical-payment-processor
+version: "1"
+min_trust_level: "EV"
+operations:
+  - pattern: "payment.*"
+    min_trust_level: "EV"
+    allowed_dids:
+      - "did:web:payment-gateway.example.com"
+```
+
+## Resolution Algorithm
+
+When evaluating a policy decision, CapiscIO resolves the **effective policy** for each agent by merging policies in order:
+
+1. Start with the **org policy** (baseline)
+2. Apply **group policies** in precedence order (lowest precedence number first)
+3. Apply **agent-specific overrides** (highest priority)
+
+The resolution is **deterministic**: given the same set of active policies, the resolved result is always identical. This is critical for audit and debugging.
+
+### Override Behavior
+
+- **`min_trust_level`**: Narrower scope wins (agent > group > org)
+- **`allowed_dids`**: Intersection (more specific scope restricts further)
+- **`denied_dids`**: Union (denied at any scope = denied everywhere)
+- **`rate_limits`**: Most specific scope wins per DID
+- **`operations`** and **`mcp_tools`**: Most specific scope wins per pattern/tool name
+
+## Visibility and Auditability
+
+Every policy resolution produces an **attribution trail** showing which scope contributed which rule. This is accessible via:
+
+- **Resolved Policy endpoint**: `GET /v1/orgs/{orgId}/policy/agents/{agentId}/resolved`
+- **Lineage endpoint**: `GET /v1/orgs/{orgId}/policy/agents/{agentId}/lineage`
+- **Policy Context** (SDK): `capiscio policy context`
+
+The resolved endpoint returns the effective policy for a specific agent. The lineage endpoint returns all policy documents that contributed to the resolution, in precedence order.
+
+## Trust Levels
+
+CapiscIO defines six trust levels, each representing increasing assurance about an agent's identity:
+
+| Level | Name | Meaning |
+|-------|------|---------|
+| (empty) | None | No trust requirement |
+| `SS` | Self-Signed | Agent has a self-signed key |
+| `REG` | Registered | Agent is registered in the registry |
+| `DV` | Domain Validated | Agent's domain ownership is verified |
+| `OV` | Organization Validated | Agent's organization is verified |
+| `EV` | Extended Validation | Agent has undergone extended validation |
+
+Trust levels are hierarchical: `EV > OV > DV > REG > SS > (none)`.
+
+## Next Steps
+
+- [Configure Agent Policy](../how-to/configure-agent-policy.md) — YAML config walkthrough
+- [Policy API Reference](../reference/policy-api.md) — Phase-one API endpoints
+- [CLI Reference](../reference/cli/index.md) — `capiscio policy` commands

docs/how-to/configure-agent-policy.md

@@ -0,0 +1,221 @@
+---
+title: Configure Agent Policy
+description: How to write and deploy YAML-based policy configurations for your CapiscIO agents.
+---
+
+# Configure Agent Policy
+
+This guide walks you through writing, validating, and deploying YAML policy configurations. Policy configs define trust requirements, access rules, and rate limits for your agents.
+
+## Quick Start
+
+### 1. Create a Policy Config File
+
+Create a file named `capiscio-policy.yaml` in your project root:
+
+```yaml
+version: "1"
+min_trust_level: "DV"
+denied_dids:
+  - "did:web:known-bad-actor.example.com"
+```
+
+### 2. Validate Locally
+
+```bash
+capiscio policy validate -f capiscio-policy.yaml
+```
+
+### 3. Deploy to Your Organization
+
+Use the dashboard UI or the [Policy API](../reference/policy-api.md) to create and approve a policy proposal:
+
+```bash
+# View current policy context
+capiscio policy context --registry https://api.capisc.io --api-key $CAPISCIO_API_KEY
+```
+
+## YAML Schema
+
+### Version
+
+Every policy config must specify `version: "1"`. This is the current and only supported version.
+
+```yaml
+version: "1"
+```
+
+### Minimum Trust Level
+
+Set a baseline trust requirement for all incoming agent requests:
+
+```yaml
+min_trust_level: "DV"  # Require domain validation or higher
+```
+
+Valid values: `""` (none), `SS`, `REG`, `DV`, `OV`, `EV`
+
+### DID Access Lists
+
+Control which agents can interact with your agents by DID:
+
+```yaml
+# Only these agents may call your agents
+allowed_dids:
+  - "did:web:partner-a.example.com"
+  - "did:web:partner-b.example.com"
+
+# These agents are always blocked
+denied_dids:
+  - "did:web:known-bad-actor.example.com"
+```
+
+!!! warning "Mutual Exclusivity"
+    A DID cannot appear in both `allowed_dids` and `denied_dids`. The validator will reject such configurations.
+
+### Rate Limits
+
+Define per-DID rate limits (requests per minute):
+
+```yaml
+rate_limits:
+  - did: "did:web:high-volume-caller.example.com"
+    rpm: 100
+  - did: "did:web:low-priority.example.com"
+    rpm: 10
+```
+
+Rate limits generate **obligations** in policy decisions — the enforcement point is responsible for applying them.
+
+### Operation-Scoped Rules
+
+Apply different trust/access rules to specific operations:
+
+```yaml
+operations:
+  - pattern: "payment.*"
+    min_trust_level: "EV"
+    allowed_dids:
+      - "did:web:payment-gateway.example.com"
+  - pattern: "read.*"
+    min_trust_level: ""  # No trust required for reads
+```
+
+Operations are matched against `input.action.operation` in policy evaluation.
+
+### MCP Tool-Scoped Rules
+
+Apply rules to specific MCP tools exposed by your agent:
+
+```yaml
+mcp_tools:
+  - tool: "database_query"
+    min_trust_level: "OV"
+    denied_dids:
+      - "did:web:untrusted.example.com"
+  - tool: "file_read"
+    min_trust_level: "DV"
+```
+
+MCP tool rules are matched against `input.action.mcp_tool` in policy evaluation.
+
+## Complete Example
+
+```yaml
+version: "1"
+min_trust_level: "DV"
+
+allowed_dids:
+  - "did:web:trusted-partner.example.com"
+  - "did:web:internal-service.example.com"
+
+denied_dids:
+  - "did:web:blocked-agent.example.com"
+
+rate_limits:
+  - did: "did:web:trusted-partner.example.com"
+    rpm: 1000
+  - did: "did:web:internal-service.example.com"
+    rpm: 500
+
+operations:
+  - pattern: "payment.*"
+    min_trust_level: "EV"
+    allowed_dids:
+      - "did:web:payment-processor.example.com"
+  - pattern: "admin.*"
+    min_trust_level: "OV"
+
+mcp_tools:
+  - tool: "database_query"
+    min_trust_level: "OV"
+  - tool: "send_email"
+    min_trust_level: "EV"
+    allowed_dids:
+      - "did:web:notification-service.example.com"
+```
+
+## Validation
+
+### CLI Validation
+
+Validate your policy config before deploying:
+
+```bash
+# Default file (capiscio-policy.yaml)
+capiscio policy validate
+
+# Custom file
+capiscio policy validate -f my-policy.yaml
+
+# JSON output for CI integration
+capiscio policy validate -f my-policy.yaml --json
+```
+
+Exit code `0` means valid; non-zero means validation errors.
+
+### Validation Rules
+
+The validator checks:
+
+- **Version**: Must be `"1"`
+- **Trust levels**: Must be one of `""`, `SS`, `REG`, `DV`, `OV`, `EV`
+- **DID format**: All DIDs must start with `did:`
+- **No duplicates**: A DID cannot appear twice in the same list
+- **No cross-listing**: A DID cannot be in both `allowed_dids` and `denied_dids`
+- **Rate limits**: RPM must be positive
+- **Operations**: Pattern must not be empty
+- **MCP tools**: Tool name must not be empty
+
+## Policy Lifecycle
+
+### 1. Create a Proposal
+
+Policies go through a proposal workflow:
+
+```
+Create Proposal → Review → Approve → Active
+                        ↘ Reject (with reason)
+```
+
+### 2. Approval Activates Policy
+
+When a proposal is approved, it becomes the active policy. The previously active policy is marked as superseded.
+
+### 3. Bundle Rebuild
+
+After activation, the policy bundle is automatically rebuilt. Agents polling the bundle endpoint will pick up the new policy on their next refresh cycle.
+
+### 4. Enforcement
+
+Policy enforcement follows the [enforcement mode](../concepts/enforcement.md) configured for your deployment:
+
+- **EM-OBSERVE**: Violations logged but allowed (default)
+- **EM-GUARD**: Violations blocked, PDP-unavailable allowed with warning
+- **EM-STRICT**: All violations blocked, including PDP unavailability
+
+## Next Steps
+
+- [Policy Scoping](../concepts/policy-scoping.md) — Org/group/agent scoping model
+- [Policy API Reference](../reference/policy-api.md) — REST API for policy management
+- [CLI Reference](../reference/cli/index.md) — `capiscio policy` commands