StopMakingThatBigFace · StopMakingThatBigFace · Jan 24, 2026 · Jan 24, 2026 · Jan 24, 2026 · Jan 24, 2026
diff --git a/README.md b/README.md
@@ -2,15 +2,11 @@
 
 **A ClickHouse migrations CLI with templated SQL and environment-aware config.**
 
-<small>_"clisma" is a mashup of ClickHouse + Prisma. A dumb pun, but it stuck._</small>
+<small>_"clisma" is a mashup of ClickHouse + Prisma. A dumb pun, but it stuck._ 👉👈</small>
 
-This project borrows ideas from tools we like:
-
-- **[Atlas](https://atlasgo.io/)** for the idea of [templated migrations](https://atlasgo.io/concepts/migrations#template) and [config-driven environments](https://atlasgo.io/concepts/dev-database).
+<p><strong><a href="https://clisma.poorquality.tech/" style="font-size: 1.3em;">💅 More Docs →</a></strong></p>
 
-- **[Prisma](https://www.prisma.io/)** for the simple, friendly CLI experience.
-
-### So why it exists?
+## What is for?
 
 - **Templates in migrations** — Atlas has this, but it is paid; clisma keeps it simple and open.
 - **Multi-statement migrations** — write real SQL without splitting into tiny files.
@@ -136,3 +132,11 @@ Example with variables and env file:
 ```bash
 clisma run --env local --var ttl_days=30 --env-file .env
 ```
+
+## So What is this
+
+This project borrows ideas from tools we like:
+
+- **[Atlas](https://atlasgo.io/)** for the idea of [templated migrations](https://atlasgo.io/concepts/migrations#template) and [config-driven environments](https://atlasgo.io/concepts/dev-database).
+
+- **[Prisma](https://www.prisma.io/)** for the simple, friendly CLI experience.
diff --git a/docs/cli.md → docs/cli.mdx b/docs/cli.md → docs/cli.mdx
@@ -1,10 +1,16 @@
 ---
-title: CLI
+title: "Commands"
+description: "Run, inspect, and create migrations from the command line"
+icon: "terminal"
 ---
 
-Clisma ships a CLI for applying and inspecting migrations.
+<Info>
+  **Prerequisites**:
+
+  - A `clisma.hcl` config file in the current directory, or pass `--config`
+</Info>
 
-The CLI requires a config file. Use `--config` or place `clisma.hcl` in the current directory.
+Clisma ships a CLI for applying and inspecting migrations.
 
 ## Commands
 
@@ -46,18 +52,23 @@ clisma checksum ./migrations/20240101123045_create_users.sql
 
 ## Flags
 
-- **`--env <name>` — environment from config file.**
+- **`--env <name> — environment from config file.`**
 
   Example: `--env production`
-
-- **`--config <path>` — path to config file.**
+- **`--config <path> — path to config file.`**
 
   Example: `--config ./clisma.hcl`
-
-- **`--var <key=value>` — set variable value (repeatable).**
+- **`--var <key=value> — set variable value (repeatable).`**
 
   Example: `--var ttl_days=30 --var replication_factor=3`
+- **`--env-file <path> — load env vars from file.`**
 
-- **`--env-file <path>` — load env vars from file.**
-
   Example: `--env-file .env`
+
+## Advanced usage
+
+Run with a custom config path and multiple variables:
+
+```bash
+clisma run --config ./infra/clisma.hcl --env staging --var ttl_days=30 --var replication_factor=2
+```
diff --git a/docs/configuration/env-and-vars.md → docs/configuration/env-and-vars.mdx b/docs/configuration/env-and-vars.md → docs/configuration/env-and-vars.mdx
@@ -1,5 +1,7 @@
 ---
-title: env() and Variables
+title: "env() and variables"
+description: "Use environment variables and config variables in clisma.hcl"
+icon: "book-open-cover"
 ---
 
 ## env()
@@ -40,7 +42,7 @@ env "local" {
 
 ## Cluster name
 
-If you want migrations_table to be replicated and use cluster-aware templates, set
+If you want the migrations table to be replicated and use cluster-aware templates, set
 `cluster_name` in the environment:
 
 ```hcl

diff --git a/docs/configuration/examples.md → docs/configuration/examples.mdx b/docs/configuration/examples.md → docs/configuration/examples.mdx
@@ -1,5 +1,7 @@
 ---
-title: Examples
+title: "Examples"
+description: "Common clisma.hcl configurations for local and production"
+icon: "notes-medical"
 ---
 
 ## Local
@@ -52,4 +54,4 @@ variable "replication_factor" {
   type = string
   default = "3"
 }
-```
+```
diff --git a/docs/configuration/overview.md → docs/configuration/overview.mdx b/docs/configuration/overview.md → docs/configuration/overview.mdx
@@ -1,5 +1,7 @@
 ---
-title: Configuration Overview
+title: "clisma.hcl"
+description: "Define environments and migration settings in clisma.hcl"
+icon: "file-pen"
 ---
 
 Clisma uses an HCL config file to define environments and migration settings.
@@ -61,4 +63,4 @@ variable "ttl_days" {
   default = "30"
   description = "Default TTL"
 }
-```
+```
diff --git a/docs/docs.json b/docs/docs.json
@@ -0,0 +1,69 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "aspen",
+  "name": "clisma",
+  "colors": {
+    "primary": "#16A34A",
+    "light": "#07C983",
+    "dark": "#15803D"
+  },
+  "favicon": "/favicon.svg",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Guides",
+        "groups": [
+          {
+            "group": "Getting started",
+            "icon": "rocket-launch",
+            "pages": [
+              "index",
+              "installation"
+            ]
+          },
+          {
+            "group": "Configuration",
+            "icon": "database",
+            "pages": [
+              "configuration/overview",
+              "configuration/env-and-vars",
+              "configuration/examples"
+            ]
+          },
+          {
+            "group": "Migrations",
+            "pages": [
+              "migrations/how-it-works",
+              "migrations/templates",
+              "migrations/naming",
+              "migrations/faq"
+            ]
+          },
+          {
+            "group": "CLI",
+            "icon": "game-console-handheld",
+            "pages": [
+              "cli"
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  "logo": {
+    "light": "/logo/light.svg",
+    "dark": "/logo/dark.svg"
+  },
+  "contextual": {
+    "options": [
+      "copy",
+      "view",
+      "chatgpt",
+      "claude",
+      "perplexity",
+      "mcp",
+      "cursor",
+      "vscode"
+    ]
+  }
+}
diff --git a/docs/favicon.svg b/docs/favicon.svg
diff --git a/docs/getting-started.md b/docs/getting-started.md
diff --git a/docs/index.md b/docs/index.md
diff --git a/docs/index.mdx b/docs/index.mdx
@@ -0,0 +1,35 @@
+---
+title: "What is clisma"
+description: "Overview of the ClickHouse migration tool and how you use it"
+icon: "hand-wave"
+---
+
+Clisma is a ClickHouse migration tool with templating support and environment configuration. You use the CLI for day-to-day workflows, or the core package for programmatic control.
+
+## What it does
+
+- Applies SQL migrations in order and tracks them in ClickHouse.
+- Supports Handlebars templating with auto-detected cluster context.
+- Reads environment-specific configuration from `clisma.hcl`.
+
+## Inspiration
+
+This project borrows ideas from tools you may already know:
+
+- [Prisma](https://www.prisma.io/) for the simple, friendly CLI experience.
+- [Atlas](https://atlasgo.io/) for templated migrations and config-driven environments.
+
+Related Atlas concepts:
+
+- [Templated migrations](https://atlasgo.io/concepts/migrations#template)
+- [Environment configuration](https://atlasgo.io/concepts/dev-database)
+
+> Why the weird name?
+>
+> It is a little joke: ClickHouse + Prisma -\> clisma. There is no full schema management here (yet), but the vibe is similar.
+
+## Next steps
+
+- Follow the [Getting started](./getting-started) guide.
+- Define your environments in [Configuration](./configuration/overview).
+- Learn about [Templates](./migrations/templates) for advanced SQL.