Comprehensive README update: full PDF integration + repo audit (vision, architecture, state, resilience, intelligence, automation)

Author: miladhzzzz

README.md

@@ -5,114 +5,113 @@
 [![gRPC](https://img.shields.io/badge/gRPC-%2300B4AB.svg?logo=grpc&logoColor=white)](https://grpc.io)
 [![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white)](https://docker.com)
 
-**A lightweight, community-driven distributed compute control plane for orchestrating Docker containers, Docker Compose applications, and virtual machines across heterogeneous infrastructure.**
+**An explainable, scheduler-driven distributed compute control plane that orchestrates containers, Docker Compose applications, and virtual machines across heterogeneous infrastructure.**
 
-Persys Compute brings hyperscaler-inspired orchestration to private, hybrid, and edge environments with minimal overhead and maximum reliability.
+Inspired by hyperscaler architectures, Persys provides a single programmable system to manage compute from a bare-metal server to multi-node clusters — unifying fragmented infrastructure under one control plane with explainable decisions.
 
-## ✨ Features
+## The Problem
 
-- **Multi-workload support**: Docker containers, full Docker Compose stacks, and KVM-based VMs
-- **Resource-aware scheduling**: CPU, memory, disk, and label-based placement
-- **Strong security**: mTLS everywhere, Vault integration for certs and secrets
-- **etcd-backed state**: Persistent, highly available cluster state
-- **Explicit reconciliation**: Automatic drift detection and correction
-- **Observability-first**: Prometheus metrics, structured logs, health endpoints
-- **Lightweight agents**: Simple, reliable node agents with local execution
-- **CLI & API**: `persysctl` for easy management
-- **Federation ready**: Multi-cluster and cloud offloading support
+Modern infrastructure is fragmented: containers, Docker Compose apps, VMs, physical servers, and cloud instances are managed with separate tools. This increases operational complexity across deployment, debugging, scaling, resource management, and failure recovery.
 
-## 🚀 Quick Start
+Persys unifies these under **one programmable API and explainable scheduler**, reducing toolchain entropy.
 
-### Using Docker Compose (Recommended for dev)
+## What Kind of Cloud?
 
-```bash
-# Clone the repo
-git clone https://github.com/persys-dev/persys-cloud.git
-cd persys-cloud
+Persys is an **IaaS foundation** with layered ambitions:
+
+- **IaaS**: Compute primitives and VM lifecycle.
+- **CaaS**: Container orchestration + Docker Compose.
+- **Roadmap → PaaS**: Managed features like GKE/EKS.
+- **Roadmap → DBaaS**: Automated database deployments.
+
+**Vision**: A programmable compute platform exposing compute, platform, and data services through one explainable control plane.
 
-# Start the full stack
-cd infra/docker
-docker compose up -d --build
+## ✨ Core Features
 
-# Build and use CLI
-cd ../../persysctl
-go build -o ./bin/persysctl .
+- **Multi-workload**: Docker containers, full Compose stacks (Git/inline), KVM VMs.
+- **Resource-aware scheduling**: CPU/memory/disk/labels/capabilities.
+- **Explainable decisions**: Persys Intelligence layer with Semi-RAG reasoning.
+- **Strong security**: mTLS, Vault for identity/secrets.
+- **State management**: etcd (persistent) + Redis (operational).
+- **Self-healing**: Leases, heartbeats, reconciliation, auto-reschedule.
+- **Storage**: Ceph-backed VM disks with replication.
+- **Automation**: persys-automation for scaling/remediation based on intelligence.
+- **Observability**: Prometheus, structured logs, health endpoints.
+- **CLI**: `persysctl` for management.
 
-# Check cluster status
+## 🚀 Quick Start
+
+```bash
+git clone https://github.com/persys-dev/persys-cloud.git && cd persys-cloud
+cd infra/docker && docker compose up -d --build
+cd ../../persysctl && go build -o bin/persysctl .
 ./bin/persysctl --transport http cluster list
 ```
 
-See [Local Development](#local-development) for more details.
-
 ## Architecture
 
-Persys Compute follows a strict **control-plane / data-plane** separation:
+**Centralized control-plane model**:
 
-- **Scheduler**: Authoritative brain for placement and reconciliation
-- **Gateway**: REST API entrypoint with auth
-- **Agents**: Dumb executors on nodes
-- **etcd**: Cluster state store
-- **Vault**: Identity and secret management
+1. **persysctl** → **API Gateway** (REST, auth, routing, CoreDNS).
+2. **Scheduler** (persys-scheduler): Authoritative placement, reconciliation, state.
+3. **Agents** (compute-agent): Lightweight executors (no scheduling).
 
-For full details, see [docs/architecture](docs/architecture).
+**Cluster**: Logical pool of nodes with telemetry; scheduler treats uniformly.
 
-## Supported Workloads
+See `docs/architecture/` for diagrams.
 
-### Containers
-Simple image-based workloads with resource limits, volumes, ports, etc.
+## Scheduling
 
-### Docker Compose
-Git-backed or inline YAML deployments with env/secrets injection.
+Telemetry-driven evaluation (utilization, labels, topology) → select optimal node → deploy + reconcile.
 
-### Virtual Machines
-Full VM provisioning with cloud-init, storage pools, and network config.
+Example: "Run PostgreSQL" → ranks nodes by resources → assigns + reports.
 
-## Local Development
+## Cluster State
 
-### Prerequisites
-- Go 1.22+
-- Docker & Docker Compose
-- etcd, Vault (provided via compose)
+- **etcd**: Persistent memory (`/nodes/`, `/workloads/`, `/assignments/`, desired state).
+- **Redis**: High-churn (events, retries, failures).
 
-### Building Components
+Enables crash recovery and efficient operations.
 
-```bash
-# Scheduler
-cd persys-scheduler && make build
+## Reliability & Self-Healing
 
-# Agent
-cd ../compute-agent && make build
+- Heartbeats (~30s) + lease-based liveness.
+- Transient partition tolerance.
+- Automatic reschedule on node loss.
+- Idempotent ops + explicit failures.
 
-# Gateway
-cd ../persys-gateway && make build
-```
+**VM Resilience**: Ceph 3x replication decouples storage from compute.
+
+## Persys Intelligence & Automation
+
+- **Intelligence**: Explainable reasoning over snapshots (state/metrics/events) → recommendations, explanations, forecasts (Semi-RAG, no direct mutation).
+- **Automation**: Acts on recommendations for autoscaling, rebalancing, remediation.
+
+**Layered Brains**:
+1. Execution (Compute).
+2. Reasoning (Intelligence).
+3. Automation.
+
+## Local Development
 
-See individual component READMEs and root `Makefile` for more.
+Prerequisites: Go 1.22+, Docker.
 
-## Contributing
+Build: Use per-component Makefiles or root `Makefile`.
 
-We welcome contributions! Please see contributing guidelines in subdirectories and open issues/PRs.
+Full stack via `infra/docker`.
 
-## Roadmap
+## Contributing & Roadmap
 
-- Full storage pool management
-- Advanced retry and backoff engine
-- Multi-cluster federation
-- Enhanced VM networking and introspection
-- Secrets management integration
-- Stream-based control channels
+See subdir guidelines. Priorities: storage pools, federation, secrets, advanced intelligence.
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file.
+MIT.
 
 ## Links
 
-- [compute-agent](compute-agent) - Node runtime agent
-- [persys-scheduler](persys-scheduler) - Core scheduler
-- [persys-gateway](persys-gateway) - API gateway
-- [persysctl](persysctl) - Command line interface
+- [compute-agent](compute-agent/), [persys-scheduler](persys-scheduler/), [persys-gateway](persys-gateway/), [persys-intelligence](persys-intelligence/), [persys-automation](persys-automation/)
 
 ---
 
-*Engineered for production-grade private and hybrid compute with simplicity and rigor.*
+*Engineered for production-grade, explainable private/hybrid compute.*