vaultkit 0.1.0 → 0.1.1

data/README.md

@@ -1,611 +1,539 @@
-# 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.
-
-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
-
-- **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
+- [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)
 
 ---
 
-## ⚡ What is FUNL?
+## 🎯 What is VaultKit CLI?
 
-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.
+The VaultKit CLI provides command-line access to:
 
-### Core Responsibilities
+| 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 |
 
-- **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
+### Mental Model
 
-FUNL is designed to be lightweight, stateless, and horizontally scalable—making it ideal for high-throughput data access scenarios.
+VaultKit uses a **request → policy → grant → fetch** workflow:
 
----
+```
+┌──────────┐    ┌──────────┐    ┌───────┐    ┌───────┐    ┌───────────┐
+│ Request  │ -> │ Policy   │ -> │ Grant │ -> │ Fetch │ -> │ Audit Log │
+│ (AQL)    │    │ Eval     │    │ (JWT) │    │ Data  │    │ (Record)  │
+└──────────┘    └──────────┘    └───────┘    └───────┘    └───────────┘
+```
 
-## 🏗️ 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
+**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**
 
 ---
 
-## 📋 Schema Discovery & Policy Management
+## 📦 Installation
 
-VaultKit's approach to schema evolution is designed for **security, auditability, and safe change management**.
+### Prerequisites
 
-### The Core Philosophy: Intent vs. Reality
+- **Ruby** 3.1 or higher
+- **VaultKit Control Plane** running and accessible
 
-VaultKit deliberately separates:
+### Option 1: Install from RubyGems (Recommended)
 
-- **Policy Bundles** (Intent) — Git-backed, immutable definitions of *what should be allowed*
-- **Schema Scans** (Reality) — Observational discovery of *what actually exists*
+```bash
+gem install vaultkitcli
+```
 
-This separation prevents silent data exposure. When new tables or sensitive columns appear, they require **explicit policy review** before access is granted.
+### Option 2: Install from Source
 
-```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
+```bash
+git clone https://github.com/yourorg/vaultkit-cli.git
+cd vaultkit-cli
+bundle install
+gem build vaultkitcli.gemspec
+gem install ./vaultkitcli-0.1.0.gem
 ```
 
-### How It Works
+### Verify Installation
 
-**Policy Bundles** are versioned artifacts that contain:
-- Dataset registry (expected schema)
-- Datasource definitions
-- Compiled policy rules
-- Bundle metadata (version, checksum, source)
+```bash
+vkit --version
+# => VaultKit CLI v0.1.0
 
-**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
+vkit --help
+```
 
-**Key Safety Principle:**
+---
 
-> Scans inform. Bundles enforce. Humans decide.
+## ⚡ Quick Start
 
-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
+### 1. Set Environment Variables
 
-### Quick Example: Handling Schema Drift
+```bash
+export VKIT_API_URL=http://localhost:3000
+```
 
+For production:
 ```bash
