diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..55426be
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,280 @@
+# NOVA Security Architecture
+
+## System Overview
+
+NOVA Security is a hard-enforced security policy system for the NOVA agent ecosystem. It provides entity trust management, role-based access control (RBAC), and policy-based authorization for agent interactions. The system combines PostgreSQL schema enforcement with AI-powered policy extraction from natural language.
+
+### Core Components
+1. **Trust Level System** – Six-tier trust hierarchy (0=untrusted to 5=admin)
+2. **Role-Based Access Control** – Cumulative role assignments with minimum trust requirements
+3. **Security Policy Engine** – Typed policies with priority-based evaluation
+4. **Policy Collector** – Active detection and enforcement of security statements
+5. **Audit System** – Comprehensive logging of all policy changes
+
+## Design Philosophy
+
+### 1. Deny by Default
+- Unknown entities start at trust level 0 (untrusted)
+- No implicit permissions – everything must be explicitly allowed
+- Fallback to trust level defaults when no policy matches
+
+### 2. Cumulative Permissions
+- Entities can hold multiple roles simultaneously
+- Permissions from all roles accumulate (OR logic)
+- Higher trust levels inherit lower-level permissions
+
+### 3. Priority-Based Evaluation
+- Policies evaluated by priority (highest first)
+- Explicit policies override trust level defaults
+- Temporal policies allow time-limited access
+
+### 4. Auditability
+- Every policy change logged with source and timestamp
+- Original message text preserved for context
+- Confidence scores track extraction certainty
+
+## Data Flow
+
+### Message Processing Pipeline
+```
+Incoming Message
+    │
+    ├─► Policy Collector (Active)
+    │       ├─ Pattern Detection (regex filters)
+    │       ├─ Claude API Extraction (structured JSON)
+    │       ├─ Entity/Role Resolution (name → ID mapping)
+    │       ├─ Confidence Evaluation (≥0.9 auto-apply)
+    │       └─ Policy Creation/Audit
+    │
+    ├─► Policy Evaluation (On-Demand)
+    │       ├─ Security Hook (check_policy() calls)
+    │       ├─ Priority-Based Matching
+    │       └─ Default Trust Level Fallback
+    │
+    └─► Enforcement
+            ├─ Communication Blocking (can_communicate())
+            ├─ Information Filtering (check_policy())
+            └─ Action Authorization (check_policy())
+```
+
+### Policy Collector Detailed Flow
+1. **Input**: Message text, sender context, message ID
+2. **Pre-filter**: Quick regex scan for policy-related phrases
+3. **API Call**: Send to Claude with entity/role context for structured extraction
+4. **Response Processing**: Parse JSON, validate policy types/actions
+5. **Entity Resolution**: Map entity/role names to database IDs
+6. **Confidence Check**: Compare against `MIN_CONFIDENCE` (0.9)
+7. **Policy Application**:
+   - High confidence: Create enabled policies, apply trust/role changes
+   - Low confidence: Create disabled policies for review
+8. **Audit Logging**: Record all changes in `policy_audit` table
+
+## Schema Relationships
+
+### Entity-Centric Security Model
+```
+trust_levels (reference table)
+    ↑
+entities (core entity registry)
+    ├── entity_role_assignments (junction table)
+    │       └── entity_roles (role definitions)
+    │
+    └── security_policies (active policies)
+            └── policy_audit (change history)
+```
+
+### Table Descriptions
+
+#### `trust_levels`
+Reference table defining six trust levels with permissions. Each level specifies:
+- `can_communicate`: Whether entities at this level can send/receive messages
+- `can_request_actions`: Whether entities can request sensitive operations
+
+#### `entities`
+Core entity registry with `trust_level` foreign key reference. New entities default to level 0.
+
+#### `entity_roles`
+Role definitions with `min_trust_level` requirement. Default roles: user, operator, admin, agent, external_agent, service.
+
+#### `entity_role_assignments`
+Junction table linking entities to roles with optional expiration timestamp.
+
+#### `security_policies`
+Active policy rules with:
+- Subject: `entity_id`, `role_id`, or `applies_to_all`
+- Type: `communication`, `information_sharing`, `action_permission`, etc.
+- Action: `allow`, `deny`, `require_approval`, `log_only`
+- Targets: `target_entity_id`, `target_role_id`, `resource_pattern`
+- Metadata: `priority`, `confidence`, `source`, `original_text`, `expires_at`
+
+#### `policy_audit`
+Immutable audit log tracking all policy changes.
+
+## Policy Evaluation Logic
+
+### Evaluation Algorithm
+```pseudocode
+function evaluate_policy(entity_id, policy_type, resource):
+    # 1. Get entity's roles (active, non-expired)
+    roles = get_entity_roles(entity_id)
+    
+    # 2. Find matching policies (highest priority first)
+    policies = find_policies(entity_id, roles, policy_type, resource)
+    sort_by_priority_desc(policies)
+    
+    # 3. Return first matching policy
+    for policy in policies:
+        if policy.matches(resource):
+            return policy.action
+    
+    # 4. Fallback to trust level defaults
+    trust_level = get_entity_trust_level(entity_id)
+    return trust_level_defaults[trust_level]
+```
+
+### Policy Matching Precedence
+1. Entity-specific policies (`entity_id = X`)
+2. Role-based policies (`role_id = Y` where entity has role Y)
+3. Global policies (`applies_to_all = TRUE`)
+4. Trust level defaults
+
+### Resource Pattern Matching
+- `resource_pattern` supports PostgreSQL regex (`~` operator)
+- Null pattern matches any resource
+- Resource names are system-defined (e.g., `service.restart`, `/api/v1/agents`)
+
+## Confidence-Based Auto-Apply
+
+### Threshold Configuration
+- `MIN_CONFIDENCE = 0.9` (configurable in script)
+- Based on Claude extraction confidence score (0.0-1.0)
+
+### High Confidence (≥ 0.9)
+- Policies created with `enabled = TRUE`
+- Trust level changes applied immediately
+- Role assignments executed
+- Assumption: Clear, unambiguous policy statements
+
+### Low Confidence (< 0.9)
+- Policies created with `enabled = FALSE`
+- Queued for human review
+- Trust/role changes deferred
+- Prevents incorrect policy application from ambiguous statements
+
+### Review Workflow
+1. Low-confidence policies visible in `security_policies` (enabled=FALSE)
+2. Human reviewer evaluates original text and confidence
+3. Reviewer enables policy or marks for deletion
+4. Audit trail preserves review decision
+
+## Integration Points
+
+### 1. Message Handling Systems
+- **OpenClaw Gateway**: Call policy collector on incoming messages
+- **Memory Pipeline**: Integrate with memory extraction for passive policy detection
+- **Agent Chat**: Check `can_communicate()` before message delivery
+
+### 2. Database Integration
+- **nova_memory**: Primary database for all security tables
+- **Row-Level Security**: Future extension using PostgreSQL RLS
+- **Foreign Data Wrappers**: Potential integration with external identity systems
+
+### 3. Agent Ecosystem
+- **Agent Registration**: Set default trust level based on agent type
+- **Role Assignment**: Automatically assign `agent` or `external_agent` roles
+- **Policy Inheritance**: System-wide policies for agent categories
+
+### 4. Administrative Interfaces
+- **Policy Review Dashboard**: View and manage queued policies
+- **Trust Level Management**: Manual trust adjustment interface
+- **Audit Reporting**: Compliance and forensic analysis
+
+## Security Considerations
+
+### 1. Principle of Least Privilege
+- Default deny stance
+- Explicit allow policies required for any access
+- Temporal policies for temporary access needs
+
+### 2. Defense in Depth
+- Database constraints prevent invalid trust levels
+- Application-level policy evaluation
+- Audit logging for forensic analysis
+- Regular review of low-confidence policies
+
+### 3. API Security
+- Anthropic API key stored in `~/.secrets/`
+- Environment variable configuration
+- No hardcoded credentials in scripts
+
+### 4. Database Security
+- PostgreSQL connection with SCRAM authentication
+- No direct table modifications – use provided functions
+- Audit triggers on critical tables
+
+### 5. Policy Validation
+- Schema constraints enforce valid policy types/actions
+- Confidence thresholds prevent ambiguous policy application
+- Original text preservation for context verification
+
+## Performance Considerations
+
+### Indexing Strategy
+- Indexes on `security_policies` for common query patterns:
+  - `entity_id` + `enabled` + `policy_type`
+  - `role_id` + `enabled` + `policy_type`
+  - `priority` DESC for evaluation ordering
+- Partial indexes for active policies only (`WHERE enabled = TRUE`)
+
+### Policy Evaluation Optimization
+- Function `check_policy()` optimized for single query evaluation
+- Materialized views for frequently accessed security summaries
+- Connection pooling for high-volume message processing
+
+### Collector Performance
+- Pre-filter regex reduces unnecessary API calls
+- Batch processing of multiple policies per message
+- Async processing for non-blocking operation
+
+## Deployment Architecture
+
+### Single-Node Deployment
+```
+Application Layer → PostgreSQL (nova_memory)
+       ↓
+  Policy Collector
+       ↓
+  Claude API (external)
+```
+
+### Multi-Node Considerations
+- Shared PostgreSQL instance for all nodes
+- Centralized policy storage for consistent enforcement
+- Distributed collectors with shared audit log
+- Message deduplication for policy extraction
+
+## Future Extensions
+
+### 1. Policy Inheritance
+- Role hierarchy with permission inheritance
+- Group-based policies (entities→groups→roles)
+- Context-aware policies (time, location, device)
+
+### 2. Advanced Pattern Matching
+- Machine learning for policy statement detection
+- Multi-model extraction (Claude + local models)
+- Contextual disambiguation using agent memory
+
+### 3. Integration Enhancements
+- Webhook notifications for policy changes
+- Real-time policy synchronization across nodes
+- Graphical policy management interface
+
+### 4. Compliance Features
+- Policy versioning and rollback
+- Compliance reporting (GDPR, HIPAA, etc.)
+- Automated policy review scheduling
+
+## Conclusion
+
+NOVA Security provides a robust, extensible security foundation for the NOVA agent ecosystem. By combining traditional RBAC with AI-powered policy extraction and PostgreSQL enforcement, it enables natural language security management while maintaining strict access control. The architecture supports both automated and human-in-the-loop workflows, balancing security with operational flexibility.
\ No newline at end of file
diff --git a/README.md b/README.md
index 44c68b6..24ea73c 100644
--- a/README.md
+++ b/README.md
@@ -4,61 +4,307 @@ Security infrastructure for NOVA: entity policies, trust management, and access
 
 ## Overview
 
