## Overview

arifOS is the world's first production-grade Constitutional AI Governance System. It wraps every AI operation in a mathematically enforced constitution, guaranteeing that what arrives at the real world is ordered, verified, and reversible.

Unlike simple prompt wrappers, arifOS is a governed intelligence organism with:

- 13 Constitutional Floors (F1-F13) — Non-negotiable physical laws
- Trinity Architecture (ΔΩΨ) — Separation of Mind, Heart, and Soul
- 25 Canonical Tools — Distributed across 5 sovereign layers
- VAULT999 Ledger — Immutable cryptographic audit trail

## 🚀 Quick Start

### Installation

    # Python (recommended)
    pip install arifosmcp==2026.3.14

    # Node.js wrapper
    npm install -g @arifos/mcp

### Basic Usage

    # Run MCP server
    python -m arifosmcp.runtime stdio

    # Or HTTP mode
    python -m arifosmcp.runtime http --port 8080

Note: arifOS requires Python 3.12+ for full async/await support and type safety.

## 🛠️ Tool Reference

### KERNEL Layer

Tool | Stage | Description
--- | --- | ---
`init_anchor` | 000_INIT | Initialize session jurisdiction
`arifOS_kernel` | 555_ROUTE | Main entry point—routes ΔΩΨ
`forge` | 000_999 | Full pipeline—INIT→SEAL
`revoke_anchor_state` | 000_INIT | Kill switch session

### AGI Δ MIND Layer

Tool | Stage | Description
--- | --- | ---
`agi_reason` | 111_OBSERVE | Governed reasoning (F2/F4/F7)
`agi_reflect` | 333_INTEGRATE | Metacognitive check
`reality_compass` | 222_GROUND | Ground claims before reasoning
`search_reality` | 222_GROUND | Live web search
`ingest_evidence` | 222_GROUND | URL→normalized evidence

### ASI Ω HEART Layer

Tool | Stage | Description
--- | --- | ---
`asi_critique` | 555_ALIGN | Adversarial safety check
`asi_simulate` | 555_ALIGN | Consequence simulation
`agentzero_engineer` | 666_EXECUTE | Code execution (F11 gate)

### APEX Ψ SOUL Layer

Tool | Stage | Description
--- | --- | ---
`apex_judge` | 777_JUDGE | Tri-witness verdict
`audit_rules` | 888_FLOOR | F1-F13 inspection
`check_vital` | 888_VITALS | System telemetry
`open_apex_dashboard` | 888_OBSERVE | Live governance UI

## ⚖️ Constitutional Floors

The 13 Floors are stationary constraints—they cannot be bypassed by any agent or system prompt.

### Hard Floors (Non-Negotiable)

- F1 Amanah (≥0.5) — Reversibility mandate
- F2 Truth (≥0.99) — Anti-hallucination
- F4 Clarity (≤0) — Entropy reduction
- F7 Humility (0.03-0.20) — Gödel uncertainty band
- F9 C_dark (<0.30) — Anti-Hantu limit
- F10 Ontology (LOCK) — No consciousness claims
- F11 Command Auth (LOCK) — Identity verification

### Soft Floors (Advisory)

- F5 Peace² (≥1.0) — Stability
- F6 Empathy (≥0.70) — Weakest stakeholder
- F8 Genius (≥0.80) — Coherence

### Special Floors

- F3 Tri-Witness (≥0.95) — Human·AI·Earth consensus
- F12 Injection (<0.85) — Adversarial defense
- F13 Sovereign (HUMAN) — Final human veto

## 🔌 MCP Client Setup

### Claude Desktop

Edit `claude_desktop_config.json`:

    {
      "mcpServers": {
        "arifos": {
          "command": "npx",
          "args": ["-y", "@arifos/mcp"]
        }
      }
    }

### Kimi / Other Clients

    {
      "mcpServers": {
        "arifos": {
          "command": "python",
          "args": ["-m", "arifosmcp.runtime", "stdio"]
        }
      }
    }

### Environment Variables

Variable | Description | Default
--- | --- | ---
`ARIFOS_ENV` | Runtime environment | production
`ARIFOS_PUBLIC_TOOL_PROFILE` | Tool visibility | full
`PORT` | HTTP server port | 8080

## 📡 API Reference

### Health Check

    GET /health

    Response:
    {
      "status": "healthy",
      "version": "2026.03.14-VALIDATED",
      "tools_loaded": 25,
      "timestamp": "2026-03-14T10:00:00Z"
    }

### List Tools

    GET /tools

    Returns JSON array of all 25 tools with JSONSchema parameters.

### MCP Protocol

    POST /mcp
    Content-Type: application/json

    {
      "jsonrpc": "2.0",
      "method": "tools/call",
      "params": {
        "name": "arifOS_kernel",
        "arguments": {
          "query": "Your query here"
        }
      }
    }

## 🎯 Best Practices

1. Always start with `init_anchor` — Establishes session jurisdiction
2. Use `forge` for one-shot tasks — Runs full 000-999 pipeline
3. Ground claims with `reality_compass` — Before reasoning
4. Respect 888_HOLD — Human escalation is a feature, not a bug
5. Check vitals regularly — Monitor ΔS, G★, Peace²

Warning: Never bypass the constitutional floors. VOID verdicts indicate constitutional collapse—debug the issue rather than forcing execution.