-# 1. Discover schema changes (safe, read-only)
-vkit scan production_db
+export VKIT_API_URL=https://vaultkit.company.com
+```
 
-# Output shows drift:
-# + dataset: customers
-#     + field: ssn (string) [PII] ⚠️  NEW - requires policy
-#     ~ field: email (text → varchar) [PII] ✓ Already masked
+### 2. Authenticate
 
-# 2. Review and update baseline
-vkit scan production_db --apply
+```bash
+vkit login --endpoint http://localhost:3000 --email analyst@company.com
+```
 
-# 3. Update policies in Git
-vim policies/customer_data.yaml
+You'll receive a prompt for your password or be redirected to SSO.
 
-# 4. Build and deploy new bundle
-vkit policy bundle
-vkit policy deploy
+### 3. Submit Your First Request
+
+```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 g_customers_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 g_customers_abc123xyz
+```
 
 ---
 
-## 🔄 AQL to Native Query Translation
+## 🔐 Authentication
+
+### `vkit login`
+
+Authenticate with the VaultKit control plane.
+
+```bash
+vkit login --endpoint http://localhost:3000 --email analyst@acme.com
+```
 
-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.
+**Options:**
+- `--endpoint` — VaultKit API endpoint (can also use `VKIT_API_URL`)
+- `--email` — Email address for authentication
 
-### AQL Structure
+**SSO Integration:**
 
-AQL is a structured JSON specification with the following top-level fields:
+If your organization uses SSO, you'll be redirected to your identity provider:
 
-```json
-{
-  "source_table": "table_name",
-  "columns": ["field1", "field2"],
-  "joins": [],
-  "aggregates": [],
-  "filters": [],
-  "group_by": [],
-  "having": [],
-  "order_by": null,
-  "limit": 0,
-  "offset": 0
-}
+```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
-}
-```
-
-**FUNL Translation → PostgreSQL:**
-```sql
-SELECT email, country, revenue
-FROM customers
-WHERE country = $1 AND revenue > $2
-LIMIT 100
-```
-
-**FUNL Translation → MySQL:**
-```sql
-SELECT `email`, `country`, `revenue`
-FROM `customers`
-WHERE `country` = ? AND `revenue` > ?
-LIMIT 100
-```
-
-**Complex Query with JOINs and Aggregates:**
-```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
-}
+Display the currently authenticated user and session information.
+
+```bash
+vkit whoami
 ```
 
-**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
+**Output:**
+```
+User ID:         user_12345
+Email:           analyst@company.com
+Role:            analyst
+Clearance Level: 2 (high)
+Region:          US
+Session Expires: 2024-01-15 18:00:00 UTC
 ```
 
-### Advanced Features
+### `vkit logout`
+
+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: g_customers_abc123xyz
+# TTL: 4 hours
+# Use: vkit fetch --grant g_customers_abc123xyz
+
+# 2. Fetch data
+vkit fetch --grant g_customers_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 g_customers_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
-
-### Prerequisites Checklist
+## 📚 Command Reference
 
-Before installing VaultKit, ensure you have:
+### Authentication Commands
 
-- [ ] **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
+#### `vkit login`
 
-### Quick Start (5 Minutes)
+Authenticate with VaultKit.
 
-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
+
+# Only pending requests
+vkit requests list --state pending
+
+# Approved requests in JSON
+vkit requests list --state approved --format json
 
-# Fetch results (use grant ID from previous command)
-vkit fetch --grant grant_abc123xyz
+# Last 100 requests
+vkit requests list --limit 100
+```
+
+#### `vkit requests show`
+
+Show details for a specific request.
+
+```bash
+vkit requests show <REQUEST_ID>
 ```
 
-🎉 **You're now querying data through VaultKit!** Continue to [Detailed Setup](#detailed-setup) for production configuration.
+**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]
+```
 
-# 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:**
+- `--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
 ```
 
-**Option B: Using Docker (Recommended for Production)**
+#### `vkit approval:approve`
+
+Approve 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:approve <REQUEST_ID> [--ttl SECONDS] [--notes "..."]
 ```
 
-#### Environment Configuration
+**Options:**
+- `--ttl` — Grant lifetime in seconds (default: 3600)
+- `--notes` — Approval notes (optional)
 
-Create a configuration file for persistent settings:
+**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."
+```
+
+#### `vkit approval:deny`
+
+Deny a pending request.
 
 ```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 approval:deny <REQUEST_ID> --reason "..."
 ```
 
-Add environment variables to your shell profile:
+**Options:**
+- `--reason` — Required explanation for denial
 
+**Examples:**
 ```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 approval:deny 42 --reason "Insufficient business justification"
+
+vkit approval:deny 42 --reason "Request violates data minimization policy"
 ```
 
-#### Datasource Configuration
+---
 
-VaultKit supports multiple credential storage backends:
+### Data Fetch Commands
+
+#### `vkit fetch`
+
+Fetch data using a previously issued grant.
 
-**Built-in Storage (Development):**
+```bash
+vkit fetch --grant <GRANT_REF> [--format FORMAT]
+```
+
+**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 g_customers_abc123xyz
+
+# Fetch as JSON
+vkit fetch --grant g_customers_abc123xyz --format json
+
+# Fetch and save to CSV
+vkit fetch --grant g_customers_abc123xyz --format csv --output results.csv
+
+# Pipe to jq for processing
+vkit fetch --grant g_customers_abc123xyz --format json | jq '.data[] | select(.revenue > 1000)'
+```
+
+---
+
+### Datasource Management (Admin Only)
+
+#### `vkit datasource add`
+
+Register a new datasource.
+
+```bash
+vkit datasource add --id <ID> --engine <ENGINE> [OPTIONS]
+```
+
+**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`
+
+**Examples:**
+
+**PostgreSQL:**
 ```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 +541,669 @@ vkit datasource add \
   }'
 ```
 
-**HashiCorp Vault (Production):**
+**With HashiCorp Vault:**
 ```bash
 vkit datasource add \