-This project provides hard-enforced security policies for entity interactions:
+NOVA Security provides hard-enforced security policies for entity interactions within the NOVA agent ecosystem. The system operates on a **deny-by-default** principle with policy-based access control, combining:
 
-- **Trust Levels** - Graduated trust from untrusted (0) to admin (5)
-- **Entity Roles** - Cumulative role assignments (user, operator, admin, agent, etc.)
-- **Security Policies** - Structured rules for communication, information sharing, action permissions
-- **Policy Collector** - Active detection and enforcement of security policy statements
-- **Enforcement Layer** - Hooks for message handling, response filtering, action authorization
-
-## Architecture
-
-```
-Incoming Message
-    │
-    ├─► Policy Collector (active)
-    │       ├─ Detect policy statements
-    │       ├─ Resolve entities/roles
-    │       ├─ Apply to security_policies table
-    │       └─ Log changes
-    │
-    └─► Policy Enforcer
-            ├─ Check communication policies
-            ├─ Filter information sharing
-            └─ Authorize actions
-```
+- **Trust Levels** – Graduated trust from untrusted (0) to admin (5)
+- **Entity Roles** – Cumulative role assignments (RBAC)
+- **Security Policies** – Structured rules for communication, information sharing, and actions
+- **Policy Collector** – Active detection and enforcement of security policy statements
+- **PostgreSQL Functions** – Database-level policy evaluation and enforcement
 
 ## Default Stance
 
