Updated docs

README.md

@@ -494,6 +494,17 @@ CleanCloud will remain focused on **safe hygiene detection**, not automation or
 
 ---
 
+## 💬 Questions or Feedback?
+
+We'd love to hear from you:
+
+- 🐛 **Found a bug?** [Open an issue](https://github.com/sureshcsdp/cleancloud/issues)
+- 💡 **Have a feature request?** [Start a discussion](https://github.com/sureshcsdp/cleancloud/discussions)
+- 📧 **Want to chat?** Email us at suresh@sure360.io
+- 🌟 **Like CleanCloud?** [Star us on GitHub](https://github.com/sureshcsdp/cleancloud)
+
+**Using CleanCloud in production?** We'd love to feature your story!
+
 ## Contributing
 
 Contributions are welcome! Please ensure all PRs:

docs/what-is-cleancloud.md

@@ -0,0 +1,143 @@
+# CleanCloud
+
+**Category:** Cloud Hygiene Intelligence  
+**Stage:** Early product, enterprise-grade foundations  
+**Philosophy:** Read-only • Conservative • Trust-first
+
+---
+
+## What Is CleanCloud?
+
+CleanCloud is a **cloud hygiene intelligence layer** that identifies **orphaned, unowned, and potentially inactive cloud resources** using **high-confidence, review-only signals**.
+
+It does **not** automate cleanup.  
+It tells teams **what deserves review — and why**.
+
+---
+
+## The Problem
+
+Modern cloud environments are:
+- Elastic and ephemeral
+- Heavily IaC-driven
+- Owned by many teams with weak attribution
+
+This creates:
+- Orphaned storage, snapshots, logs, and network resources
+- Security and operational risk
+- Cleanup paralysis due to blast-radius fear
+
+### Why Existing Tools Fall Short
+- **Auto-delete tools** → unsafe in production
+- **Cost tools** → noisy, billing-centric, low trust
+- **Security tools** → too broad, hygiene is a side concern
+
+---
+
+## CleanCloud’s Insight
+
+> **Cloud hygiene is a trust problem, not an automation problem.**
+
+Teams want:
+- Conservative detection
+- Transparent reasoning
+- Explicit confidence levels
+- Zero write permissions
+
+CleanCloud is designed to earn trust first.
+
+---
+
+## What CleanCloud Does
+
+- Scans AWS and Azure using **read-only APIs**
+- Uses **multiple conservative signals per rule**
+- Assigns explicit **confidence levels** (LOW / MEDIUM / HIGH)
+- Preserves evidence for every finding
+- Runs natively in CI/CD via **OIDC (no long-lived secrets)**
+
+---
+
+## What CleanCloud Deliberately Does NOT Do
+
+- ❌ No auto-delete or auto-remediation
+- ❌ No write, tag, or mutate permissions
+- ❌ No billing or cost data access
+- ❌ No opinionated workflows
+
+This is a **strategic design choice**, not a limitation.
+
+---
+
+## Why CleanCloud Is Valuable
+
+| Dimension | CleanCloud |
+|--------|-----------|
+| Safety | Read-only, review-only |
+| Signal quality | Conservative, multi-signal rules |
+| Trust | Explicit confidence + evidence |
+| Adoption | CI-native, OIDC-first |
+| Compliance | SOC2 / ISO / regulated-friendly |
+| Integration | Clean JSON/CSV output |
+
+---
+
+## Users & Buyers
+
+- **Primary users:** SRE, Platform, Infrastructure teams
+- **Stakeholders:** Security, Compliance, FinOps
+
+---
+
+## Strategic Fit for an Acquirer
+
+CleanCloud acts as:
+- A **signal generator** upstream of automation
+- A **trust layer** before remediation
+- A **complement** to observability, security, and governance platforms
+
+It is designed to be:
+- Embedded
+- Integrated
+- Extended
+
+—not replaced.
+
+---
+
+## Current State (v0.3.0)
+
+- AWS + Azure support
+- OIDC-first authentication (no secrets)
+- Agentless, read-only scanning
+- Conservative hygiene rules (storage, snapshots, logs, public IPs)
+- CI/CD-ready doctor validation
+
+---
+
+## Near-Term Expansion (Low Risk)
+
+- Ownership & attribution hints
+- Rule contracts and evidence schemas
+- Additional conservative hygiene rules
+
+No change to the trust or safety model.
+
+---
+
+## Long-Term Vision
+
+CleanCloud becomes the **standard cloud hygiene intelligence substrate** inside:
+- Observability platforms
+- CNAPP / security tooling
+- CMDB and workflow engines
+
+Always focused on **signal quality, trust, and safety**.
+
+---
+
+## Positioning Summary
+
+CleanCloud is not a cleanup tool.
+
+It is the **missing intelligence layer** that makes cleanup, governance, and automation safe to do *later* — by humans or trusted systems.

docs/why-no-auto-delete.md

@@ -0,0 +1,148 @@
+# Why CleanCloud Will Never Auto-Delete Your Cloud Resources
+
+Most cloud hygiene tools promise automation.
+
+CleanCloud deliberately refuses it.
+
+This is not a technical limitation — it’s a **design decision**.
+
+---
+
+## The Temptation of Auto-Deletion
+
+At first glance, auto-delete sounds appealing:
+
+- Orphaned disks? Delete them.
+- Old snapshots? Clean them up.
+- Unused IPs? Reclaim them.
+
+But in real production environments, this thinking breaks down fast.
+
+---
+
+## Why Auto-Delete Fails in the Real World
+
+### 1. Cloud Context Is Incomplete
+
+Cloud APIs do not know:
+- Business intent
+- Deployment timelines
+- Human ownership
+- Out-of-band dependencies
+
+A resource that looks unused today may be:
+- A rollback safety net
+- A compliance artifact
+- A disaster recovery dependency
+
+Deleting it automatically is guessing — not engineering.
+
+---
+
+### 2. IaC and Elastic Infrastructure Create False Positives
+
+Modern infrastructure is:
+- Created automatically
+- Destroyed partially
+- Recreated frequently
+
+Short-lived orphaned resources are **normal**.
+
+Aggressive cleanup tools misinterpret this churn as waste.
+
+CleanCloud waits — deliberately.
+
+---
+
+### 3. Blast Radius Is Non-Linear
+
+Deleting the wrong resource can:
+- Break production
+- Corrupt backups
+- Violate compliance
+- Trigger outages days later
+
+The cost of a false positive deletion is **orders of magnitude higher** than the cost of leaving a resource untouched.
+
+---
+
+### 4. Security Teams Don’t Trust Automation
+
+In regulated environments:
+- Auto-deletion is a red flag
+- Write permissions are heavily restricted
+- Tooling must be auditable and reversible
+
+Read-only tools pass security review.
+Auto-remediation tools often don’t.
+
+---
+
+## The CleanCloud Philosophy: Signal First
+
+CleanCloud answers a safer question:
+
+> *“Which resources deserve a human review — and how confident are we?”*
+
+Instead of deleting:
+- We explain *why* a resource was flagged
+- We show *how confident* we are
+- We provide *evidence* for investigation
+
+Humans stay in control.
+
+---
+
+## Confidence Beats Aggression
+
+CleanCloud assigns explicit confidence levels:
+- **HIGH** — multiple strong signals, long age thresholds
+- **MEDIUM** — likely hygiene issue, worth review
+- **LOW** — informational, not actionable by default
+
+No single signal is ever enough.
+
+---
+
+## Why This Matters Long-Term
+
+Auto-delete tools:
+- Maximize short-term savings
+- Minimize trust
+- Create operational fear
+
+CleanCloud:
+- Maximizes signal quality
+- Builds long-term trust
+- Enables safe automation *later*
+
+---
+
+## What CleanCloud Enables Instead
+
+- CI/CD hygiene gates
+- Ownership review workflows
+- Human-approved remediation
+- Integration with security and CMDB systems
+
+Automation is possible — **after trust is established**.
+
+---
+
+## Our Promise
+
+CleanCloud will:
+- Never delete your resources
+- Never modify your infrastructure
+- Never make irreversible decisions for you
+
+Because cloud hygiene should be:
+- Safe
+- Deliberate
+- Human-reviewed
+
+Not aggressive.
+
+---
+
+**CleanCloud is built for teams who value trust over automation.**