flowchart TD
    subgraph Clients ["AI Clients (Local)"]
        Claude[Claude Desktop]
        Cursor[Cursor]
        VSCode[VS Code]
    end

    subgraph Gateway ["VaultMind Gateway (Local Proxy)"]
        VMGateway["vaultmind-gateway"]
    end

    subgraph Security ["Security Engine"]
        PolicyEngine["Policy Engine<br>(allow/deny/network rules)"]
        PolicyYaml["policy.yaml"]
    end

    subgraph Logs ["Immutable Audit Trail"]
        SQLite[("SQLite Audit Trail<br>(vault.db)")]
        JSONL["JSONL Event Log"]
    end

    subgraph Sandbox ["Isolation"]
        VMSandbox["Process Sandbox<br>(FS ACLs & Net Block)"]
    end

    %% Flow of Tool Calls
    Claude & Cursor & VSCode -->|MCP stdio/SSE| VMGateway
    VMGateway -->|1. Request Verdict| PolicyEngine
    PolicyYaml -.->|Defines Rules| PolicyEngine
    PolicyEngine -->|2. allow/deny/error| VMGateway
    VMGateway -->|3. Log Event| SQLite & JSONL
    VMGateway -->|4. Execute if allowed| VMSandbox

    %% Styling
    classDef client fill:#111827,stroke:#3b82f6,stroke-width:2px,color:#f3f4f6;
    classDef gw fill:#1e1b4b,stroke:#6366f1,stroke-width:2px,color:#f3f4f6;
    classDef engine fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#f3f4f6;
    classDef audit fill:#7c2d12,stroke:#f97316,stroke-width:2px,color:#f3f4f6;
    classDef sand fill:#581c87,stroke:#a855f7,stroke-width:2px,color:#f3f4f6;

    class Claude,Cursor,VSCode client;
    class VMGateway gw;
    class PolicyEngine,PolicyYaml engine;
    class SQLite,JSONL audit;
    class VMSandbox sand;

# Install from source
git clone https://github.com/your-org/vaultmind.git
cd vaultmind
npm install

# Create a policy file
npx tsx packages/cli/src/index.ts init

# Start recording a session
npx tsx packages/cli/src/index.ts record -- echo "hello, air-gapped world"

# Analyze audit logs
npx tsx packages/cli/src/index.ts analyze

# Generate policy from audit log
npx tsx packages/cli/src/index.ts policy generate

# Start the gateway server
npx tsx packages/cli/src/index.ts gateway start --port 3080

# policy.yaml
version: "1.0"
rules:
  - id: "allow-docs"
    allow:
      - "read(docs/*)"
      - "read(*.md)"
  - id: "block-src-writes"
    deny:
      - "write(src/*)"
      - "write(lib/*)"
  - id: "network-off"
    network: "off"
default_action: "deny"

CREATE TABLE sessions (
    id TEXT PRIMARY KEY,
    start_time INTEGER NOT NULL,
    policy_hash TEXT,
    status TEXT CHECK(status IN ('recording','analyzing','done'))
);

CREATE TABLE events (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id TEXT NOT NULL,
    ts INTEGER NOT NULL,
    agent TEXT NOT NULL,
    tool TEXT NOT NULL,
    params TEXT NOT NULL,       -- JSON
    verdict TEXT CHECK(verdict IN ('allow','deny','error')),
    reason TEXT
);

import { createPolicyHelper } from '@vaultmind/sdk';
import { VaultMindClient } from '@vaultmind/sdk';

// Fluent policy builder
const policy = createPolicyHelper()
  .allow('read(docs/*)')
  .deny('write(src/*)')
  .network('off')
  .build();

// Programmatic client
const client = new VaultMindClient();
await client.startSession();
const result = await client.evaluateCall({
  tool: 'read_file',
  args: {},
  action: 'read',
  path: 'docs/guide.md',
});
console.log(result.verdict); // 'allow' | 'deny'
console.log(client.getStats()); // { total, allowed, denied, errors }
await client.endSession();

vaultmind/
├── packages/
│   ├── vm-core/           # Shared types, policy engine, DB, logger
│   ├── vm-sandbox/        # Execution sandbox
│   ├── mcp-gateway/       # MCP proxy + REST/WS server
│   ├── cli/               # CLI entrypoint
│   └── sdk/               # TypeScript SDK
├── dashboard/
│   └── src/index.html     # Real-time monitoring dashboard
├── tests/                 # Integration & policy tests
├── docs/                  # MkDocs material
├── examples/              # Docker, Nix, systemd units
└── policy.yaml            # Default security policy