docs: create dedicated markdown documentation and explicit navigation tree

website/docs/architecture.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 3
+---
+
+# Architecture
+
+Claritty is designed as a decentralized, multi-agent system. It leverages a modern "Hub and Spoke" architecture to scale across dozens of clusters while keeping AI reasoning close to the metal.
+
+## Hub and Spoke Model
+
+At the core of Claritty is the separation between the **SRE Agent** (the spoke) and the **Centralized Hub**.
+
+```text
+Cluster A (prod) ──► claritty-agent ─┐
+Cluster B (dev)  ──► claritty-agent ─┼──► Centralized Claritty Hub (UI + DB)
+Cluster C (eu)   ──► claritty-agent ─┘
+```
+
+- **Agents:** Lightweight daemons running inside your Kubernetes clusters. They are stateless, completely isolated, and execute the heavy AI reasoning locally using your configured LLM (Ollama, Groq, Mistral, OpenAI, Anthropic). 
+- **Hub:** A centralized dashboard that aggregates the incident reports generated by the agents. The Hub does *not* have access to your raw cluster metrics or logs, guaranteeing a Zero-Trust security boundary.
+
+---
+
+## The 6-Stage AI Pipeline
+
+When an agent detects a failure (e.g., a `CrashLoopBackOff`, a network partition, or API throttling), it triggers Claritty's sophisticated 6-stage AI pipeline.
+
+Each stage represents a specialized, autonomous agent:
+
+1. 🩺 **Triage Agent**  
+   Analyzes high-level cluster states, identifies failing nodes or pods, and scopes the incident.
+2. 📊 **Metrics Agent**  
+   Gathers granular CPU, memory, and custom metrics for the affected resources to detect spikes or resource starvation.
+3. 📜 **Log Analysis Agent**  
+   Parses raw container logs, extracting stack traces, fatal errors, and contextual warnings.
+4. 🏗 **Infrastructure Agent**  
+   Evaluates the underlying Kubernetes architecture, checking for misconfigured Deployments, PVC capacity issues, or Service routing failures.
+5. 📖 **Runbook Agent**  
+   Consults built-in, battle-tested YAML runbooks to map the discovered symptoms to known failure modes.
+6. ⚡ **Commander Agent**  
+   Synthesizes the findings from all previous agents to generate a human-readable RCA and proposes exact `kubectl` remediation commands.
+
+:::info
+
+**Safety Guarantee:** The Commander Agent validates all proposed commands against a strict, predefined allowlist. Destructive actions are flagged and heavily restricted.
+
+:::

website/docs/cli-usage.md

@@ -0,0 +1,46 @@
+---
+sidebar_position: 4
+---
+
+# CLI Usage
+
+The `clarctl` CLI is the developer's gateway to Claritty. Run directly from your terminal, it leverages your local `kubeconfig` context to instantly diagnose issues in your clusters.
+
+## Basic Commands
+
+### Verify Installation
+Ensure the CLI is correctly installed and dynamically versioned:
+```bash
+clarctl version
+```
+
+### Scan the Current Context
+Run a comprehensive, real-time diagnostic scan of your entire active Kubernetes context:
+```bash
+clarctl scan
+```
+This command triggers the 6-stage AI pipeline locally, generating a beautifully formatted terminal output (using `lipgloss` and `bubbletea`) instead of raw JSON.
+
+---
+
+## Interactive Remediation
+
+When `clarctl scan` detects an incident, it doesn't just stop at giving you an RCA. The **Commander Agent** will propose a step-by-step remediation plan right in your terminal.
+
+For every command proposed by the AI, the CLI will enter interactive mode:
+
+```bash
+> AI proposes: kubectl rollout restart deployment my-app -n default
+> Execute? [y/dry/n]: 
+```
+
+### Prompt Options
+- `y` (Yes): Immediately executes the command against the cluster.
+- `dry` (Dry Run): Simulates the command using the Kubernetes API `--dry-run=client` flag to ensure it's structurally valid without making actual mutations.
+- `n` (No): Rejects the command and halts the remediation sequence.
+
+:::warning
+
+While Claritty runs commands through a strict allowlist to prevent destructive actions, you should always review proposed commands before typing `y`. Use `dry` if you are unsure of a command's side-effects.
+
+:::

website/docs/installation.md