-  --id production_db \
+  --id production_pg \
   --engine postgres \
   --credential-backend vault \
   --vault-path secret/data/databases/production \
   --config '{
-    "host": "prod.db.internal",
+    "host": "db.production.internal",
     "port": 5432,
     "database": "analytics",
     "ssl_mode": "verify-full"
   }'
 ```
 
-**AWS Secrets Manager:**
+**Snowflake:**
 ```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 \
+  --id snowflake_prod \
+  --engine snowflake \
+  --username analytics_user \
+  --password $SNOWFLAKE_PASSWORD \
   --config '{
-    "host": "rds.amazonaws.com",
-    "port": 5432,
-    "database": "production"
+    "account": "xy12345.us-east-1",
+    "warehouse": "ANALYTICS_WH",
+    "database": "PRODUCTION",
+    "schema": "PUBLIC"
   }'
 ```
 
-#### Policy Setup
+#### `vkit datasource list`
 
-Initialize your policy repository:
+List all registered datasources.
 
 ```bash
-# Create policy repository structure
-mkdir -p vaultkit-policies/{policies,registries,datasources}
-cd vaultkit-policies
+vkit datasource list [--format FORMAT]
+```
+
+**Examples:**
+```bash
+vkit datasource list
+vkit datasource list --format json
+```
 
-git init
-git add .
-git commit -m "Initialize VaultKit policies"
+#### `vkit datasource get`
 
-# Link VaultKit to your policy repo
-vkit policy init --repo $(pwd)
+Get details for a specific datasource.
+
+```bash
+vkit datasource get <DATASOURCE_ID>
 ```
 
-Create your first policy (`policies/base_access.yaml`):
+**Example:**
+```bash
+vkit datasource get production_pg
+```
 
-```yaml
-id: analyst_basic_access
-description: Basic read access for analysts with PII masking
-priority: 100
+#### `vkit datasource test`
 
-match:
-  datasets:
-    - customers
-    - orders
-  
-context:
-  requester_role: analyst
-  environment: production
+Test connectivity to a datasource.
 
-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 test <DATASOURCE_ID>
 ```
 
-Build and deploy the policy bundle:
+**Example:**
+```bash
+vkit datasource test production_pg
+
+# Output:
+# Testing connection to production_pg...
+# ✓ Connection successful
+# Engine: PostgreSQL 15.3
+# Latency: 45ms
+```
+
+#### `vkit datasource remove`
+
+Remove a datasource (admin only).
 
 ```bash
-# Validate policies
-vkit policy validate
+vkit datasource remove <DATASOURCE_ID> [--force]
+```
 
-# Build bundle
-vkit policy bundle --output bundle.tar.gz
+**Options:**
+- `--force` — Skip confirmation prompt
 
-# Deploy to active control plane
-vkit policy deploy --bundle bundle.tar.gz
+**Example:**
+```bash
+vkit datasource remove old_staging_customers_db --force
 ```
 
 ---
 
-## 🎯 Use Cases
+### Schema Discovery 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 scan`
 
-**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
+Scan a datasource and detect schema drift.
 
-**VaultKit Solution:**
+```bash
+vkit scan <DATASOURCE_ID> [--mode MODE]
+```
 
-```yaml
-# policies/ai_agent_restrictions.yaml
-id: ai_agent_restrictions
-match:
-  fields:
-    category: pii
+**Options:**
+- `--mode` — Scan mode: `diff`, `apply` (default: `diff`)
+- `--format` — Output format: `json`, `table` (default: `table`)
 
-context:
-  requester_role: ai_agent
-  environment: production
+**Modes:**
 
-action:
-  mask: true
-  mask_type: hash
-  reason: "PII must be hashed for AI agents"
-  ttl: "15m"
+| 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
 ```
 
-**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
+**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
+```
 
-**CLI Usage:**
+**Scan All Datasources:**
 ```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}]
-  }'
+for ds in $(vkit datasource list --format json | jq -r '.[].id'); do
+  echo "Scanning $ds..."
+  vkit scan $ds
+done
+```
+
+---
+
+### Policy Management Commands
+
+#### `vkit policy bundle`
+
+Compile policies and registry into a deployable bundle.
+
+```bash
+vkit policy bundle [OPTIONS]
+```
+
+**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
+
+**Example:**
+```bash
+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>
+```
+
+**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
+```
 
