dip-protocol · pavancharak · Apr 5, 2026
diff --git a/README.md b/README.md
@@ -1,307 +1,82 @@
-# Manthan — Decision Operating System
-
-> Every decision is traceable, auditable, and built for trust.
-
----
-
-## 🚀 What is Manthan?
-
-Manthan is a **deterministic decision infrastructure** that enforces contract-based rules directly in your workflows.
-
-It replaces manual approvals with:
-
-* Deterministic evaluation
-* Contract-driven rules
-* Enforced outcomes
-
-At its current version (**v0.2**), Manthan operates as a:
-
-> **GitHub Pull Request Gate**
-
----
-
-## ⚡ Why it matters
-
-Modern workflows rely on:
-
-* Manual reviews
-* Subjective approvals
-* Inconsistent enforcement
-
-Manthan changes that:
-
-> Decisions are no longer opinions — they are **enforced outcomes**.
-
----
-
-## 🧠 How it works
-
-```txt
-GitHub PR Event
-      │
-      ▼
-Webhook (/internal/event)
-      │
-      ▼
-Event Normalization
-      │
-      ▼
-Decision Engine (core/)
-      │
-      ▼
-Explanation Builder
-      │
-      ▼
-GitHub Enforcement
- (Check Run + Status + Comment)
-      │
-      ▼
-Merge Allowed / Blocked
-```
-
----
-
-## 🔍 Decision Engine (Deterministic Flow)
-
-```txt
-Input (eventPayload + contract)
-      │
-      ▼
-Contract Validation
-      │
-      ▼
-Determinism Check
-      │
-      ▼
-Boundary Check
-      │
-      ▼
-Intent Alignment
-      │
-      ▼
-Base Rules
-      │
-      ▼
-Final Decision (pass / fail)
-      │
-      ▼
-Trace + Explanation
-```
+# Manthan — Deterministic PR Gate
 
----
+Manthan is a deterministic decision system that evaluates GitHub pull requests against structured decision contracts.
 
-## 🔐 Enforcement Flow
+Same input → same decision. Every time.
 
-```txt
-Decision Result
-      │
-      ▼
-Map to GitHub State
- (pass → success, fail → failure)
-      │
-      ▼
-Create Check Run
-      │
-      ▼
-Set Commit Status
- (manthan/pr-gate)
-      │
-      ▼
-Upsert PR Comment
-      │
-      ▼
-Branch Protection
-      │
-      ▼
-Merge Allowed / Blocked
-```
 
----
+## What This Does
 
-## 🔍 What it enforces
+Manthan enforces decisions at the pull request level.
 
-| Condition              | Result    |
-| ---------------------- | --------- |
-| Missing PR description | ❌ Blocked |
-| No test files          | ❌ Blocked |
-| Contract satisfied     | ✅ Allowed |
+Instead of human reviews or probabilistic tools, every PR is evaluated against a contract and produces a reproducible verdict.
 
----
 
-## ⚡ 1-Minute Demo
+## Core Principles
 
-### Step 1 — Create PR (invalid)
+* Deterministic — no drift, no heuristics
+* Contract-driven — decisions defined as structured schemas
+* Enforced — results applied directly to PRs
+* Auditable — every decision includes a trace
 
-```txt
-PR created → No description
-```
 
-```txt
-manthan/pr-gate → ❌ failure
-```
+## Example Output
 
----
+Decision: FAIL
 
-### Step 2 — Fix PR
+Contract: api-schema-v1
 
-```md
-Add feature X
+Violations:
 
-- Includes implementation
-- Adds tests
-```
+* Missing field `userId`
+* Endpoint `/create` not defined
 
----
+Trace:
 
-### Step 3 — Automatic re-evaluation
+* input.schema.required
+* endpoint.registry.match
 
-```txt
-PR updated → webhook triggered
-manthan/pr-gate → ✅ success
-```
+evaluation_id: 8f3a...
+contract_version: v1
 
----
 
-### Step 4 — Merge enabled
+## Architecture
 
-```txt
-All checks passed → Merge allowed
-```
+* `/contracts` — decision definitions
+* `/core` — evaluation engine
+* `/enforcement` — GitHub PR interaction
+* `/dsl` — contract logic structure
+* `/api` — webhook ingestion layer
 
----
 
-### 🧠 Insight
+## Determinism Guarantee
 
-```txt
-Invalid input → fail → blocked
-Valid input   → pass → allowed
-```
+Given:
 
-> Manthan does not suggest — it **enforces**.
+* Same PR
+* Same contract
+* Same repository state
 
----
+Manthan guarantees:
 
-## 🚀 Try Manthan (GitHub App)
+* Same verdict
+* Same violations
+* Same trace
+* Same evaluation_id
 
-### 1️⃣ Install the App
 
-* Go to GitHub App settings
-* Click **Install App**
-* Select repository
+## Status
 
----
+Manthan v0.2 — Deterministic PR Gate (locked)
 
-### 2️⃣ Enable Branch Protection
-
-* Settings → Branches
-* Require status checks
-
-Add:
-
-```txt
-manthan/pr-gate
-```
-
----
-
-### 3️⃣ Create a PR
-
----
-
-### 4️⃣ Observe
-
-```txt
-PR → Decision → Status → Merge control
-```
-
----
-
-## 🧪 Local Testing (CLI)
-
-```bash
-npm run cli payload.json
-```
-
----
-
-## 📘 Documentation
-
-* 📄 [System Specification](./docs/manthan-v0.2-pr-gate.md)
-* 📜 [Release Notes (v0.2)](./docs/releases/v0.2.md)
-* 📚 [Docs Index](./docs/README.md)
-
----
-
-## 🔒 Versioning Model
-
-* v0.2 — PR Gate (**current**)
-* v0.3 — Multi-contract
-* v1.0 — Platform
-
-### Rules
-
-* No patch versions
+* GitHub App integration
+* Idempotent webhook processing
+* PR comment enforcement
 * No runtime mutation
-* Immutable releases
-
----
-
-## 🏗 System Design
-
-```txt
-core/          → deterministic engine
-api/           → webhook entry
-enforcement/   → GitHub integration
-```
-
----
-
-## 🚫 What Manthan is NOT
-
-* Not CI
-* Not linter
-* Not advisory tool
-
-Manthan is:
-
-> **Decision Infrastructure**
-
----
-
-## 🔒 Current Status
-
-* Version: v0.2
-* State: Locked
-* Behavior: Immutable
-
----
-
-## 🚀 Next
-
-### v0.3 — Multi-Contract Evaluation
-
-* Multiple contracts per PR
-* Aggregated decision
-* Single enforcement signal
-
----
-
-## 🤝 Philosophy
-
-> Aligned decision = single source of truth
-
----
 
-## ⭐ Summary
 
-```txt
-Manual approval → subjective decisions
-```
+## Positioning
 
-↓
+Manthan is not a recommendation system.
 
-```txt
-Deterministic evaluation → enforced outcomes
-```
-end
----
+It is enforcement infrastructure for decisions.