diff --git a/README.md b/README.md
index 57e10666..b86b4753 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,12 @@
 
 # Failproof AI
 
+[![Docs](https://img.shields.io/badge/docs-befailproof.ai-002CA7?style=flat-square)](https://befailproof.ai)
+[![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai)
+[![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/exospherehost/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/exospherehost/failproofai/actions)
+[![Discord](https://img.shields.io/discord/1234567890?style=flat-square&label=Discord&color=5865F2)](https://discord.com/invite/zT92CAgvkj)
+
 Open-source hooks, policies, and project visualization for **Claude Code** & the **Agents SDK**.
 
 - **Hooks & Policies** — 35+ built-in security policies that run as Claude Code hooks. Block dangerous commands, sanitize secrets, restrict file access, and more.
diff --git a/docs/architecture.md b/docs/architecture.md
index 2dbd938e..b4ea42bd 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,4 +1,8 @@
-# Architecture
+---
+title: Architecture
+description: "How the hook handler, config loading, and policy evaluation work internally"
+icon: sitemap
+---
 
 This document explains how failproofai works internally: how the hook system processes events, how configuration is loaded and merged, how policies are evaluated, and how the dashboard fits in.
 
diff --git a/docs/built-in-policies.md b/docs/built-in-policies.md
index dfc92a32..a1b6cec3 100644
--- a/docs/built-in-policies.md
+++ b/docs/built-in-policies.md
@@ -1,4 +1,8 @@
-# Built-in Policies
+---
+title: Built-in Policies
+description: "All 35+ security policies with descriptions and parameters"
+icon: shield
+---
 
 failproofai ships with 35+ built-in security policies. Each policy fires on a specific hook event type and tool name. Eight policies accept parameters that let you tune their behavior without writing code.
 
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 2788d12f..eda8d218 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -1,4 +1,8 @@
-# CLI Reference
+---
+title: CLI Reference
+description: "All commands, flags, and environment variables for the failproofai CLI"
+icon: terminal
+---
 
 All commands are invoked via the `failproofai` binary.
 
diff --git a/docs/configuration.md b/docs/configuration.md
index 65643619..88731b78 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,4 +1,8 @@
-# Configuration
+---
+title: Configuration
+description: "Config file format, three-scope system, and merge rules"
+icon: gear
+---
 
 failproofai uses JSON configuration files to control which policies are active, how they behave, and where custom hooks are loaded from.
 
diff --git a/docs/custom-hooks.md b/docs/custom-hooks.md
index 5d7ea4eb..df063204 100644
--- a/docs/custom-hooks.md
+++ b/docs/custom-hooks.md
@@ -1,4 +1,8 @@
-# Custom Hooks
+---
+title: Custom Hooks
+description: "Write your own policies in JavaScript with allow, deny, and instruct decisions"
+icon: code
+---
 
 Custom hooks let you write your own policies in JavaScript. They integrate with the same hook event system as built-in policies and support the same `allow`, `deny`, and `instruct` decisions.
 
diff --git a/docs/dashboard.md b/docs/dashboard.md
index 95dcabd7..35f8628a 100644
--- a/docs/dashboard.md
+++ b/docs/dashboard.md
@@ -1,4 +1,8 @@
-# Dashboard
+---
+title: Dashboard
+description: "Session viewer, policy management, and activity log"
+icon: chart-line
+---
 
 The failproofai dashboard is a local web application for browsing Claude Code sessions and managing security policies.
 
diff --git a/docs/docs.json b/docs/docs.json
new file mode 100644
index 00000000..f68c75e7
--- /dev/null
+++ b/docs/docs.json
@@ -0,0 +1,83 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "luma",
+  "name": "FailproofAI",
+  "colors": {
+    "primary": "#002CA7",
+    "light": "#e4587d",
+    "dark": "#002CA7"
+  },
+  "favicon": "/favicon.ico",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Docs",
+        "groups": [
+          {
+            "group": "Getting Started",
+            "pages": [
+              "introduction",
+              "getting-started"
+            ]
+          },
+          {
+            "group": "Core Concepts",
+            "pages": [
+              "configuration",
+              "built-in-policies",
+              "custom-hooks"
+            ]
+          },
+          {
+            "group": "Tools",
+            "pages": [
+              "cli-reference",
+              "dashboard"
+            ]
+          },
+          {
+            "group": "Advanced",
+            "pages": [
+              "architecture",
+              "testing",
+              "package-aliases"
+            ]
+          }
+        ]
+      }
+    ],
+    "global": {
+      "anchors": [
+        {
+          "anchor": "GitHub",
+          "href": "https://github.com/exospherehost/failproofai",
+          "icon": "github"
+        },
+        {
+          "anchor": "npm",
+          "href": "https://www.npmjs.com/package/failproofai",
+          "icon": "npm"
+        },
+        {
+          "anchor": "Discord",
+          "href": "https://discord.com/invite/zT92CAgvkj",
+          "icon": "discord"
+        }
+      ]
+    }
+  },
+  "navbar": {
+    "links": [],
+    "primary": {
+      "type": "button",
+      "label": "Get started",
+      "href": "/getting-started"
+    }
+  },
+  "footer": {
+    "socials": {
+      "github": "https://github.com/exospherehost/failproofai",
+      "x": "https://x.com/exospherehost"
+    }
+  }
+}
diff --git a/docs/favicon.ico b/docs/favicon.ico
new file mode 100644
index 00000000..efd8c27c
Binary files /dev/null and b/docs/favicon.ico differ
diff --git a/docs/getting-started.md b/docs/getting-started.md
index df95ac02..77329f93 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -1,4 +1,8 @@
-# Getting Started
+---
+title: Getting Started
+description: "Install failproofai, enable policies, and take it for a spin"
+icon: rocket
+---
 
 ## Requirements
 
diff --git a/docs/index.md b/docs/index.md
deleted file mode 100644
index 6c2bb7f0..00000000
--- a/docs/index.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# Failproof AI — Documentation
-
-Open-source hooks, policies, and session visualization for **Claude Code** and the **Agents SDK**. Runs entirely locally — no data leaves your machine.
-
----
-
-## Documentation
-
-| Guide | Description |
-|-------|-------------|
-| [Getting Started](./getting-started.md) | Install failproofai, enable policies, and take it for a spin |
-| [CLI Reference](./cli-reference.md) | All commands, flags, and environment variables |
-| [Configuration](./configuration.md) | Config file format, three-scope system, and merge rules |
-| [Built-in Policies](./built-in-policies.md) | All 35+ policies with descriptions and parameters |
-| [Custom Hooks](./custom-hooks.md) | Write your own policies in JavaScript |
-| [Dashboard](./dashboard.md) | Session viewer, policy management, and activity log |
-| [Architecture](./architecture.md) | How the hook handler, config loading, and policy evaluation work |
-| [Testing](./testing.md) | Unit tests, E2E tests, and test helpers |
-| [Package Aliases](./package-aliases.md) | Registered typosquat-prevention aliases and how they work |
-
----
-
-## Quick reference
-
-**Install:**
-```bash
-npm install -g failproofai
-```
-
-**Enable policies globally:**
-```bash
-failproofai --install-policies
-```
-
-**Launch dashboard:**
-```bash
-failproofai
-```
-
-**List active policies:**
-```bash
-failproofai --list-policies
-```
-
-**Add a custom policy file:**
-```bash
-failproofai --install-policies --custom ./my-policies.js
-```
diff --git a/docs/introduction.md b/docs/introduction.md
new file mode 100644
index 00000000..6eccfe4c
--- /dev/null
+++ b/docs/introduction.md
@@ -0,0 +1,45 @@
+---
+title: Introduction
+description: "Open-source hooks, policies, and session visualization for Claude Code and the Agents SDK"
+---
+
+# Failproof AI
+
+Open-source hooks, policies, and session visualization for **Claude Code** and the **Agents SDK**. Runs entirely locally — no data leaves your machine.
+
+## What is Failproof AI?
+
+Failproof AI is a security and observability toolkit that intercepts Claude Code tool calls in real time. It evaluates configurable policies — blocking dangerous commands, redacting secrets, and adding safety instructions — before Claude can act.
+
+It also includes a local web dashboard for browsing Claude Code sessions, inspecting tool calls, and managing policies visually.
+
+## Key features
+
+| Feature | Description |
+|---------|-------------|
+| [35+ Built-in Policies](./built-in-policies.md) | Block sudo, rm -rf, force-push, secret leaks, and more — out of the box. |
+| [Custom Hooks](./custom-hooks.md) | Write your own policies in JavaScript with a simple allow/deny/instruct API. |
+| [Session Dashboard](./dashboard.md) | Browse projects, inspect sessions, and review every tool call and policy decision. |
+| [Three-Scope Config](./configuration.md) | Global, project, and local configuration with automatic merging. |
+
+## Quick start
+
+Install globally via npm:
+
+```bash
+npm install -g failproofai
+```
+
+Enable policies:
+
+```bash
+failproofai --install-policies
+```
+
+Launch the dashboard:
+
+```bash
+failproofai
+```
+
+See the [Getting Started](./getting-started.md) guide for a full walkthrough.
diff --git a/docs/logo/exosphere-dark.png b/docs/logo/exosphere-dark.png
new file mode 100644
index 00000000..2f567459
Binary files /dev/null and b/docs/logo/exosphere-dark.png differ
diff --git a/docs/logo/exosphere-light.png b/docs/logo/exosphere-light.png
new file mode 100644
index 00000000..c154ac9f
Binary files /dev/null and b/docs/logo/exosphere-light.png differ
diff --git a/docs/package-aliases.md b/docs/package-aliases.md
index 61cff356..f3bd3043 100644
--- a/docs/package-aliases.md
+++ b/docs/package-aliases.md
@@ -1,4 +1,8 @@
-# Package Aliases & Typosquatting Protection
+---
+title: Package Aliases
+description: "Registered typosquat-prevention aliases and how they work"
+icon: copy
+---
 
 ## Official package
 
diff --git a/docs/testing.md b/docs/testing.md
index cfb1b985..b2d57d91 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -1,4 +1,8 @@
-# Testing
+---
+title: Testing
+description: "Unit tests, E2E tests, and test helpers"
+icon: flask-vial
+---
 
 failproofai has two test suites: **unit tests** (fast, mocked) and **end-to-end tests** (real subprocess invocations).