-# Result: email field is hashed
-# {
-#   "user_id": 12345,
-#   "email": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-#   "purchase_amount": 1250.00
-# }
+#### `vkit policy deploy`
+
+Deploy a policy bundle to the control plane.
+
+```bash
+vkit policy deploy --bundle <BUNDLE_FILE> [OPTIONS]
+```
+
+**Options:**
+- `--bundle` — Path to bundle file (required)
+- `--org` — Organization identifier
+- `--activate` — Immediately activate bundle
+- `--dry-run` — Validate deployment without activating
+
+**Examples:**
+```bash
+# Deploy and activate
+vkit policy deploy \
+  --bundle dist/policy_bundle.json \
+  --org acme \
+  --activate
+
+# Dry run (test deployment)
+vkit policy deploy \
+  --bundle dist/policy_bundle.json \
+  --org acme \
+  --dry-run
+```
+
+#### `vkit policy list`
+
+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.
+
+```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
+```
+
+---
+
+## ⚙️ Configuration
+
+### Configuration File
+
+Create `~/.vkit/config.yaml` for persistent settings:
 
 ```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
+# VaultKit Control Plane
+api_url: "https://vaultkit.company.com"
+
+# Authentication
+auth:
+  method: "sso"  # or "password"
+  sso_provider: "okta"
+
+# Default Settings
+defaults:
+  datasource: "production_pg"
+  environment: "production"
+  requester_region: "US"
+  clearance_level: "high"
+
+# Output Preferences
+output:
+  format: "table"  # json, table, csv
+  color: true
+
+# Audit Logging
+audit:
+  local_log: true
+  log_customers_path: "~/.vkit/audit.log"
+
+# Request Settings
+request:
+  default_ttl: 3600  # 1 hour
+  auto_retry: true
+  retry_attempts: 3
+```
+
+### Environment Variables
+
+Override config file with environment variables:
+
+```bash
+# Required
+export VKIT_API_URL="https://vaultkit.company.com"
+
+# Optional
+export VKIT_CONFIg_customers_PATH="~/.vkit/config.yaml"
+export VKIT_AUTH_TOKEN="eyJhbGciOiJIUzI1NiIs..."
+export VKIT_DEFAULT_DATASOURCE="production_pg"
+export VKIT_OUTPUT_FORMAT="json"
+```
+
+### Precedence Order
+
+1. Command-line flags (highest priority)
+2. Environment variables
+3. Configuration file
+4. Built-in defaults (lowest priority)
 
 ---
-id: ccpa_disclosure_logging
-match:
-  dataset: california_residents
 
-context:
-  requester_region: ANY
+## 🔬 Advanced Usage
+
+### Scripting with vkit
+
+**Batch Request Processing:**
 
-action:
-  allow: true
-  ttl: "1h"
-  audit_metadata:
-    ccpa_disclosure: true
-    data_subject_rights: "User has right to know about this access"
+```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
+
+PENDING=$(vkit approval:list --state pending --format json)
 
-# Response:
-# ❌ Access Denied
-# Reason: Cross-region PII access forbidden due to GDPR Article 44
-# Policy: gdpr_cross_region_deny
-# Audit ID: audit_20240115_abc123
+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_customers_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_customers_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 g_customers_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: g_customers_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
+```
 
 ---
-id: after_hours_deny
-match:
-  dataset: audit_logs
-  environment: production
-
-context:
-  time:
-    outside_window
+
+## 🤝 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/yourorg/vaultkit](https://github.com/yourorg/vaultkit)
+- **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)
+
+---
+
+## 📄 License
+
+VaultKit CLI is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.
+
+---
+
+## 💬 Support
+
+- **Issues**: [github.com/yourorg/vaultkit-cli/issues](https://github.com/yourorg/vaultkit-cli/issues)
+- **Discussions**: [github.com/yourorg/vaultkit-cli/discussions](https://github.com/yourorg/vaultkit-cli/discussions)
+- **Email**: support@vaultkit.io
+- **Slack**: [vaultkit.slack.com](https://vaultkit.slack.com)
+
+---
+
+**Built with ❤️ by the VaultKit team**