-**Deny until instructed otherwise.** Unknown entities have trust_level=0 and cannot communicate until explicitly permitted.
+**Deny until instructed otherwise.** Unknown entities have `trust_level=0` and cannot communicate until explicitly permitted via trust level changes, role assignments, or security policies.
 
 ## Components
 
 | Component | Path | Purpose |
 |-----------|------|---------|
-| Schema | `schema/` | PostgreSQL tables and functions |
-| Policy Collector | `scripts/collect-policies.sh` | Active policy detection |
-| Enforcer | `lib/enforcer.py` | Policy enforcement library |
-| Docs | `docs/` | Specifications and design docs |
+| Schema | `schema/` | PostgreSQL tables, functions, and views |
+| Policy Collector | `scripts/collect-policies.sh` | Active policy detection via Claude API |
+| Documentation | `docs/` | Specifications and design documents |
+| Agent Installer | `agent-install.sh` | Stub installer for agent deployment |
+
+## Trust Levels
+
+NOVA Security defines six trust levels based on entity identity and verification:
+
+| Level | Name | Can Communicate | Can Request Actions | Description |
+|-------|------|-----------------|-------------------|-------------|
+| 0 | `untrusted` | ❌ | ❌ | Unknown entity, no interaction permitted |
+| 1 | `known` | ❌ | ❌ | Identified but unverified, listen-only |
+| 2 | `verified` | ✅ | ❌ | Identity confirmed, limited interaction |
+| 3 | `trusted` | ✅ | ❌ | Full interaction, standard permissions |
+| 4 | `privileged` | ✅ | ✅ | Extended permissions, can request sensitive actions |
+| 5 | `admin` | ✅ | ✅ | Full administrative access |
+
+**Default:** All new entities start at level 0 (untrusted).
+
+## Roles System (RBAC)
+
+Roles allow policy statements like "Administrators can do X" without naming specific entities. Roles are **cumulative** – an entity can hold multiple roles simultaneously.
+
+### Default Roles
+- `user` – Standard user with basic permissions (requires trust_level ≥ 2)
+- `operator` – Can perform operational tasks (requires trust_level ≥ 3)
+- `admin` – Full administrative access (requires trust_level = 5)
+- `agent` – Internal AI agent with defined capabilities (requires trust_level ≥ 3)
+- `external_agent` – AI agent from external system (requires trust_level ≥ 2)
+- `service` – Automated service or bot (requires trust_level ≥ 1)
+
+### Role Assignment Functions
+- `assign_role(entity_id, role_name, assigned_by, expires_at, notes)` – Assign role to entity
+- `revoke_role(entity_id, role_name)` – Remove role assignment
+- `entity_has_role(entity_id, role_name)` – Check if entity has role
+- `entity_roles(entity_id)` – List entity's active roles
+
+## Security Policies
+
+Structured policy storage with typed policies and priority-based evaluation. Policies support entity, role, or global targets.
+
+### Policy Types
+| Type | Description | Example |
+|------|-------------|---------|
+| `communication` | Who can send/receive messages | "You may communicate freely with X" |
+| `information_sharing` | What info can be shared with whom | "Don't share Y with Z" |
+| `action_permission` | What actions entity can request | "X can restart services" |
+| `response_mode` | How to handle messages | "Listen to X but don't respond" |
+| `data_access` | Access to specific data/tables | "X can read tasks table" |
+| `delegation` | Can delegate tasks to others | "X can assign work to agents" |
+
+### Policy Actions
+- `allow` – Explicitly permit the action
+- `deny` – Explicitly forbid the action
+- `require_approval` – Flag for human review before allowing
+- `log_only` – Allow but log for auditing
+
+### Evaluation Priority
+1. Policies with highest `priority` value are evaluated first
+2. If no matching policy found, fall back to trust level defaults
+3. Untrusted entities (level 0) are denied by default
+
+## Policy Collector
 
