diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
new file mode 100644
index 0000000..1c3b3c9
--- /dev/null
+++ b/docs/getting-started/installation.md
@@ -0,0 +1,36 @@
+# CapiscIO Python CLI
+
+The **CapiscIO Python CLI** is a lightweight wrapper that automatically downloads and executes the high-performance [CapiscIO Core](https://github.com/capiscio/capiscio-core) binary.
+
+It provides a seamless experience for Python developers, allowing you to install the CLI via `pip` without worrying about platform-specific binaries.
+
+## Installation
+
+```bash
+pip install capiscio
+```
+
+## Usage
+
+Once installed, the `capiscio` command is available in your terminal. It passes all arguments directly to the underlying Core binary.
+
+```bash
+# Validate an agent card
+capiscio validate ./agent-card.json
+
+# Check version
+capiscio version
+```
+
+For full command reference, see the [CapiscIO Core Documentation](../../capiscio-core/index.md).
+
+## How it Works
+
+1.  **Detection**: When you run `capiscio`, the wrapper detects your Operating System (Linux, macOS, Windows) and Architecture (AMD64, ARM64).
+2.  **Download**: It checks if the correct `capiscio-core` binary is present in your user cache directory. If not, it downloads it securely from GitHub Releases.
+3.  **Execution**: It executes the binary with your provided arguments, piping input and output directly to your terminal.
+
+## Requirements
+
+*   Python 3.10+
+*   Internet connection (for initial binary download)
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..309b46c
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,34 @@
+---
+title: CapiscIO Python CLI - Documentation
+description: Official documentation for the CapiscIO Python CLI wrapper.
+---
+
+# CapiscIO Python CLI
+
+The **CapiscIO Python CLI** is a lightweight wrapper around the CapiscIO Core binary, designed for seamless integration into Python environments.
+
+<div class="grid cards" markdown>
+
+-   **🚀 Getting Started**
+
+    ---
+
+    Install the CLI via pip.
+
+    [:octicons-arrow-right-24: Installation](./getting-started/installation.md)
+
+-   **⚙️ Reference**
+
+    ---
+
+    Command reference and usage.
+
+    [:octicons-arrow-right-24: Commands](./reference/commands.md)
+
+</div>
+
+## Installation
+
+```bash
+pip install capiscio
+```
diff --git a/docs/reference/commands.md b/docs/reference/commands.md
new file mode 100644
index 0000000..9b4f097
--- /dev/null
+++ b/docs/reference/commands.md
@@ -0,0 +1,27 @@
+# Wrapper-Specific Commands
+
+While most commands are handled by the Core binary, the Python wrapper includes a few utility commands for managing the wrapper itself.
+
+## `capiscio --wrapper-version`
+
+Displays the version of the Python wrapper package itself, distinct from the Core binary version.
+
+```bash
+$ capiscio --wrapper-version
+capiscio-python wrapper v2.1.3
+```
+
+## `capiscio --wrapper-clean`
+
+Removes the cached `capiscio-core` binary. This is useful if the binary becomes corrupted or if you want to force a re-download.
+
+```bash
+$ capiscio --wrapper-clean
+Cleaned cache directory: /Users/username/Library/Caches/capiscio/bin
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CAPISCIO_CORE_PATH` | (Optional) Override the path to the `capiscio-core` binary. If set, the wrapper will use this binary instead of downloading one. |
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..01306b6
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,90 @@
+# CapiscIO Python CLI Wrapper
+
+site_name: CapiscIO Python CLI
+site_url: https://docs.capisc.io/capiscio-python
+site_description: The official Python wrapper for the CapiscIO Core CLI.
+site_author: CapiscIO Team
+copyright: Copyright &copy; 2025 CapiscIO
+
+repo_name: capiscio/capiscio-python
+repo_url: https://github.com/capiscio/capiscio-python
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+  logo: https://docs.capisc.io/assets/logo.png
+  favicon: https://docs.capisc.io/assets/favicon.ico
+  palette:
+    - scheme: slate
+      primary: blue grey
+      accent: cyan
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+    - scheme: default
+      primary: blue grey
+      accent: cyan
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+  
+  font:
+    text: Roboto
+    code: Roboto Mono
+  
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - navigation.footer
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - content.tabs.link
+
+plugins:
+  - search:
+      lang: en
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+  - pymdownx.details
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+
+extra:
+  homepage: https://docs.capisc.io
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/capiscio
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/capiscio
+
+nav:
+  - Home: index.md
+  - Getting Started:
+      - Installation: getting-started/installation.md
+  - Reference:
+      - Commands: reference/commands.md