vaultkit 0.1.0 → 0.1.2

data/README.md

@@ -1,611 +1,543 @@
-# VaultKit
+# VaultKit CLI (`vkit`)
 
+[![Gem Version](https://img.shields.io/badge/gem-v0.1.0-blue.svg)](https://rubygems.org/gems/vaultkitcli)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()
-[![Version](https://img.shields.io/badge/version-0.1.0-orange.svg)]()
-[![Go Version](https://img.shields.io/badge/go-1.21+-00ADD8.svg)](https://golang.org)
 [![Ruby Version](https://img.shields.io/badge/ruby-3.1+-CC342D.svg)](https://www.ruby-lang.org)
 
-> A secure, policy-driven control plane for unified data access across heterogeneous data sources.
+> Command-line interface for VaultKit — secure, policy-driven data access control plane
 
-**TL;DR**: VaultKit prevents credential sprawl and enforces data access policies across databases. Write queries in AQL (vendor-neutral JSON), policies decide who sees what, FUNL executes safely. Schema changes require explicit review—no silent data exposure.
+The VaultKit CLI (`vkit`) is the primary interface for interacting with the VaultKit control plane. It enables users to request governed data access, track approvals, manage datasources, and deploy policy bundles—all while maintaining complete audit trails.
 
 ---
 
-## 🎯 What is VaultKit?
+## 📋 Table of Contents
 
-VaultKit provides enterprise-grade governance and security for data access, enabling applications, engineers, and AI agents to query multiple data sources through a unified, policy-controlled interface.
+- [What is VaultKit CLI?](#what-is-vaultkit-cli)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Authentication](#authentication)
+- [Core Workflows](#core-workflows)
+- [Command Reference](#command-reference)
+- [Configuration](#configuration)
+- [Advanced Usage](#advanced-usage)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
 
-VaultKit is a **control plane** that governs how data is accessed across your organization. It centralizes authentication, authorization, policy evaluation, and access control—ensuring that every data request is properly authenticated, authorized, and audited before execution.
+---
 
-### Core Responsibilities
+## 🎯 What is VaultKit CLI?
 
-- **Authentication & Authorization**: Identity verification and access control with RBAC/ABAC support
-- **Policy Evaluation**: Fine-grained policies based on user attributes, data sensitivity, geographic regions, and time constraints
-- **Data Masking**: Column-level masking rules (full, partial, hash) applied based on user clearance
-- **Connection Management**: Centralized datasource configuration and credential management
-- **Approval Workflows**: Require explicit approval for accessing sensitive datasets
-- **Audit Logging**: Complete audit trail of every data access request
-- **Metadata Catalog**: Automated dataset classification and schema discovery
-- **Session Tokens**: Short-lived, cryptographically-signed tokens for Zero-Trust security
-- **Schema Governance**: Git-backed policy bundles with drift detection for safe schema evolution
+The VaultKit CLI provides command-line access to VaultKit for:
 
----
+- **Users** - Data analysts, engineers, and administrators
+- **AI Agents** - LLMs and autonomous systems requiring governed data access
+- **Tools & Services** - CI/CD pipelines, data pipelines, and automated workflows
+- **Applications** - Programmatic integration via scripting
 
-## ⚡ What is FUNL?
+| Capability | Description |
+|------------|-------------|
+| **Authentication** | Login, session management, identity verification |
+| **Data Requests** | Submit AQL queries with automatic policy evaluation |
+| **Approval Workflows** | Approve or deny access requests requiring authorization |
+| **Grant Management** | Fetch data using approved, time-limited grants |
+| **Datasource Admin** | Register and manage database connections (admin only) |
+| **Schema Discovery** | Scan datasources and detect schema drift |
+| **Policy Deployment** | Build, validate, and deploy policy bundles |
+| **Audit Queries** | Search and export audit logs |
 
-FUNL (Functional Universal Query Language) is the **data plane and execution engine** that powers VaultKit's query capabilities. While VaultKit decides *if* and *how* data can be accessed, FUNL handles the actual execution.
+### Mental Model
 
-### Core Responsibilities
+VaultKit uses a **request → policy → grant → fetch** workflow:
 
-- **AQL Translation**: Converts VaultKit's Abstract Query Language (AQL) into native query languages
-- **Multi-Engine Support**: Executes queries against PostgreSQL, MySQL, Snowflake, BigQuery, and more
-- **SQL Masking Engine**: Applies column-level masking at the SQL execution layer
-- **Query Execution**: Handles parameterized queries with injection prevention
-- **Result Sanitization**: Returns masked and filtered results back to VaultKit
-- **JWT Authentication**: Only accepts cryptographically-signed requests from VaultKit
+```
+┌──────────┐    ┌──────────┐    ┌───────┐    ┌───────┐    ┌───────────┐
+│ Request  │ -> │ Policy   │ -> │ Grant │ -> │ Fetch │ -> │ Audit Log │
+│ (AQL)    │    │ Eval     │    │ (JWT) │    │ Data  │    │ (Record)  │
+└──────────┘    └──────────┘    └───────┘    └───────┘    └───────────┘
+```
 
-FUNL is designed to be lightweight, stateless, and horizontally scalable—making it ideal for high-throughput data access scenarios.
+**Key Principles:**
+- Users **request** data, not queries
+- Policies **decide** what happens (allow, mask, deny, require approval)
+- Grants **authorize** execution with TTLs
+- FUNL **executes** queries safely
+- Everything is **audited**
 
 ---
 
-## 🏗️ Architecture
-
-```mermaid
-flowchart TB
-    subgraph clients["🖥️ Client Layer"]
-        app["Applications"]
-        cli["CLI Tools"]
-        agent["AI Agents"]
-    end
-
-    subgraph vaultkit["🛡️ VaultKit — Control Plane"]
-        direction TB
-        orch["Request Orchestrator"]
-        policy["Policy Engine<br/>(ABAC/RBAC)"]
-        auth["Authentication<br/>(JWT/SSO)"]
-        registry["Schema Registry"]
-        bundle["Active Policy Bundle"]
-        conn["Connection Manager"]
-        approval["Approval Workflow"]
-        audit["Audit Logger"]
-    end
-
-    subgraph funl["⚡ FUNL — Data Plane"]
-        direction TB
-        translator["AQL Translator"]
-        executor["Query Executor"]
-        masking["SQL Masking Layer"]
-    end
-
-    subgraph datasources["💾 Data Sources"]
-        pg[(PostgreSQL)]
-        mysql[(MySQL)]
-        snow[(Snowflake)]
-        bq[(BigQuery)]
-    end
-
-    subgraph governance["📋 Governance Layer"]
-        git["Git Repository<br/>(Policies & Registry)"]
-        scan["Schema Scans"]
-        cicd["CI/CD Pipeline"]
-    end
-
-    clients -->|AQL Request| orch
-    orch --> auth
-    orch --> policy
-    policy --> bundle
-    orch --> registry
-    orch --> approval
-    orch --> audit
-    orch -->|Signed Token + AQL| translator
-    
-    translator --> executor
-    executor --> masking
-    masking --> datasources
-    datasources --> masking
-    masking --> executor
-    executor --> translator
-    translator -->|Masked Results| orch
-    orch -->|Response| clients
-
-    scan -.->|Discovers Schema| datasources
-    scan -->|Drift Detection| registry
-    git -->|Deploy Bundle| bundle
-    cicd -->|Build & Validate| git
-
-    style vaultkit fill:#e3f2fd
-    style funl fill:#fff3e0
-    style datasources fill:#f3e5f5
-    style governance fill:#f1f8e9
-```
-
-### Component Breakdown
-
-#### VaultKit (Control Plane)
-
-- **Request Orchestrator**: Routes and manages the lifecycle of data access requests
-- **Policy Engine**: Evaluates ABAC/RBAC rules with support for sensitivity levels, regions, and time constraints
-  - **Policy Priority System**: `deny` > `require_approval` > `mask` > `allow`
-  - **Match Rules**: Dataset-based, field sensitivity, categories, specific field names
-  - **Context Awareness**: User role, clearance level, region, environment, time windows
-- **Authentication Service**: Handles user identity via JWT, OAuth, or SSO integration
-- **Schema Registry**: Runtime database storing discovered schemas and serving as drift baseline
-- **Active Policy Bundle**: Immutable, Git-backed artifact containing all enforcement rules
-- **Connection Manager**: Manages datasource credentials (supports VaultKit store, HashiCorp Vault, AWS Secrets Manager)
-- **Approval Workflow**: Implements multi-stage approval for sensitive data access
-- **Audit Logger**: Records every request to pluggable sinks (SQLite, PostgreSQL, S3, etc.)
-
-#### FUNL (Data Plane)
-- **AQL Translator**: Parses AQL and generates engine-specific SQL with proper escaping
-- **Query Executor**: Maintains connection pools and executes parameterized queries
-- **SQL Masking Layer**: Injects masking functions into SELECT statements based on policy
-- **Engine Plugins**: Extensible architecture for adding new database engines
-
-#### Governance Layer
-- **Git Repository**: Source of truth for all policies and dataset registries
-- **Schema Scans**: Observational tooling that discovers database changes
-- **CI/CD Pipeline**: Automated validation, bundling, and deployment of policy changes
-
----
+## 📦 Installation
 
-## 📋 Schema Discovery & Policy Management
+### Prerequisites
 
-VaultKit's approach to schema evolution is designed for **security, auditability, and safe change management**.
+- **Ruby** 3.1 or higher
+- **VaultKit Control Plane** running and accessible
 
-### The Core Philosophy: Intent vs. Reality
+### Option 1: Install from RubyGems (Recommended)
 
-VaultKit deliberately separates:
+```bash
+gem install vaultkitcli
+```
 
-- **Policy Bundles** (Intent) — Git-backed, immutable definitions of *what should be allowed*
-- **Schema Scans** (Reality) — Observational discovery of *what actually exists*
+### Verify Installation
 
-This separation prevents silent data exposure. When new tables or sensitive columns appear, they require **explicit policy review** before access is granted.
+```bash
+vkit --version
+# => VaultKit CLI v0.1.0
 
-```mermaid
-flowchart LR
-    A[Live Database] -->|1. Scan Discovers| B[Schema Changes]
-    B -->|2. Drift Detection| C[Schema Registry]
-    C -->|3. Human Review| D[Policy Updates in Git]
-    D -->|4. CI Validation| E[Build Bundle]
-    E -->|5. Deploy| F[Active Bundle]
-    F -->|Enforces| G[Access Control]
-    
-    style A fill:#f3e5f5
-    style C fill:#fff3e0
-    style D fill:#e8f5e9
-    style F fill:#e3f2fd
-    style G fill:#fce4ec
+vkit --help
 ```
 
-### How It Works
-
-**Policy Bundles** are versioned artifacts that contain:
-- Dataset registry (expected schema)
-- Datasource definitions
-- Compiled policy rules
-- Bundle metadata (version, checksum, source)
+---
 
-**Schema Scans** perform these steps:
-1. Introspect datasources via FUNL
-2. Discover tables and columns
-3. Classify fields (PII, financial, internal)
-4. Compute diff against runtime registry
-5. Surface changes for review
+## ⚡ Quick Start
 
-**Key Safety Principle:**
+### 1. Set Environment Variables
 
-> Scans inform. Bundles enforce. Humans decide.
+```bash
+export VKIT_API_URL=http://localhost:3000
+```
 
-Scans **never** automatically update active policies. This ensures:
-- No silent expansion of policy scope
-- No auto-granting access to new sensitive data
-- Full Git-based audit trail
-- Compliance with SOC2, ISO 27001, GDPR, HIPAA
+For production:
+```bash
+export VKIT_API_URL=https://vaultkit.company.com
+```
 
-### Quick Example: Handling Schema Drift
+### 2. Authenticate
 
 ```bash
-# 1. Discover schema changes (safe, read-only)
-vkit scan production_db
-
-# Output shows drift:
-# + dataset: customers
-#     + field: ssn (string) [PII] ⚠️  NEW - requires policy
-#     ~ field: email (text → varchar) [PII] ✓ Already masked
+vkit login --endpoint http://localhost:3000 --email analyst@company.com
+```
 
-# 2. Review and update baseline
-vkit scan production_db --apply
+You'll receive a prompt for your password or be redirected to SSO.
 
-# 3. Update policies in Git
-vim policies/customer_data.yaml
+### 3. Submit Your First Request
 
-# 4. Build and deploy new bundle
-vkit policy bundle
-vkit policy deploy
+```bash
+vkit request --aql '{
+  "source_table": "customers",
+  "columns": ["id", "email", "total_spend"],
+  "limit": 10
+}'
 ```
 
-### CI/CD Integration (Recommended)
+### 4. Fetch Results
 
-```yaml
-name: Schema Drift Check
-on: [schedule, push]
-jobs:
-  drift-detection:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Scan all datasources
-        run: vkit scan --all --fail-on-drift
-      
-      - name: Create PR if drift detected
-        if: failure()
-        run: |
-          vkit scan --all --diff > drift-report.md
-          gh pr create --title "Schema Drift Detected" --body-file drift-report.md
+If granted immediately:
+```bash
+vkit fetch --grant gr_abc123xyz
 ```
 
-📘 **[Full Bundling & Scan System Documentation →](./docs/BUNDLING_SCAN_SYSTEM.md)**
+If approval required:
+```bash
+# Check status
+vkit requests list --state pending
+
+# After approval
+vkit fetch --grant gr_abc123xyz
+```
 
 ---
 
-## 🔄 AQL to Native Query Translation
+## 🔐 Authentication
+
+### `vkit login`
+
+Authenticate with the VaultKit control plane.
 
-AQL (Access Query Language) is a structured JSON format that describes **what** to fetch, not **how**. This abstraction allows VaultKit to enforce policies consistently across different database engines.
+```bash
+vkit login --endpoint http://localhost:3000 --email analyst@acme.com
+```
 
-### AQL Structure
+**Options:**
+- `--endpoint` — VaultKit API endpoint (can also use `VKIT_API_URL`)
+- `--email` — Email address for authentication
 
-AQL is a structured JSON specification with the following top-level fields:
+**SSO Integration:**
 
-```json
-{
-  "source_table": "table_name",
-  "columns": ["field1", "field2"],
-  "joins": [],
-  "aggregates": [],
-  "filters": [],
-  "group_by": [],
-  "having": [],
-  "order_by": null,
-  "limit": 0,
-  "offset": 0
-}
+If your organization uses SSO, you'll be redirected to your identity provider:
+
+```bash
+vkit login --endpoint https://vaultkit.company.com --email you@company.com
+
+# Output:
+# Opening browser for SSO authentication...
+# ✓ Authentication successful
+# Session expires: 2024-01-15 18:00:00 UTC
 ```
 
-### Translation Examples
+### `vkit whoami`
 
-**Simple Query:**
-```json
-{
-  "source_table": "customers",
-  "columns": ["email", "country", "revenue"],
-  "filters": [
-    { "field": "country", "operator": "eq", "value": "US" },
-    { "field": "revenue", "operator": "gt", "value": 10000 }
-  ],
-  "limit": 100
-}
+Display the currently authenticated user and session information.
+
+```bash
+vkit whoami
 ```
 
-**FUNL Translation → PostgreSQL:**
-```sql
-SELECT email, country, revenue
-FROM customers
-WHERE country = $1 AND revenue > $2
-LIMIT 100
+**Output:**
+```
+👤 analyst@acme.com (role: analyst, org: acme)
 ```
 
-**FUNL Translation → MySQL:**
-```sql
-SELECT `email`, `country`, `revenue`
-FROM `customers`
-WHERE `country` = ? AND `revenue` > ?
-LIMIT 100
+**JSON Format:**
+```bash
+vkit whoami --format json
 ```
 
-**Complex Query with JOINs and Aggregates:**
+**Output:**
 ```json
 {
-  "source_table": "users",
-  "joins": [
-    {
-      "type": "LEFT",
-      "table": "orders",
-      "left_field": "users.id",
-      "right_field": "orders.user_id"
-    }
-  ],
-  "columns": ["users.email", "users.username"],
-  "aggregates": [
-    {
-      "func": "sum",
-      "field": "orders.amount",
-      "alias": "total_spent"
-    }
-  ],
-  "group_by": ["users.email", "users.username"],
-  "having": [
-    {
-      "operator": "gt",
-      "field": "SUM(orders.amount)",
-      "value": 500
-    }
-  ],
-  "order_by": {
-    "column": "total_spent",
-    "direction": "DESC"
-  },
-  "limit": 10
+  "email": "analyst@acme.com",
+  "role": "analyst",
+  "org": "acme"
 }
 ```
 
-**FUNL Translation → PostgreSQL:**
-```sql
-SELECT users.email, users.username, SUM(orders.amount) AS total_spent
-FROM users
-LEFT JOIN orders ON users.id = orders.user_id
-GROUP BY users.email, users.username
-HAVING SUM(orders.amount) > $1
-ORDER BY total_spent DESC
-LIMIT 10
-```
+### `vkit logout`
 
-### Advanced Features
+Clear stored credentials and end session.
 
-**Complex Filtering with OR Logic:**
-```json
-{
-  "source_table": "users",
-  "columns": ["id", "email", "role"],
-  "filters": [
-    {
-      "logic": "OR",
-      "conditions": [
-        { "field": "users.role", "operator": "eq", "value": "admin" },
-        { "field": "users.role", "operator": "eq", "value": "manager" }
-      ]
-    },
-    { "field": "orders.amount", "operator": "gt", "value": 100 }
-  ]
-}
+```bash
+vkit logout
 ```
 
-**Translation:**
-```sql
-SELECT id, email, role
-FROM users
-WHERE (users.role = $1 OR users.role = $2) AND orders.amount > $3
+---
+
+## 🔄 Core Workflows
+
+### Workflow 1: Immediate Access (Auto-Approved)
+
+```bash
+# 1. Submit request
+vkit request --aql '{
+  "source_table": "public_reports",
+  "columns": ["report_id", "title", "published_date"],
+  "limit": 10
+}'
+
+# Output:
+# ✓ Request granted immediately
+# Grant ID: gr_abc123xyz
+# TTL: 4 hours
+# Use: vkit fetch --grant gr_abc123xyz
+
+# 2. Fetch data
+vkit fetch --grant gr_abc123xyz --format table
 ```
 
-**Supported Operators:**
-- Comparison: `eq`, `neq`, `gt`, `lt`, `gte`, `lte`
-- Pattern matching: `like`
-- Set operations: `in`
-- Null checks: `is_null`, `is_not_null`
+### Workflow 2: Approval Required
 
-**Supported Aggregations:**
-- `sum`, `count`, `avg`, `min`, `max`
+```bash
+# 1. Submit request
+vkit request --aql '{
+  "source_table": "financial_transactions",
+  "columns": ["transaction_id", "amount", "customer_id"],
+  "filters": [{"field": "amount", "operator": "gt", "value": 10000}]
+}'
 
-**Supported JOINs:**
-- `INNER`, `LEFT`, `RIGHT`, `FULL`
+# Output:
+# ⏳ Approval required
+# Request ID: req_20240115_xyz789
+# Approver: finance_manager
+# Reason: Financial data requires manager approval
+# Status: PENDING
 
-### SQL-Level Masking
+# 2. Check status
+vkit requests list --state pending
 
-FUNL's **Masking Dialect System** applies transformations directly in SQL based on VaultKit's policy decisions:
+# 3. After approval, fetch data
+vkit fetch --grant gr_approved_abc123
+```
 
-| Masking Type | PostgreSQL | MySQL | Snowflake |
-|-------------|------------|-------|-----------|
-| **Full** | `'*****' AS email` | `'*****' AS email` | `'*****' AS email` |
-| **Partial** | `CONCAT(LEFT(email, 3), '****')` | `CONCAT(LEFT(email, 3), '****')` | `CONCAT(LEFT(email, 3), '****')` |
-| **Hash** | `ENCODE(SHA256(email::bytea), 'hex')` | `SHA2(email, 256)` | `SHA2(email, 256)` |
+### Workflow 3: Denied Access
 
----
+```bash
+vkit request --aql '{
+  "source_table": "payment_cards",
+  "columns": ["card_number", "cvv"],
+  "limit": 10
+}'
 
-## ✨ Key Features
-
-### VaultKit (Control Plane)
-
-| Feature | Description |
-|---------|-------------|
-| **AQL Orchestration** | Vendor-neutral query language prevents SQL injection and enables policy enforcement |
-| **Policy Engine** | Attribute-based access control with support for clearance levels, regions, sensitivity tags, and time windows |
-| **Policy Priority System** | Hierarchical decision making: `deny` > `require_approval` > `mask` > `allow` |
-| **Field-Level Policies** | Match rules based on dataset name, field sensitivity, categories (pii, financial, etc.), or specific field names |
-| **Context-Aware Rules** | Policies evaluate requester role, clearance level, region, environment, and time constraints |
-| **Approval Workflows** | Require manager/security approval for accessing PII, financial data, or production environments |
-| **Zero-Trust Sessions** | Short-lived, cryptographically-signed tokens with automatic expiration |
-| **Credential Abstraction** | Never expose database credentials to users—supports multiple secret backends |
-| **Git-Backed Governance** | All policies and registries versioned in Git with full audit trail |
-| **Schema Drift Detection** | Automated discovery of database changes with manual approval workflow |
-| **Comprehensive Auditing** | Every query logged with user identity, timestamp, policy decisions, and results metadata |
-| **CLI & SDK** | Rich command-line tools (`vkit`) and programmatic SDK for integration |
-
-### FUNL (Data Plane)
-
-| Feature | Description |
-|---------|-------------|
-| **Multi-Engine Translation** | Supports PostgreSQL, MySQL, Snowflake, BigQuery with identical AQL interface |
-| **SQL-Level Masking** | Masking applied during query execution—no post-processing overhead |
-| **Injection Prevention** | All queries use parameterized execution with proper type binding |
-| **Raw SQL Support** | Supports raw SQL for schema introspection and admin operations (policy-controlled) |
-| **Horizontal Scaling** | Stateless design enables running multiple FUNL instances behind a load balancer |
-| **JWT Verification** | Only executes queries signed by VaultKit's private key |
+# Output:
+# ❌ Request denied
+# Reason: Direct payment card data access forbidden
+# Policy: pci_dss_restrictions
+# Alternative: Use tokenized_card_id field instead
+# Audit ID: audit_20240115_denied_123
+```
 
 ---
 
-## 🚀 Getting Started
+## 📚 Command Reference
 
-### Prerequisites Checklist
+### Authentication Commands
 
-Before installing VaultKit, ensure you have:
+#### `vkit login`
 
-- [ ] **Ruby** 3.1+ installed (`ruby --version`)
-- [ ] **Go** 1.21+ installed (`go version`)
-- [ ] **OpenSSL** for key generation
-- [ ] **Git** for policy management
-- [ ] Access credentials for at least one supported datasource
-- [ ] (Optional) **Docker** for containerized FUNL deployment
+Authenticate with VaultKit.
 
-### Quick Start (5 Minutes)
-
-This streamlined path gets you querying data quickly. For production deployments, see [Detailed Setup](#detailed-setup) below.
+```bash
+vkit login --endpoint <URL> --email <EMAIL>
+```
 
-#### 1. Generate Cryptographic Keys
+**Options:**
+- `--endpoint, -e` — VaultKit API endpoint (default: `$VKIT_API_URL`)
+- `--email` — User email address
+- `--password` — Password (prompted if not provided)
 
+**Examples:**
 ```bash
-# Generate RSA key pair for token signing
-openssl genpkey -algorithm RSA -out vaultkit_private.pem -pkeyopt rsa_keygen_bits:2048
-openssl rsa -pubout -in vaultkit_private.pem -out vaultkit_public.pem
+# Interactive login
+vkit login --endpoint http://localhost:3000 --email analyst@company.com
 
-# Set environment variables
-export VKIT_PRIVATE_KEY="$(pwd)/vaultkit_private.pem"
-export VKIT_PUBLIC_KEY="$(pwd)/vaultkit_public.pem"
-export FUNL_PUBLIC_KEY="$(pwd)/vaultkit_public.pem"
+# Non-interactive (CI/CD)
+vkit login --endpoint https://vaultkit.company.com --email bot@company.com --password $BOT_PASSWORD
 ```
 
-⚠️ **Security Note**: Keep your private key secure. Add `*.pem` to your `.gitignore`.
+#### `vkit whoami`
 
-#### 2. Start FUNL
+Display current user information.
 
 ```bash
-# Using Docker (recommended)
-export FUNL_URL="http://localhost:8080"
-docker compose up -d
+vkit whoami [--format json|table]
+```
 
-# Verify FUNL is running
-curl http://localhost:8080/health
+**Examples:**
+```bash
+vkit whoami
+vkit whoami --format json
 ```
 
-#### 3. Install VaultKit CLI
+#### `vkit logout`
+
+End session and clear credentials.
 
 ```bash
-git clone https://github.com/yourorg/vaultkitcli.git
-cd vaultkitcli
-gem build vaultkitcli.gemspec
-gem install ./vaultkitcli-0.1.0.gem
+vkit logout
+```
 
-# Verify installation
-vkit --version
+---
+
+### Data Request Commands
+
+#### `vkit request`
+
+Submit a governed data request using AQL.
+
+```bash
+vkit request --aql <AQL_JSON> [OPTIONS]
 ```
 
-#### 4. Initialize & Connect
+**Options:**
+- `--aql` — AQL JSON payload (inline or via STDIN)
+- `--env` — Environment (default: `production`)
+- `--requester_region` — Your geographic region (e.g., `US`, `EU`)
+- `--dataset_region` — Dataset's geographic region
+- `--requester_clearance` — Clearance level: `low`, `high`, `admin`
+- `--format` — Output format: `json`, `table` (default: `table`)
 
+**Inline AQL:**
 ```bash
-# Authenticate
-vkit login
+vkit request \
+  --aql '{"source_table":"customers","columns":["email","total_spend"],"limit":100}' \
+  --requester_region EU \
+  --dataset_region EU \
+  --requester_clearance high
+```
 
-# Register your first datasource
-vkit datasource add \
-  --id demo_db \
-  --engine postgres \
-  --username readonly_user \
-  --password $DB_PASSWORD \
-  --config '{
-    "host": "localhost",
-    "port": 5432,
-    "database": "analytics"
-  }'
+**AQL via STDIN:**
+```bash
+cat query.json | vkit request
+
+# Or
+echo '{"source_table":"orders","columns":["order_id","total"]}' | vkit request
+```
 
-# Discover schema
-vkit scan demo_db --apply
+**AQL from File:**
+```bash
+vkit request --aql "$(cat queries/customer_analysis.json)"
 ```
 
-#### 5. Query Data
+**Possible Outcomes:**
+
+| Outcome | Description | Next Step |
+|---------|-------------|-----------|
+| ✅ **Granted** | Immediate access | `vkit fetch --grant <GRANT_ID>` |
+| ⏳ **Queued** | Requires approval | Wait for approval, check with `vkit requests list` |
+| ❌ **Denied** | Policy disallows | Review policy restrictions |
+
+#### `vkit requests list`
+
+View your request history.
 
 ```bash
-# Submit AQL query
-vkit request --datasource demo_db --aql '{
-  "source_table": "users",
-  "columns": ["id", "email", "created_at"],
-  "limit": 10
-}'
+vkit requests list [--state STATE] [--format FORMAT]
+```
+
+**Options:**
+- `--state` — Filter by state: `all`, `pending`, `approved`, `denied` (default: `all`)
+- `--format` — Output format: `json`, `table` (default: `table`)
+- `--limit` — Number of results (default: 50)
+
+**Examples:**
+```bash
+# All requests
+vkit requests list
 
-# Fetch results (use grant ID from previous command)
-vkit fetch --grant grant_abc123xyz
+# Only pending requests
+vkit requests list --state pending
+
+# Approved requests in JSON
+vkit requests list --state approved --format json
+
+# Last 100 requests
+vkit requests list --limit 100
 ```
 
-🎉 **You're now querying data through VaultKit!** Continue to [Detailed Setup](#detailed-setup) for production configuration.
+#### `vkit requests show`
+
+Show details for a specific request.
+
+```bash
+vkit requests show <REQUEST_ID>
+```
+
+**Example:**
+```bash
+vkit requests show req_20240115_xyz789
+```
 
 ---
 
-### Detailed Setup
+### Approval Commands
 
-#### Installation Options
+#### `vkit approval:list`
 
-**Option A: From Source (Recommended for Development)**
+List approval requests you are authorized to act on.
 
 ```bash
-# Clone and install CLI
-git clone https://github.com/yourorg/vaultkitcli.git
-cd vaultkitcli
-bundle install
-gem build vaultkitcli.gemspec
-gem install ./vaultkitcli-0.1.0.gem
+vkit approval:list [--state STATE] [--format FORMAT]
+```
+
+**Options:**
+- `--state` — Filter by state: `all`, `pending`, `approved`, `denied` (default: `pending`)
+- `--format` — Output format: `json`, `table` (default: `table`)
+
+**Examples:**
+```bash
+# Pending approvals
+vkit approval:list
+
+# All approvals you've handled
+vkit approval:list --state all
+
+# JSON output for scripting
+vkit approval:list --format json
+```
+
+#### `vkit approval:approve`
+
+Approve a pending request.
+
+```bash
+vkit approval:approve <REQUEST_ID> [--ttl SECONDS] [--notes "..."]
+```
 
-# Clone and build FUNL
-git clone https://github.com/yourorg/funl.git
-cd funl
-go build -o funl ./cmd/funl
-./funl serve --port 8080
+**Options:**
+- `--ttl` — Grant lifetime in seconds (default: 3600)
+- `--notes` — Approval notes (optional)
+
+**Examples:**
+```bash
+# Basic approval
+vkit approval:approve 42
+
+# With custom TTL and notes
+vkit approval:approve 42 \
+  --ttl 7200 \
+  --notes "Approved for Q4 analysis. Limited to aggregate data only."
 ```
 
-**Option B: Using Docker (Recommended for Production)**
+#### `vkit approval:deny`
+
+Deny a pending request.
 
 ```bash
-# docker-compose.yml
-version: '3.8'
-services:
-  funl:
-    image: vaultkit/funl:0.1.0
-    ports:
-      - "8080:8080"
-    environment:
-      - FUNL_PUBLIC_KEY=/keys/vaultkit_public.pem
-    volumes:
-      - ./vaultkit_public.pem:/keys/vaultkit_public.pem:ro
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
-      interval: 10s
-      timeout: 3s
-      retries: 3
+vkit approval:deny <REQUEST_ID> --reason "..."
 ```
 
-#### Environment Configuration
+**Options:**
+- `--reason` — Required explanation for denial
+
+**Examples:**
+```bash
+vkit approval:deny 42 --reason "Insufficient business justification"
+
+vkit approval:deny 42 --reason "Request violates data minimization policy"
+```
+
+---
+
+### Data Fetch Commands
 
-Create a configuration file for persistent settings:
+#### `vkit fetch`
+
+Fetch data using a previously issued grant.
 
 ```bash
-# ~/.vkit/config.yaml
-funl_url: "http://localhost:8080"
-private_key_path: "/path/to/vaultkit_private.pem"
-public_key_path: "/path/to/vaultkit_public.pem"
-default_datasource: "production_db"
-audit_log_path: "/var/log/vaultkit/audit.log"
+vkit fetch --grant <GRANT_REF> [--format FORMAT]
 ```
 
-Add environment variables to your shell profile:
+**Options:**
+- `--grant, -g` — Grant reference or ID (required)
+- `--format` — Output format: `json`, `table`, `csv` (default: `table`)
+- `--output, -o` — Write to file instead of STDOUT
+
+**Examples:**
+```bash
+# Fetch and display as table
+vkit fetch --grant gr_abc123xyz
+
+# Fetch as JSON
+vkit fetch --grant gr_abc123xyz --format json
+
+# Fetch and save to CSV
+vkit fetch --grant gr_abc123xyz --format csv --output results.csv
+
+# Pipe to jq for processing
+vkit fetch --grant gr_abc123xyz --format json | jq '.data[] | select(.revenue > 1000)'
+```
+
+---
+
+### Datasource Management (Admin Only)
+
+#### `vkit datasource add`
+
+Register a new datasource.
 
 ```bash
-# ~/.bashrc or ~/.zshrc
-export VKIT_PRIVATE_KEY="/path/to/vaultkit_private.pem"
-export VKIT_PUBLIC_KEY="/path/to/vaultkit_public.pem"
-export FUNL_PUBLIC_KEY="/path/to/vaultkit_public.pem"
-export FUNL_URL="http://localhost:8080"
-export VKIT_CONFIG_PATH="$HOME/.vkit/config.yaml"
+vkit datasource add --id <ID> --engine <ENGINE> [OPTIONS]
 ```
 
-#### Datasource Configuration
+**Options:**
+- `--id` — Unique datasource identifier (required)
+- `--engine` — Database engine: `postgres`, `mysql`, `snowflake`, `bigquery` (required)
+- `--username` — Database username
+- `--password` — Database password
+- `--config` — JSON configuration (host, port, database, etc.)
+- `--credential-backend` — Secret backend: `vaultkit`, `vault`, `aws-secrets`
 
-VaultKit supports multiple credential storage backends:
+**Examples:**
 
-**Built-in Storage (Development):**
+**PostgreSQL (Built-in credential storage):**
 ```bash
 vkit datasource add \
-  --id staging_db \
+  --id production_pg \
   --engine postgres \
-  --username app_user \
+  --username vaultkit_ro \
   --password $DB_PASSWORD \
   --config '{
-    "host": "staging.db.internal",
+    "host": "db.production.internal",
     "port": 5432,
     "database": "analytics",
     "ssl_mode": "require",
@@ -613,349 +545,594 @@ vkit datasource add \
   }'
 ```
 
-**HashiCorp Vault (Production):**
+**MySQL:**
 ```bash
 vkit datasource add \
-  --id production_db \
-  --engine postgres \
-  --credential-backend vault \
-  --vault-path secret/data/databases/production \
+  --id production_mysql \
+  --engine mysql \
+  --username app_reader \
+  --password $MYSQL_PASSWORD \
   --config '{
-    "host": "prod.db.internal",
-    "port": 5432,
-    "database": "analytics",
-    "ssl_mode": "verify-full"
+    "host": "mysql.production.internal",
+    "port": 3306,
+    "database": "ecommerce",
+    "ssl_mode": "REQUIRED"
   }'
 ```
 
-**AWS Secrets Manager:**
+#### `vkit datasource list`
+
+List all registered datasources.
+
 ```bash
-vkit datasource add \
-  --id cloud_db \
-  --engine postgres \
-  --credential-backend aws-secrets \
-  --secret-arn arn:aws:secretsmanager:us-east-1:123456789:secret:db-creds \
-  --config '{
-    "host": "rds.amazonaws.com",
-    "port": 5432,
-    "database": "production"
-  }'
+vkit datasource list [--format FORMAT]
 ```
 
-#### Policy Setup
+**Examples:**
+```bash
+vkit datasource list
+vkit datasource list --format json
+```
+
+#### `vkit datasource get`
 
-Initialize your policy repository:
+Get details for a specific datasource.
 
 ```bash
-# Create policy repository structure
-mkdir -p vaultkit-policies/{policies,registries,datasources}
-cd vaultkit-policies
+vkit datasource get <DATASOURCE_ID>
+```
 
-git init
-git add .
-git commit -m "Initialize VaultKit policies"
+**Example:**
+```bash
+vkit datasource get production_pg
+```
 
-# Link VaultKit to your policy repo
-vkit policy init --repo $(pwd)
+#### `vkit datasource test`
+
+Test connectivity to a datasource.
+
+```bash
+vkit datasource test <DATASOURCE_ID>
 ```
 
-Create your first policy (`policies/base_access.yaml`):
+**Example:**
+```bash
+vkit datasource test production_pg
 
-```yaml
-id: analyst_basic_access
-description: Basic read access for analysts with PII masking
-priority: 100
+# Output:
+# Testing connection to production_pg...
+# ✓ Connection successful
+# Engine: PostgreSQL 15.3
+# Latency: 45ms
+```
+
+#### `vkit datasource remove`
 
-match:
-  datasets:
-    - customers
-    - orders
-  
-context:
-  requester_role: analyst
-  environment: production
+Remove a datasource (admin only).
 
-rules:
-  - field_category: pii
-    action: mask
-    mask_type: partial
-    reason: "PII must be masked for analysts"
-  
-  - field_category: financial
-    action: require_approval
-    approver_role: finance_manager
-    ttl: "2h"
-    reason: "Financial data requires approval"
-  
-  - default:
-      action: allow
-      ttl: "8h"
+```bash
+vkit datasource remove <DATASOURCE_ID> [--force]
 ```
 
-Build and deploy the policy bundle:
+**Options:**
+- `--force` — Skip confirmation prompt
 
+**Example:**
 ```bash
-# Validate policies
-vkit policy validate
+vkit datasource remove old_staging_db --force
+```
+
+---
 
-# Build bundle
-vkit policy bundle --output bundle.tar.gz
+### Schema Discovery Commands
 
-# Deploy to active control plane
-vkit policy deploy --bundle bundle.tar.gz
+#### `vkit scan`
+
+Scan a datasource and detect schema drift.
+
+```bash
+vkit scan <DATASOURCE_ID> [--mode MODE]
+```
+
+**Options:**
+- `--mode` — Scan mode: `diff`, `apply` (default: `diff`)
+- `--format` — Output format: `json`, `table` (default: `table`)
+
+**Modes:**
+
+| Mode | Description |
+|------|-------------|
+| `diff` | Show changes without applying (safe, read-only) |
+| `apply` | Update baseline registry with discovered schema |
+
+**Examples:**
+
+**Discover Changes:**
+```bash
+vkit scan production_pg
+
+# Output:
+# Scanning datasource: production_pg
+# 
+# Schema Drift Detected:
+# 
+# + Dataset: customers
+#     + Field: phone_number (varchar) [PII] ⚠️  NEW - requires policy
+#     ~ Field: email (text → varchar) [PII] ✓ Already masked
+# 
+# + Dataset: user_sessions
+#     + Field: ip_address (inet) [PII] ⚠️  NEW - requires policy
+#     + Field: user_agent (text) [INTERNAL] ⚠️  NEW - requires policy
+# 
+# Summary: 2 new datasets, 3 new fields, 1 modified field
+```
+
+**Apply Changes:**
+```bash
+vkit scan production_pg --mode apply
+
+# Output:
+# ✓ Baseline registry updated
+# Next steps:
+#   1. Review new fields: customers.phone_number, user_sessions.ip_address
+#   2. Update policies in Git: config/policies/
+#   3. Build new bundle: vkit policy bundle
+#   4. Deploy bundle: vkit policy deploy
+```
+
+**Scan All Datasources:**
+```bash
+for ds in $(vkit datasource list --format json | jq -r '.[].id'); do
+  echo "Scanning $ds..."
+  vkit scan $ds
+done
 ```
 
 ---
 
-## 🎯 Use Cases
+### Policy Management Commands
 
-### 1. **Secure AI Agent Access**
-Enable LLM-powered agents to query production databases without exposing credentials. VaultKit enforces policies that restrict which tables and columns AI agents can access, with automatic masking of sensitive fields.
+#### `vkit policy bundle`
 
-**Problem:**
-- AI agents need data context for decision-making
-- Direct database access creates security risks
-- Credentials in AI systems can leak
-- Uncontrolled queries can expose sensitive data
+Compile policies and registry into a deployable bundle.
 
-**VaultKit Solution:**
+```bash
+vkit policy bundle [OPTIONS]
+```
 
-```yaml
-# policies/ai_agent_restrictions.yaml
-id: ai_agent_restrictions
-match:
-  fields:
-    category: pii
+**Options:**
+- `--policies_dir` — Path to policies directory (default: `config/policies`)
+- `--registry_dir` — Path to registry files (default: `config`)
+- `--datasources_dir` — Path to datasource configs (default: `config/datasources`)
+- `--out` — Output bundle file (default: `dist/policy_bundle.json`)
+- `--org` — Organization identifier (optional, defaults to logged-in user's org)
+
+**Example:**
+```bash
+# Using logged-in user's org
+vkit policy bundle \
+  --policies_dir config/policies \
+  --registry_dir config \
+  --datasources_dir config/datasources \
+  --out dist/policy_bundle.json
+
+# Specifying org explicitly
+vkit policy bundle \
+  --policies_dir config/policies \
+  --registry_dir config \
+  --datasources_dir config/datasources \
+  --out dist/policy_bundle.json \
+  --org acme
+```
+
+#### `vkit policy validate`
+
+Validate a policy bundle without deploying.
+
+```bash
+vkit policy validate --bundle <BUNDLE_FILE>
+```
 
-context:
-  requester_role: ai_agent
-  environment: production
+**Example:**
+```bash
+vkit policy validate --bundle dist/policy_bundle.json
+
+# Output:
+# Validating policy bundle...
+# ✓ Schema validation passed
+# ✓ Policy syntax valid
+# ✓ No circular dependencies
+# ✓ All datasources referenced
+# Bundle is valid and ready to deploy
+```
+
+#### `vkit policy deploy`
 
-action:
-  mask: true
-  mask_type: hash
-  reason: "PII must be hashed for AI agents"
-  ttl: "15m"
+Deploy a policy bundle to the control plane.
+
+```bash
+vkit policy deploy --bundle <BUNDLE_FILE> [OPTIONS]
 ```
 
-**How it works:**
-1. AI agents receive short-lived session tokens (15 minutes)
-2. All PII fields automatically hashed before results return
-3. Agents can analyze patterns without accessing raw sensitive data
-4. Every query logged with AI agent identity
+**Options:**
+- `--bundle` — Path to bundle file (required)
+- `--org` — Organization identifier (optional, defaults to logged-in user's org)
+- `--activate` — Immediately activate bundle
+- `--dry-run` — Validate deployment without activating
 
-**CLI Usage:**
+**Examples:**
 ```bash
-# AI agent requests data
-vkit request \
-  --datasource production_db \
-  --role ai_agent \
-  --aql '{
-    "source_table": "customer_behavior",
-    "columns": ["user_id", "email", "purchase_amount"],
-    "filters": [{"field": "purchase_amount", "operator": "gt", "value": 1000}]
-  }'
+# Deploy and activate (using logged-in user's org)
+vkit policy deploy \
+  --bundle dist/policy_bundle.json \
+  --activate
+
+# Deploy with explicit org
+vkit policy deploy \
+  --bundle dist/policy_bundle.json \
+  --org acme \
+  --activate
+
+# Dry run (test deployment)
+vkit policy deploy \
+  --bundle dist/policy_bundle.json \
+  --dry-run
+```
+
+#### `vkit policy list`
 
-# Result: email field is hashed
-# {
-#   "user_id": 12345,
-#   "email": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-#   "purchase_amount": 1250.00
-# }
+List active policy bundles.
+
+```bash
+vkit policy list
+```
+
+#### `vkit policy show`
+
+Show details of a specific policy.
+
+```bash
+vkit policy show <POLICY_ID>
 ```
 
 ---
 
-### 2. **Cross-Region Compliance (GDPR, CCPA, HIPAA)**
-Automatically mask or deny access to sensitive fields based on user location and data residency requirements.
+### Audit Commands
 
-**Problem:**
-- GDPR prohibits transferring EU citizen data outside EU
-- CCPA requires disclosure of data access by California residents
-- HIPAA restricts PHI access based on business need
-- Manual compliance is error-prone and doesn't scale
+#### `vkit audit query`
 
-**VaultKit Solution:**
+Search audit logs.
 
-```yaml
-# policies/gdpr_protection.yaml
-id: gdpr_cross_region_deny
-match:
-  dataset: eu_customers
-  fields:
-    category: pii
-
-context:
-  requester_region: US
-  dataset_region: EU
-
-action:
-  deny: true
-  reason: "Cross-region PII access forbidden due to GDPR Article 44"
-  audit_flag: compliance_violation
+```bash
+vkit audit query [OPTIONS]
+```
+
+**Options:**
+- `--user` — Filter by user email
+- `--action` — Filter by action: `granted`, `denied`, `pending`
+- `--dataset` — Filter by dataset name
+- `--days` — Look back N days (default: 7)
+- `--limit` — Number of results (default: 100)
+- `--format` — Output format: `json`, `table`, `csv`
+
+**Examples:**
+```bash
+# All queries by a user
+vkit audit query --user analyst@company.com --days 30
+
+# Denied access attempts
+vkit audit query --action denied --days 7
+
+# Access to specific dataset
+vkit audit query --dataset customers --action granted
+
+# Export to CSV
+vkit audit query --user analyst@company.com --format csv --output audit_report.csv
+```
+
+#### `vkit audit export`
+
+Export audit logs for compliance reporting.
+
+```bash
+vkit audit export --start-date <DATE> --end-date <DATE> [OPTIONS]
+```
+
+**Options:**
+- `--start-date` — Start date (YYYY-MM-DD)
+- `--end-date` — End date (YYYY-MM-DD)
+- `--format` — Output format: `json`, `csv` (default: `csv`)
+- `--output` — Output file path
+
+**Example:**
+```bash
+vkit audit export \
+  --start-date 2024-01-01 \
+  --end-date 2024-01-31 \
+  --format csv \
+  --output compliance_reports/january_2024.csv
+```
 
 ---
-id: ccpa_disclosure_logging
-match:
-  dataset: california_residents
 
-context:
-  requester_region: ANY
+## 🔬 Advanced Usage
 
-action:
-  allow: true
-  ttl: "1h"
-  audit_metadata:
-    ccpa_disclosure: true
-    data_subject_rights: "User has right to know about this access"
+### Scripting with vkit
+
+**Batch Request Processing:**
+
+```bash
+#!/bin/bash
+# process_requests.sh
+
+REQUESTS=(
+  '{"source_table":"customers","columns":["id","email"],"limit":100}'
+  '{"source_table":"orders","columns":["order_id","total"],"limit":100}'
+  '{"source_table":"products","columns":["product_id","name"],"limit":100}'
+)
+
+for aql in "${REQUESTS[@]}"; do
+  echo "Processing: $aql"
+  vkit request --aql "$aql" --format json | jq -r '.grant_id' >> grants.txt
+done
+
+echo "Generated grants:"
+cat grants.txt
 ```
 
-**How it works:**
-- US-based analysts querying EU customer data are automatically denied
-- Policy engine evaluates both requester and dataset regions
-- Audit log captures denied attempts with compliance flags
-- CCPA-flagged queries generate disclosure reports
+**Automated Approvals (for testing):**
 
-**Multi-Region Access Pattern:**
 ```bash
-# US analyst attempts to query EU data
-vkit request --datasource eu_customers_db --aql '{...}'
+#!/bin/bash
+# auto_approve_pending.sh
 
-# Response:
-# ❌ Access Denied
-# Reason: Cross-region PII access forbidden due to GDPR Article 44
-# Policy: gdpr_cross_region_deny
-# Audit ID: audit_20240115_abc123
+PENDING=$(vkit approval:list --state pending --format json)
+
+echo "$PENDING" | jq -r '.[].id' | while read -r request_id; do
+  echo "Approving request: $request_id"
+  vkit approval:approve "$request_id" --ttl 3600 --notes "Auto-approved for testing"
+done
+```
+
+### Integration with CI/CD
+
+**GitHub Actions Example:**
+
+```yaml
+name: Deploy VaultKit Policies
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'config/policies/**'
+      - 'config/registry.yaml'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Install vkit CLI
+        run: gem install vaultkitcli
+      
+      - name: Authenticate
+        run: |
+          vkit login \
+            --endpoint ${{ secrets.VKIT_API_URL }} \
+            --email ${{ secrets.VKIT_BOT_EMAIL }} \
+            --password ${{ secrets.VKIT_BOT_PASSWORD }}
+      
+      - name: Build Policy Bundle
+        run: |
+          vkit policy bundle \
+            --policies_dir config/policies \
+            --registry_dir config \
+            --out policy_bundle.json \
+            --org ${{ secrets.ORG_ID }}
+      
+      - name: Validate Bundle
+        run: vkit policy validate --bundle policy_bundle.json
+      
+      - name: Deploy Bundle
+        run: |
+          vkit policy deploy \
+            --bundle policy_bundle.json \
+            --org ${{ secrets.ORG_ID }} \
+            --activate
+```
+
+### Using jq for Advanced Filtering
+
+**Extract specific fields:**
+```bash
+vkit requests list --format json | jq '.[] | select(.state == "approved") | {id, dataset, requester}'
+```
+
+**Count requests by state:**
+```bash
+vkit requests list --format json | jq 'group_by(.state) | map({state: .[0].state, count: length})'
+```
+
+**Find high-value transactions:**
+```bash
+vkit fetch --grant gr_abc123 --format json | jq '.data[] | select(.amount > 10000)'
 ```
 
 ---
 
-### 3. **Just-In-Time Access (Break-Glass)**
-Developers can request temporary elevated access to production data with automatic approval workflows and audit trails.
+## 🐛 Troubleshooting
+
+### Common Issues
+
+#### Authentication Failed
 
 **Problem:**
-- Engineers need emergency production access for incident resolution
-- Standing privileges violate principle of least privilege
-- Manual approval processes slow incident response
-- Audit trails are incomplete or manual
+```
+Error: Authentication failed (401 Unauthorized)
+```
 
-**VaultKit Solution:**
+**Solutions:**
+```bash
+# 1. Check endpoint
+echo $VKIT_API_URL
 
-```yaml
-# policies/financial_requires_approval.yaml
-id: financial_break_glass
-match:
-  fields:
-    category: financial
-
-context:
-  environment: production
-  requester_role: engineer
-
-action:
-  require_approval: true
-  approver_role: finance_manager
-  approval_metadata_required:
-    - incident_ticket
-    - business_justification
-  ttl: "1h"
-  reason: "Financial data access requires approval"
-  auto_revoke: true
-```
-
-**CLI Usage:**
-```bash
-# Engineer requests emergency access
-vkit request \
-  --datasource production_db \
-  --approval-required \
-  --reason "Investigating payment processing failure - Ticket INC-5432" \
-  --metadata '{"incident_ticket": "INC-5432", "business_justification": "Payment processor reporting transaction mismatch"}' \
-  --duration "2h" \
-  --aql '{
-    "source_table": "transactions",
-    "columns": ["transaction_id", "amount", "status"],
-    "filters": [{"field": "status", "operator": "eq", "value": "failed"}]
-  }'
+# 2. Re-authenticate
+vkit logout
+vkit login --endpoint http://localhost:3000 --email you@company.com
 
-# Response:
-# ⏳ Approval Required
-# Request ID: req_20240115_xyz789
-# Status: PENDING
-# Approver: finance_manager
-# Expires: 2024-01-15 18:30 UTC
+# 3. Verify credentials
+vkit whoami
 ```
 
-**Approval Workflow:**
+#### Connection Refused
+
+**Problem:**
+```
+Error: Connection refused - connect(2) for "localhost" port 3000
+```
+
+**Solutions:**
 ```bash
-# Finance manager reviews request
-vkit approval list --pending
+# 1. Check if control plane is running
+curl http://localhost:3000/health
 
-# Approve with notes
-vkit approval grant \
-  --request-id req_20240115_xyz789 \
-  --notes "Approved for incident resolution. Access limited to failed transactions only."
+# 2. Verify Docker containers
+cd infra
+docker compose ps
 
-# Engineer notified and can fetch data
-vkit fetch --grant grant_approved_abc123
+# 3. Start services
+docker compose up
 ```
 
-**Audit Trail Output:**
-```json
-{
-  "request_id": "req_20240115_xyz789",
-  "requester": "engineer@company.com",
-  "requester_role": "engineer",
-  "requested_at": "2024-01-15T16:00:00Z",
-  "approved_by": "finance.manager@company.com",
-  "approved_at": "2024-01-15T16:05:32Z",
-  "approval_reason": "Approved for incident resolution",
-  "access_granted": "2024-01-15T16:05:32Z",
-  "access_expires": "2024-01-15T18:05:32Z",
-  "queries_executed": 3,
-  "rows_accessed": 147,
-  "incident_ticket": "INC-5432",
-  "auto_revoked": true
-}
+#### Grant Expired
+
+**Problem:**
+```
+Error: Grant has expired
+Grant ID: gr_abc123xyz
+Expired at: 2024-01-15 12:00:00 UTC
 ```
 
----
+**Solutions:**
+```bash
+# 1. Request new grant
+vkit request --aql '{"source_table":"customers",...}'
+
+# 2. Request longer TTL (if approval required)
+vkit request --aql '{...}' --ttl 7200
+```
 
-### 4. **Time-Restricted Access Windows**
-Enforce access controls based on business hours, maintenance windows, or compliance requirements.
+#### Policy Denial
 
 **Problem:**
-- Audit logs should only be accessible during business hours
-- Production data access outside work hours indicates potential misuse
-- Compliance requires time-based controls for certain datasets
+```
+❌ Request denied
+Reason: Cross-region PII access forbidden
+Policy: gdpr_protection
+```
 
-**VaultKit Solution:**
+**Solutions:**
+1. Review policy restrictions
+2. Request approval if available
+3. Modify query to exclude restricted fields
+4. Contact admin to update policies
 
-```yaml
-# policies/time_restricted_access.yaml
-id: business_hours_only
-match:
-  dataset: audit_logs
-  environment: production
-
-context:
-  time:
-    start: "08:00"
-    end: "18:00"
-    timezone: "America/Toronto"
-    days: ["monday", "tuesday", "wednesday", "thursday", "friday"]
-
-action:
-  allow: true
-  reason: "Access allowed during business hours"
-  ttl: "1h"
+### Debug Mode
+
+Enable verbose logging:
+
+```bash
+# Set debug environment variable
+export VKIT_DEBUG=true
+
+# Run command
+vkit request --aql '{...}'
+
+# Output includes:
+# - HTTP request/response details
+# - Policy evaluation trace
+# - Timing information
+```
+
+### Health Check
+
+Verify CLI and control plane connectivity:
+
+```bash
+# Check CLI version
+vkit --version
+
+# Check control plane health
+curl $VKIT_API_URL/health
+
+# Test authentication
+vkit whoami
+```
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions to the VaultKit CLI!
+
+### Development Setup
+
+```bash
+# Clone repository
+git clone https://github.com/yourorg/vaultkit-cli.git
+cd vaultkit-cli
+
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run CLI locally
+bundle exec bin/vkit --help
+```
+
+### Running Tests
+
+```bash
+# Unit tests
+bundle exec rspec spec/unit
+
+# Integration tests (requires running control plane)
+bundle exec rspec spec/integration
+
+# All tests
+bundle exec rspec
+```
+
+### Code Style
+
+```bash
+# Run RuboCop
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -a
+```
+
+---
+
+## 📚 Additional Resources
+
+- **Main Repository**: [github.com/ndbaba1/vaultkitcli.git](https://github.com/ndbaba1/vaultkitcli.git)
+- **Documentation**: [docs.vaultkit.io](https://docs.vaultkit.io)
+- **AQL Specification**: [docs.vaultkit.io/aql](https://docs.vaultkit.io/aql)
+- **Policy Reference**: [docs.vaultkit.io/policies](https://docs.vaultkit.io/policies)
+- **API Documentation**: [docs.vaultkit.io/api](https://docs.vaultkit.io/api)
 
 ---
-id: after_hours_deny
-match:
-  dataset: audit_logs
-  environment: production
-
-context:
-  time:
-    outside_window
+
+## 📄 License
+
+VaultKit CLI is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.
+
+---
+
+**Built with ❤️ by the VaultKit team**