-## Quick Start
+The active policy collector (`scripts/collect-policies.sh`) processes messages to detect and apply security policy statements.
 
+### How It Works
+1. **Pattern Detection** – Quick regex scan for policy-related phrases
+2. **Claude Extraction** – Uses Claude API to extract structured policy statements
+3. **Entity Resolution** – Maps entity/role names to database IDs
+4. **Policy Creation** – Inserts policies into `security_policies` table
+5. **Audit Logging** – Records all changes in `policy_audit` table
+
+### Confidence Threshold
+- **≥ 0.9** – Auto-apply policies immediately
+- **< 0.9** – Create as disabled (`enabled=FALSE`) for manual review
+
+### Typical Usage
 ```bash
-# Apply schema
+# Environment variables for context
+export SENDER_NAME="Alice"
+export SENDER_ENTITY=123
+export MESSAGE_ID="msg_abc"
+
+# Process a message
+./scripts/collect-policies.sh "Alice is now an administrator"
+
+# Or pipe input
+echo "Trust Bob but don't share secrets with him" | ./scripts/collect-policies.sh
+```
+
+## SQL Functions Reference
+
+### Trust Level Functions
+```sql
+-- Get trust level name
+SELECT trust_level_name(3);  -- returns 'trusted'
+
+-- Get trust level details
+SELECT * FROM trust_level_info(4);  -- returns name, description, permissions
+```
+
+### Role Management Functions
+```sql
+-- Assign a role
+SELECT assign_role(123, 'admin', NULL, NULL, 'Auto-assigned');
+
+-- Check role membership
+SELECT entity_has_role(123, 'admin');  -- returns TRUE/FALSE
+
+-- List entity roles
+SELECT * FROM entity_roles(123);
+```
+
+### Policy Evaluation Functions
+```sql
+-- Check if entity can communicate
+SELECT can_communicate(123);  -- returns TRUE/FALSE
+
+-- Check specific policy type
+SELECT * FROM check_policy(123, 'communication', '/api/v1/agents');
+
+-- Create a new policy
+SELECT create_policy(
+    123,                   -- entity_id
+    NULL,                  -- role_id (optional)
+    'communication',       -- policy_type
+    'allow',               -- action
+    NULL,                  -- target_entity_id (optional)
+    '/api/v1/*',          -- resource_pattern (optional)
+    100,                   -- priority
+    NULL,                  -- expires_at (optional)
+    'manual',              -- source
+    'msg_123',             -- source_message_id (optional)
+    'Alice can call API'   -- original_text (optional)
+);
+```
+
+## Views Reference
+
+### `v_active_policies`
+Shows all active policies with resolved entity/role names.
+```sql
+SELECT * FROM v_active_policies WHERE policy_type = 'communication';
+```
+
+### `v_entity_security`
+Entity security summary including trust level, role assignments, and policy counts.
+```sql
+SELECT * FROM v_entity_security WHERE name = 'Alice';
+```
+
+### `v_entity_roles`
+Entities with their assigned roles (aggregated array).
+```sql
+SELECT * FROM v_entity_roles WHERE 'admin' = ANY(roles);
+```
+
+## Installation
+
+### 1. Apply Schema
+The schema files must be applied in order:
+
+```bash
+# Apply to nova_memory database
 psql -d nova_memory -f schema/001-trust-levels.sql
 psql -d nova_memory -f schema/002-entity-roles.sql
 psql -d nova_memory -f schema/003-security-policies.sql
+```
+
+### 2. Configure Environment
+Set up required environment variables:
+
+```bash
+# Anthropic API key for policy collector
+export ANTHROPIC_API_KEY="your-api-key"
+# Or store in ~/.secrets/anthropic-api-key
+
+# Database connection (defaults to nova_memory)
+export DB_NAME="nova_memory"
+```
 