@@ -0,0 +1,75 @@
+---
+sidebar_position: 2
+---
+
+# Installation
+
+Claritty is designed to be deployed effortlessly. Depending on your operational requirements, you can install the **Clarctl CLI** for local, on-demand diagnostics, or deploy the **SRE Agent & Hub** for continuous, in-cluster observability.
+
+---
+
+## Option 1: Install Clarctl CLI (Local Tool)
+
+The `clarctl` CLI is a standalone binary that connects to your local `kubeconfig` and interacts directly with your clusters from your terminal.
+
+### 1. Download the Binary
+You can install the latest release directly via our installation script (supports Linux and macOS):
+
+```bash
+curl -sL https://raw.githubusercontent.com/Vaishnav88sk/claritty/master/clarctl-go/install.sh | bash
+```
+
+### 2. Verify Installation
+Ensure the binary is in your path and correctly installed:
+
+```bash
+clarctl version
+```
+
+### 3. Run a Scan
+Instantly diagnose your current Kubernetes context:
+
+```bash
+clarctl scan
+```
+
+---
+
+## Option 2: Deploy the SRE Agent & Hub (In-Cluster)
+
+For continuous, 24/7 monitoring, deploy the Agent into your clusters and spin up the Centralized Hub.
+
+### 1. Start the Hub Server
+The Hub serves as the central control plane, receiving telemetry from your agents and hosting the web dashboard. You can spin this up quickly using Docker Compose.
+
+```bash
+# Export your database credentials
+export DATABASE_URL="postgresql://user:pass@host:5432/claritty?sslmode=require"
+
+# Download the compose file
+curl -sL https://raw.githubusercontent.com/Vaishnav88sk/claritty/master/sre-agent/docker-compose.yml -o docker-compose.yml
+
+# Start the Hub in detached mode
+docker-compose up -d
+```
+> View the beautiful Claritty dashboard at `http://localhost:8822`!
+
+### 2. Deploy the SRE Agent
+Next, deploy the lightweight SRE agent directly into the Kubernetes clusters you wish to monitor.
+
+```bash
+# 1. Apply the required RBAC permissions
+kubectl apply -f https://raw.githubusercontent.com/Vaishnav88sk/claritty/master/sre-agent/deploy/agent-rbac.yaml
+
+# 2. Apply the configuration (Make sure to edit this file with your Hub IP!)
+kubectl apply -f https://raw.githubusercontent.com/Vaishnav88sk/claritty/master/sre-agent/deploy/agent-configmap.yaml
+
+# 3. Deploy the agent daemon
+kubectl apply -f https://raw.githubusercontent.com/Vaishnav88sk/claritty/master/sre-agent/deploy/agent-deployment.yaml
+```
+
+:::warning
+
+Before applying `agent-configmap.yaml`, ensure you replace the default placeholders with your specific Hub Server IP and a unique `Cluster Name` to identify it on the dashboard.
+
+:::

website/docs/intro.md

@@ -4,4 +4,31 @@ sidebar_position: 1
 
 # Introduction
 
-Welcome to Claritty.
+**Claritty** is a production-grade, open-source AI Site Reliability Engineering (SRE) platform specifically designed for Kubernetes.
+
+It combines real-time cluster telemetry with a powerful **6-stage AI agent pipeline** to automatically detect, diagnose, and remediate incidents, shrinking MTTR (Mean Time to Resolution) from hours down to minutes.
+
+:::tip
+
+Claritty is designed with **Zero-Trust** in mind. By leveraging local LLMs (like Ollama), your sensitive cluster telemetry and logs never leave your infrastructure.
+
+:::
+
+## The Two Modes of Claritty
+
+Claritty provides two powerful ways to interact with your Kubernetes infrastructure, depending on your needs:
+
+### 1. Clarctl CLI (Local Tool)
+A powerful command-line interface run from your local machine. It connects to your current Kubernetes context to instantly analyze namespaces or specific pods, generate an RCA (Root Cause Analysis), and offer interactive, step-by-step remediation commands. **Perfect for on-call engineers debugging live incidents.**
+
+### 2. SRE Agent & Hub (In-Cluster Platform)
+A lightweight, in-cluster daemon (the Agent) that continuously monitors your infrastructure. It autonomously performs the 6-stage AI pipeline on failing resources and pushes structured incident reports to a centralized Hub server. The Hub provides a beautiful web dashboard for a multi-cluster overview, Slack alerts, and detailed RCA records. **Perfect for continuous production monitoring.**
+
+## Key Features
+
+- 📊 **Node & Pod-Level Telemetry**: Real-time resource usage and metrics collection.
+- ⚡ **Auto Incident Detection**: Detects cascading failures, API throttling, Split-Brain StatefulSets, network partitions, and more.
+- 🧠 **6-Stage AI Pipeline**: Triage, Metrics, Logs, Infra, Runbook, and Commander agents collaboratively diagnose root causes.
+- 🚨 **Interactive Auto-Remediation**: Step-by-step CLI prompts (`y / dry / n`) before executing any fix.
+- 🌐 **Centralized Dashboard**: A web UI to view multi-cluster health, active incidents, and automated remediation plans.
+- 🔒 **Safety First**: Destructive commands are flagged. All fixes are verified against a strict allowlist.

website/docusaurus.config.ts

@@ -32,7 +32,8 @@ const config: Config = {
       {
         docs: {
           sidebarPath: './sidebars.ts',
-          editUrl: 'https://github.com/Vaishnav88sk/claritty/issues/',
+          editUrl: ({versionDocsDirPath, docPath}) =>
+            'https://github.com/Vaishnav88sk/claritty/issues',
         },
         blog: false, // Disable the blog plugin
         theme: {

website/sidebars.ts

@@ -13,21 +13,23 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
  Create as many sidebars as you want.
  */
 const sidebars: SidebarsConfig = {
-  // By default, Docusaurus generates a sidebar from the docs folder structure
-  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
-
-  // But you can create a sidebar manually
-  /*
   tutorialSidebar: [
-    'intro',
-    'hello',
     {
       type: 'category',
-      label: 'Tutorial',
-      items: ['tutorial-basics/create-a-document'],
+      label: 'Getting Started',
+      items: ['intro', 'installation'],
+    },
+    {
+      type: 'category',
+      label: 'Core Concepts',
+      items: ['architecture'],
+    },
+    {
+      type: 'category',
+      label: 'Reference',
+      items: ['cli-usage'],
     },
   ],
-   */
 };
 
 export default sidebars;