-# Run collector (typically called by hook)
-./scripts/collect-policies.sh "policy statement text"
+### 3. Integrate with NOVA Ecosystem
+The policy collector should be called as part of message processing pipelines. Typical integration:
+
+1. Message received → extract text
+2. Run policy collector → apply security policies
+3. Continue with normal processing
+
+## Quick Usage Examples
+
+### Example 1: Basic Policy Check
+```sql
+-- Check if entity can communicate
+SELECT name, can_communicate(id) 
+FROM entities 
+WHERE name = 'Alice';
+
+-- Result: TRUE if allowed by policy or trust level ≥ 2
+```
+
+### Example 2: Create Communication Policy
+```sql
+-- Allow Alice to communicate with Bob
+SELECT create_policy(
+    (SELECT id FROM entities WHERE name = 'Alice'),
+    NULL,
+    'communication',
+    'allow',
+    (SELECT id FROM entities WHERE name = 'Bob'),
+    NULL,
+    100,
+    NULL,
+    'manual',
+    NULL,
+    'Alice can talk to Bob'
+);
+```
+
+### Example 3: Role-Based Policy
+```sql
+-- Allow all admins to restart services
+SELECT create_policy(
+    NULL,
+    (SELECT id FROM entity_roles WHERE name = 'admin'),
+    'action_permission',
+    'allow',
+    NULL,
+    'service.restart',
+    100,
+    NULL,
+    'manual',
+    NULL,
+    'Admins can restart services'
+);
+```
+
+### Example 4: Temporary Policy
+```sql
+-- Allow communication until tomorrow
+SELECT create_policy(
+    123,
+    NULL,
+    'communication',
+    'allow',
+    456,
+    NULL,
+    100,
+    NOW() + INTERVAL '1 day',
+    'manual',
+    NULL,
+    'Temporary access'
+);
+```
+
+## Schema Overview
+
+```
+trust_levels (level, name, description, can_communicate, can_request_actions)
+    |
+entities (trust_level FK) –– entity_role_assignments –– entity_roles
+    |                               |
+security_policies –– policy_audit   |
+    |                               |
+v_active_policies                  v_entity_roles
+v_entity_security
 ```
 
 ## Related Projects
 
-- [nova_memory](../docs/) - Memory database (entities, facts, events)
-- [openclaw](../openclaw/) - Gateway and message handling
+- **[nova_memory](https://github.com/your-org/nova-memory)** – Memory database (entities, facts, events)
+- **[openclaw](https://github.com/your-org/openclaw)** – Gateway and message handling
+- **[nova-cognition](../nova-cognition/)** – Reasoning and decision making
 
 ---
 
-*Private repository. Security-sensitive code.*
+## Security Considerations
+
+1. **Default Deny** – Unknown entities cannot interact
+2. **Audit Logging** – All policy changes are recorded
+3. **Confidence Thresholds** – Low-confidence policies require review
+4. **PostgreSQL Security** – Policies enforced at database level
+5. **No Hardcoded Secrets** – Keys via environment variables
+
+## License
+
+Private repository. Security-sensitive code.
\ No newline at end of file