infra-cost 0.3.3 → 1.2.0

package/README.md

@@ -12,12 +12,23 @@
 
 *Take control of your cloud costs across AWS, Google Cloud, Azure, Alibaba Cloud, and Oracle Cloud* 🚀
 
-[Installation](#-installation) • [Quick Start](#-quick-start) • [Features](#-features) • [Documentation](#-documentation) • [Contributing](#-contributing)
+[Installation](#-installation) • [Quick Start](#-quick-start) • [Features](#-features) • [Documentation](#-documentation) • [Development](#-development) • [Contributing](#-contributing)
 
 </div>
 
 ---
 
+> **📢 Migrating from v0.x?**
+> infra-cost v1.0 introduces a new subcommand-based CLI architecture for better organization and discoverability.
+>
+> - **Quick migration:** Run `infra-cost config migrate` to automatically update your configuration
+> - **Command changes:** Old flags are now organized subcommands (e.g., `--inventory` → `export inventory json`)
+> - **Full guide:** See [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) for complete migration instructions
+>
+> All new features and improvements are built on this solid foundation!
+
+---
+
 ## 🎯 Why infra-cost?
 
 **Save money. Optimize resources. Make informed decisions.**
@@ -34,7 +45,7 @@
 
 ### 🌐 **Multi-Cloud Support**
 - **AWS** ✅ (Full support with Cost Explorer integration)
-- **Google Cloud** 🚧 (Architecture ready, coming soon)
+- **Google Cloud** ✅ (BigQuery billing export, multi-project support)
 - **Microsoft Azure** 🚧 (Architecture ready, coming soon)
 - **Alibaba Cloud** 🚧 (Architecture ready, coming soon)
 - **Oracle Cloud** 🚧 (Architecture ready, coming soon)
@@ -62,6 +73,173 @@
 - **API Server**: REST endpoints for custom integrations
 - **Webhook Support**: Real-time notifications and integrations
 
+## 📖 CLI Commands Overview
+
+infra-cost v1.0 uses a modern subcommand-based architecture for better organization and discoverability.
+
+### ⚡ Quick Commands
+
+#### `infra-cost now` - Instant Cost Check (NEW in v1.2.0)
+
+See today's cloud spending in one second - perfect for morning cost checks!
+
+```bash
+# Quick daily cost check (zero config)
+infra-cost now
+
+# Output:
+# 💰 Today's Cost: $45.23 (+$3.12 ↑ from yesterday)
+# 📊 Top Services: EC2 $22.10 | RDS $15.30 | S3 $4.20
+# 📈 Month-to-Date: $892.45 / $1,500 (59%)
+#    [███████████████████░░░░░░░░░░] 59%
+#
+# Provider: AWS
+# Run `infra-cost cost` for detailed breakdown
+```
+
+**Features:**
+- 🚀 **Zero configuration** - auto-detects your default AWS profile
+- 📊 **Smart summary** - today's cost + delta from yesterday
+- 🎯 **Top 3 services** - see where your money is going at a glance
+- 💹 **Budget progress** - visual progress bar if budgets configured
+- 🎨 **Color-coded** - green = under budget, red = over budget
+- ⚡ **Lightning fast** - get your answer in ~1 second
+
+**Options:**
+```bash
+infra-cost now                      # Default profile
+infra-cost now --profile prod       # Specific profile
+infra-cost now --provider gcp       # Google Cloud
+infra-cost now --json               # JSON output for scripting
+```
+
+**Perfect for:**
+- Morning stand-ups: "How much did we spend yesterday?"
+- Quick sanity checks before demos
+- Solo developers and indie hackers
+- Anyone who wants instant cost visibility
+
+---
+
+#### `infra-cost free-tier` - AWS Free Tier Tracker (NEW in v1.2.0)
+
+Track your AWS Free Tier usage and prevent surprise bills - perfect for solo developers and indie hackers!
+
+```bash
+# Check free tier status
+infra-cost free-tier
+
+# Output:
+# 🆓 AWS Free Tier Status (Account: 123456789012)
+# ════════════════════════════════════════════════════════════
+#
+# EC2 (t2.micro/t3.micro instances)
+# ├── Used: 620.0 hours / 750 hours (82.7%)
+# ├── [████████████████████████░░░░░░] 83%
+# └── ⚠️ Warning: 130.0 hours remaining
+#
+# S3 (Standard storage)
+# ├── Used: 4.2 GB / 5 GB (84.0%)
+# ├── [████████████████████████░░░░░░] 84%
+# └── ⚠️ Warning: 0.8 GB remaining
+#
+# Lambda (1M requests, 400K GB-sec)
+# ├── Used: 0.0 cost / 0 cost (0.0%)
+# ├── [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0%
+# └── ✅ On track
+#
+# ────────────────────────────────────────────────────────────
+# 💡 Tip: You have 8 days until month end
+```
+
+**Features:**
+- 🆓 **Tracks popular free tier services**: EC2, S3, Lambda, RDS
+- 📊 **Visual progress bars** - see usage at a glance
+- ⚡ **Smart alerts** - warns when approaching limits (default: 80%)
+- 💰 **Cost projection** - estimate month-end overages
+- 🎯 **Perfect for beginners** - avoid surprise AWS bills
+- 🚨 **Status indicators** - green=safe, yellow=warning, red=critical
+
+**Options:**
+```bash
+infra-cost free-tier                       # Check current status
+infra-cost free-tier --alert-threshold 90  # Custom threshold
+infra-cost free-tier --show-projection     # Show projected overages
+infra-cost free-tier --json                # JSON output
+```
+
+**Tracked Services:**
+- **EC2**: 750 hours/month (t2.micro/t3.micro)
+- **S3**: 5 GB storage
+- **Lambda**: Cost-based tracking (free tier = $0 cost)
+
+**Perfect for:**
+- Solo developers and indie hackers
+- Students learning AWS
+- New AWS users avoiding surprise bills
+- Monthly free tier checkups
+
+---
+
+### Command Migration Table
+
+| Command Usage | Old Command (v0.x) | New Command (v1.0) |
+|--------------|-------------------|-------------------|
+| **Cost Analysis** |
+| Default cost analysis | `infra-cost` | `infra-cost cost analyze` |
+| Show cost deltas | `infra-cost --delta` | `infra-cost cost analyze --show-delta` |
+| Cost trends | `infra-cost --trends 30` | `infra-cost cost trends --period 30d` |
+| Compare clouds | `infra-cost --compare-clouds aws,gcp` | `infra-cost cost compare --providers aws,gcp` |
+| Forecast costs | `infra-cost --forecast 30` | `infra-cost cost forecast --days 30` |
+| **Optimization** |
+| Optimization recommendations | `infra-cost --finops` | `infra-cost optimize recommendations` |
+| Quick wins | `infra-cost --quick-wins` | `infra-cost optimize quickwins` |
+| Rightsizing | `infra-cost --rightsize` | `infra-cost optimize rightsizing` |
+| Cross-cloud optimization | `infra-cost --optimization-report` | `infra-cost optimize cross-cloud` |
+| **Monitoring & Alerts** |
+| Cost alerts | `infra-cost --alerts` | `infra-cost monitor alerts` |
+| Budget monitoring | `infra-cost --budgets` | `infra-cost monitor budgets` |
+| Real-time monitoring | `infra-cost --monitor` | `infra-cost monitor watch` |
+| Anomaly detection | `infra-cost --anomaly-detect` | `infra-cost monitor anomaly` |
+| **Export & Reports** |
+| Export inventory (JSON) | `infra-cost --inventory` | `infra-cost export inventory json` |
+| Export inventory (CSV) | `infra-cost --inventory-export csv` | `infra-cost export inventory csv` |
+| Export inventory (Excel) | `infra-cost --inventory-export xlsx` | `infra-cost export inventory xlsx` |
+| Export inventory (PDF) | `infra-cost --inventory-export pdf` | `infra-cost export inventory pdf` |
+| **AWS Organizations** |
+| List accounts | `infra-cost --organizations` | `infra-cost organizations list` |
+| Organization summary | `infra-cost --organizations-summary` | `infra-cost organizations summary` |
+| Daily costs | `infra-cost --organizations-daily` | `infra-cost organizations daily` |
+| **Chargeback** |
+| Chargeback report | `infra-cost --chargeback` | `infra-cost chargeback report` |
+| Send to Slack | `infra-cost --chargeback-slack` | `infra-cost chargeback slack` |
+| **Dashboards** |
+| Interactive dashboard | `infra-cost --dashboard` | `infra-cost dashboard interactive` |
+| Multi-cloud dashboard | `infra-cost --dashboard-multicloud` | `infra-cost dashboard multicloud` |
+| **Configuration** |
+| Show configuration | `infra-cost --config-status` | `infra-cost config show` |
+| Generate configuration | `infra-cost --config-generate` | `infra-cost config init` |
+| Validate configuration | `infra-cost --config-validate` | `infra-cost config validate` |
+| Migrate configuration | N/A (new in v1.0) | `infra-cost config migrate` |
+
+### Available Command Groups
+
+- **`cost`** - Cost analysis, trends, comparisons, and forecasting
+- **`optimize`** - Optimization recommendations and analysis
+- **`monitor`** - Alerts, budgets, and anomaly detection
+- **`export`** - Export data in multiple formats
+- **`organizations`** - AWS Organizations multi-account support
+- **`chargeback`** - Cost allocation and reporting
+- **`config`** - Configuration management
+- **`dashboard`** - Interactive dashboards
+
+**Get help for any command:**
+```bash
+infra-cost --help
+infra-cost cost --help
+infra-cost cost analyze --help
+```
+
 ## 📦 Installation
 
 ### npm (Recommended)
@@ -98,35 +276,77 @@ docker run --rm codecollab-co/infra-cost --help
 
 ### 1. Basic AWS Cost Analysis
 ```bash
-# Using default AWS credentials
-infra-cost
+# Analyze costs with default AWS credentials
+infra-cost cost analyze
 
-# Get a 6-month cost trend with forecasting
-infra-cost --trend --forecast 30
+# Show cost trends over time
+infra-cost cost trends --period 30d
 
-# Interactive multi-cloud dashboard
-infra-cost --multi-cloud-dashboard
+# Compare costs across multiple providers
+infra-cost cost compare --providers aws,gcp
 ```
 
-### 2. Advanced Analysis
+### 2. Google Cloud Platform Cost Analysis
 ```bash
-# Generate executive PDF report
-infra-cost --executive-summary --pdf-report quarterly-report.pdf
+# Analyze GCP costs with service account
+infra-cost cost analyze \
+  --provider gcp \
+  --project-id my-project \
+  --key-file /path/to/service-account.json
+
+# List all accessible GCP projects
+infra-cost cost analyze \
+  --provider gcp \
+  --project-id my-project \
+  --list-projects
+
+# Analyze costs with custom billing dataset
+infra-cost cost analyze \
+  --provider gcp \
+  --project-id my-project \
+  --billing-dataset custom_billing \
+  --billing-table custom_table
+
+# Compare costs across multiple GCP projects
+infra-cost cost compare \
+  --provider gcp \
+  --projects project-1,project-2,project-3
+```
+
+### 3. Optimization & Recommendations
+```bash
+# Get AI-powered optimization recommendations
+infra-cost optimize recommendations
 
-# AI-powered anomaly detection
-infra-cost --anomaly-detect --anomaly-realtime
+# Find quick wins for immediate savings
+infra-cost optimize quickwins
 
-# Comprehensive sustainability analysis
-infra-cost --sustainability --carbon-footprint --green-recommendations
+# Get rightsizing recommendations
+infra-cost optimize rightsizing
 ```
 
-### 3. Team Collaboration
+### 4. Monitoring & Alerts
 ```bash
-# Send daily cost report to Slack
-infra-cost --slack-token YOUR_TOKEN --slack-channel "#finops" --smart-alerts
+# Check cost alerts and budget status
+infra-cost monitor alerts
+
+# Monitor budgets
+infra-cost monitor budgets
 
-# Start real-time cost monitoring
-infra-cost --monitor --alert-threshold 1000 --alert-channel slack
+# Detect cost anomalies
+infra-cost monitor anomaly
+```
+
+### 5. Team Collaboration
+```bash
+# Send cost report to Slack
+infra-cost chargeback slack
+
+# Generate chargeback report
+infra-cost chargeback report
+
+# Interactive dashboard
+infra-cost dashboard interactive
 ```
 
 ## 🔐 Authentication
@@ -138,67 +358,166 @@ infra-cost --monitor --alert-threshold 1000 --alert-channel slack
 export AWS_ACCESS_KEY_ID=your_access_key
 export AWS_SECRET_ACCESS_KEY=your_secret_key
 export AWS_REGION=us-east-1
-infra-cost
+infra-cost cost analyze
 ```
 
 #### 2. AWS Profiles
 ```bash
 # Use default profile
-infra-cost
+infra-cost cost analyze
 
 # Use specific profile
-infra-cost --profile production
+infra-cost cost analyze --profile production
 
-# Auto-discover profiles
-infra-cost --discover-profiles --auto-profile
+# Discover available profiles
+infra-cost config show --discover-profiles
 ```
 
 #### 3. IAM Roles (EC2/Lambda/ECS)
 ```bash
 # Automatically uses attached IAM role
-infra-cost
+infra-cost cost analyze
 ```
 
 #### 4. AWS SSO
 ```bash
 aws sso login --profile my-sso-profile
-infra-cost --profile my-sso-profile
+infra-cost cost analyze --profile my-sso-profile
+```
+
+#### 5. Configuration File
+```bash
+# Initialize configuration
+infra-cost config init
+
+# Validate configuration
+infra-cost config validate
+
+# Show current configuration
+infra-cost config show
+```
+
+### Google Cloud Platform Authentication
+
+#### 1. Service Account Key File (Recommended)
+```bash
+# Download service account key from GCP Console
+# IAM & Admin > Service Accounts > Create Key (JSON)
+
+export GOOGLE_PROJECT_ID=your-project-id
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
+infra-cost cost analyze --provider gcp
+```
+
+#### 2. Application Default Credentials (ADC)
+```bash
+# Authenticate with gcloud CLI
+gcloud auth application-default login
+
+# Set default project
+gcloud config set project your-project-id
+
+# Run infra-cost
+infra-cost cost analyze --provider gcp --project-id your-project-id
+```
+
+#### 3. Command-Line Arguments
+```bash
+infra-cost cost analyze \
+  --provider gcp \
+  --project-id my-project \
+  --key-file /path/to/service-account.json
 ```
 
-### Multi-Cloud Setup (Coming Soon)
+#### 4. Configuration File
+```bash
+# Initialize configuration with GCP
+infra-cost config init
+
+# Edit ~/.infra-cost/config.json
+{
+  "provider": "gcp",
+  "credentials": {
+    "projectId": "my-project",
+    "keyFilePath": "/path/to/service-account.json",
+    "billingDatasetId": "billing_export",
+    "billingTableId": "gcp_billing_export"
+  }
+}
+```
+
+#### GCP Permissions Required
+Your service account needs the following IAM permissions:
+- `resourcemanager.projects.get` - Read project information
+- `bigquery.jobs.create` - Query billing data
+- `bigquery.tables.getData` - Read billing tables
+
+**Recommended IAM Role:** `roles/bigquery.user` + custom role for project access
+
+#### Enable BigQuery Billing Export
+infra-cost requires BigQuery billing export to be enabled:
+
+1. Go to [GCP Billing Console](https://console.cloud.google.com/billing)
+2. Select your billing account
+3. Navigate to "Billing export"
+4. Enable "BigQuery export"
+5. Configure dataset (default: `billing_export`)
+6. Wait 24 hours for initial data
+
+### Multi-Cloud Setup
+
 ```bash
 # Google Cloud Platform
-infra-cost --provider gcp --project-id my-project --key-file service-account.json
+infra-cost cost analyze --provider gcp --project-id my-project --key-file service-account.json
 
-# Microsoft Azure
-infra-cost --provider azure --subscription-id sub-id --tenant-id tenant-id
+# Microsoft Azure (Coming Soon)
+infra-cost cost analyze --provider azure --subscription-id sub-id --tenant-id tenant-id
+
+# Oracle Cloud (Coming Soon)
+infra-cost cost analyze --provider oracle --user-id user-ocid --tenancy-id tenancy-ocid
 
 # Cross-cloud comparison
-infra-cost --compare-clouds aws,gcp,azure --optimization-report
+infra-cost cost compare --providers aws,gcp
+
+# Cross-cloud optimization report (Coming Soon)
+infra-cost optimize cross-cloud
 ```
 
 ## 📊 Output Examples
 
 ### Default Rich Terminal UI
 ```bash
-infra-cost --smart-alerts --compact
+infra-cost cost analyze --output fancy
 ```
 ![Cost Analysis](./.github/images/aws-cost.png)
 
-### Executive Dashboard
+### Export Options
 ```bash
-infra-cost --executive-summary
+# Export inventory to JSON
+infra-cost export inventory json
+
+# Export to CSV
+infra-cost export inventory csv
+
+# Export to Excel
+infra-cost export inventory xlsx
+
+# Export to PDF
+infra-cost export inventory pdf
 ```
-![Executive Summary](./.github/images/executive-dashboard.png)
 
 ### JSON for Automation
 ```bash
-infra-cost --json --forecast 30 --analytics-insights
+infra-cost cost analyze --output json
 ```
 
-### PDF Reports
+### Interactive Dashboard
 ```bash
-infra-cost --pdf-report monthly-report.pdf --trend --optimization-tips
+# Launch interactive terminal dashboard
+infra-cost dashboard interactive
+
+# Multi-cloud dashboard
+infra-cost dashboard multicloud
 ```
 
 ## 💬 Slack Integration
@@ -211,14 +530,15 @@ infra-cost --pdf-report monthly-report.pdf --trend --optimization-tips
 
 ### Setup & Usage
 ```bash
-# Create Slack app with chat:write permissions
-# Get OAuth token and channel ID
+# Configure Slack credentials (one-time setup)
+export SLACK_TOKEN=xoxb-your-token
+export SLACK_CHANNEL="#finops"
 
-# Send cost report
-infra-cost --slack-token xoxb-your-token --slack-channel "#finops"
+# Send chargeback report to Slack
+infra-cost chargeback slack
 
-# Enable smart alerts
-infra-cost --slack-token xoxb-your-token --slack-channel "#alerts" --smart-alerts
+# Or provide inline
+infra-cost chargeback slack --slack-token xoxb-your-token --slack-channel "#finops"
 ```
 
 ### Automated Daily Reports
@@ -232,11 +552,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - run: |
-          npx infra-cost \
-            --executive-summary \
+          npx infra-cost chargeback slack \
             --slack-token ${{ secrets.SLACK_TOKEN }} \
-            --slack-channel ${{ secrets.SLACK_CHANNEL }} \
-            --smart-alerts --trends 7
+            --slack-channel ${{ secrets.SLACK_CHANNEL }}
 ```
 
 ## 🤖 GitHub Actions Integration
@@ -334,88 +652,284 @@ See [example workflows](.github/workflows/examples/) for more use cases.
 
 ## 🔧 Advanced Usage
 
-### Cost Forecasting & Analytics
+### AWS Organizations Support
+
+#### Multi-Account Management
+```bash
+# List all accounts in organization
+infra-cost organizations list
+
+# Get organization-wide cost summary
+infra-cost organizations summary
+```
+
+#### Daily Cost Reports with Slack Integration
+```bash
+# Get daily costs for all accounts
+infra-cost organizations daily
+
+# Send daily report to Slack
+infra-cost organizations daily --slack-webhook https://hooks.slack.com/services/YOUR/WEBHOOK/URL
+
+# View 30-day history
+infra-cost organizations daily --days 30
+
+# Get scheduling instructions for automated daily reports
+infra-cost organizations daily --schedule-daily --schedule-time 09:00
+
+# Export to JSON for automation
+infra-cost organizations daily --json
+```
+
+**Features:**
+- 📊 Multi-account cost breakdown
+- 📈 Day-over-day cost trends with visual indicators
+- 🔥 Top 5 spender accounts
+- 📊 Weekly averages and projections
+- 💬 Slack webhook integration for team notifications
+- ⏰ Scheduling instructions (cron, Lambda, GitHub Actions)
+
+**Perfect for:**
+- Large organizations with multiple AWS accounts
+- FinOps teams managing cross-account costs
+- Daily cost visibility and team accountability
+- Automated cost reporting workflows
+
+### Cost Analysis & Forecasting
 ```bash
-# AI-powered forecasting with multiple models
-infra-cost --forecast 90 --forecast-model AUTO --forecast-confidence 95
+# Analyze costs with delta comparison
+infra-cost cost analyze --show-delta --delta-threshold 10
 
-# Business intelligence insights
-infra-cost --analytics --analytics-insights --analytics-drivers
+# Get cost trends
+infra-cost cost trends --period 90d
 
-# Custom dashboards
-infra-cost --dashboard-create "Monthly Review" --chart-create "line:Cost Trends"
+# Compare costs across providers
+infra-cost cost compare --providers aws,gcp,azure
+
+# Forecast future costs
+infra-cost cost forecast --days 30
 ```
 
-### Optimization & Automation
+### Optimization Commands
 ```bash
-# Generate optimization recommendations
-infra-cost --finops --optimization-tips --rightsize --sustainability
+# Get all optimization recommendations
+infra-cost optimize recommendations
+
+# Find quick wins for immediate savings
+infra-cost optimize quickwins
 
-# Automated optimization (dry-run first!)
-infra-cost --optimize-dry-run --optimize-rules resize,schedule,unused
+# Get rightsizing recommendations
+infra-cost optimize rightsizing
 
-# Cross-cloud cost comparison
-infra-cost --compare-clouds aws,gcp --optimization-report
+# Cross-cloud optimization analysis
+infra-cost optimize cross-cloud
 ```
 
-### Enterprise Features
+### Monitoring & Alerts
 ```bash
-# Multi-tenant management
-infra-cost --enterprise --tenants --platform-metrics
+# Check cost alerts
+infra-cost monitor alerts
 
-# API server for integrations
-infra-cost --api-server --api-port 3000 --webhook-create
+# Monitor budgets
+infra-cost monitor budgets
 
-# Comprehensive audit logging
-infra-cost --audit --compliance-check soc2 --audit-export json
+# Watch for cost changes in real-time
+infra-cost monitor watch
+
+# Detect anomalies
+infra-cost monitor anomaly
+```
+
+### Configuration Management
+```bash
+# Initialize new configuration
+infra-cost config init
+
+# Show current configuration
+infra-cost config show
+
+# Validate configuration
+infra-cost config validate
+
+# Migrate from old version
+infra-cost config migrate
 ```
 
 ## 🏗️ Architecture & Extensibility
 
-### Multi-Cloud Provider Pattern
+### Clean Architecture Structure (v1.0)
 ```
 src/
-├── providers/
-│   ├── factory.ts      # Provider factory
-│   ├── aws.ts          # AWS implementation ✅
-│   ├── gcp.ts          # Google Cloud 🚧
-│   ├── azure.ts        # Azure 🚧
-│   ├── alicloud.ts     # Alibaba Cloud 🚧
-│   └── oracle.ts       # Oracle Cloud 🚧
-├── analytics/          # AI/ML cost analysis
-├── optimization/       # Cost optimization engines
-├── visualization/      # Dashboards & charts
-├── integrations/       # Third-party integrations
-└── enterprise/         # Multi-tenant features
+├── cli/                        # CLI layer
+│   ├── commands/              # Subcommand structure
+│   │   ├── cost/             # Cost analysis commands
+│   │   ├── optimize/         # Optimization commands
+│   │   ├── monitor/          # Monitoring commands
+│   │   ├── export/           # Export commands
+│   │   ├── organizations/    # AWS Organizations commands
+│   │   ├── chargeback/       # Chargeback commands
+│   │   ├── config/           # Configuration commands
+│   │   └── dashboard/        # Dashboard commands
+│   ├── middleware/           # Auth, validation, error handling
+│   └── index.ts              # CLI entry point
+├── core/                      # Core business logic
+│   ├── config/               # Configuration system
+│   │   ├── schema.ts         # Zod validation schemas
+│   │   ├── loader.ts         # Config file loading
+│   │   ├── discovery.ts      # Profile discovery
+│   │   └── profiles.ts       # Profile management
+│   ├── logging/              # Structured logging
+│   ├── analytics/            # Cost analytics engines
+│   ├── optimization/         # Optimization engines
+│   └── monitoring/           # Monitoring systems
+├── providers/                 # Cloud provider implementations
+│   ├── factory.ts            # Provider factory
+│   └── aws/                  # AWS implementation ✅
+│       ├── provider.ts       # Main provider class
+│       ├── cost.ts           # Cost Explorer integration
+│       ├── account.ts        # Account/Organizations
+│       └── config.ts         # AWS-specific config
+├── exporters/                # Output formatters
+│   └── formats/
+│       ├── fancy.ts          # Rich terminal output
+│       ├── json.ts           # JSON output
+│       ├── text.ts           # Plain text
+│       └── slack.ts          # Slack formatting
+└── enterprise/               # Enterprise features
+    ├── multi-tenant/         # Multi-tenancy support
+    └── audit/                # Audit logging
 ```
 
 ### Key Design Principles
-- **Abstract provider interface** for consistent multi-cloud API
-- **Plugin architecture** for easy extensibility
-- **Type-safe implementation** with comprehensive TypeScript coverage
-- **Modular design** allowing feature composition
-- **Performance optimized** with efficient data processing
+- **Subcommand Architecture** - Domain-organized, discoverable commands
+- **Clean Separation** - CLI, core logic, and providers are decoupled
+- **Type Safety** - Comprehensive TypeScript with Zod validation
+- **Testability** - Dependency injection and mocking support
+- **Extensibility** - Plugin architecture for new providers
+- **Configuration First** - Unified config system with profiles
 
 ## 🚀 Roadmap
 
-### Q4 2024
+### ✅ Completed (2024-2025)
+
+**Core Platform & Architecture:**
 - ✅ Enhanced terminal UI and visualization
 - ✅ AI-powered anomaly detection
 - ✅ Comprehensive PDF reporting
 - ✅ Advanced Slack integration
-- 🚧 Google Cloud Platform support
-
-### Q1 2025
-- 🔮 Microsoft Azure integration
-- 🔮 Advanced forecasting models
-- 🔮 Mobile app companion
-- 🔮 Sustainability tracking expansion
-
-### Q2 2025
-- 🔮 Alibaba Cloud & Oracle Cloud support
-- 🔮 Advanced automation engine
-- 🔮 Enterprise SSO integration
-- 🔮 Custom plugin system
+- ✅ GitHub Actions integration
+- ✅ npm and Homebrew distribution
+- ✅ **Phase 1: Clean Architecture Restructuring (v1.0)**
+  - Subcommand-based CLI architecture
+  - Unified configuration system with profiles
+  - Automatic cloud profile discovery
+  - Structured logging with audit trails
+  - AWS Organizations support (Issue #10 ✅)
+  - Cost allocation and chargeback reporting (Issue #30 ✅)
+  - Configuration file support (Issue #29 ✅)
+  - Caching layer for performance (Issue #28 ✅)
+  - IAM Roles and environment variables auth (Issues #12, #13 ✅)
+  - AWS SSO login support (Issue #9 ✅)
+
+**Multi-Cloud Foundation:**
+- ✅ Multi-cloud provider architecture (Issue #20 - foundation)
+  - AWS provider fully implemented
+  - GCP, Azure, Alibaba Cloud, Oracle Cloud - architecture ready
+
+### Q1 2026 (Current - In Progress)
+
+**Priority: Multi-Cloud Expansion**
+- ✅ **Google Cloud Platform support - COMPLETE** (Issue #66)
+  - ✅ Provider implementation with BigQuery billing export
+  - ✅ GCP authentication (service account, ADC)
+  - ✅ Multi-project support with parallel retrieval
+  - ✅ Multi-currency cost aggregation
+  - ✅ Cost breakdown by service and time period
+  - ✅ Resource inventory (GCE, Storage, SQL, GKE)
+  - ✅ Budget tracking and alerts
+  - ✅ Organization-level cost aggregation
+  - ✅ Comprehensive documentation and examples
+  - ✅ 65 unit tests passing (100% coverage)
+- 📋 **Advanced forecasting models** (No GitHub issue)
+  - ML-based cost predictions
+  - Seasonal trend analysis
+  - Budget recommendations
+- 📋 **Enhanced analytics** (No GitHub issue)
+  - Advanced cost attribution
+  - Custom tagging strategies
+  - Cost optimization scoring
+
+### Q2 2026 (Planned)
+
+**Priority: Complete Multi-Cloud & Automation**
+- 🔮 **Microsoft Azure integration** (Issue #20 - partial)
+  - Azure Cost Management API
+  - Subscription and resource group support
+  - Azure-specific recommendations
+- 🔮 **Alibaba Cloud support** (Issue #20 - partial)
+  - Alibaba Cloud Cost API integration
+  - Multi-region support
+- 🔮 **Oracle Cloud support** (Issue #20 - partial)
+  - OCI Cost Management integration
+  - Compartment-based analysis
+- 📋 **Advanced automation engine** (No GitHub issue)
+  - Automated cost optimization actions
+  - Policy-based automation
+  - Approval workflows
+  - Related: Issue #42 (Scheduled Reports), Issue #49 (API Server)
+
+### Q3 2026 (Planned)
+
+**Priority: Enterprise Features**
+- ✅/🚧 **Enterprise SSO integration**
+  - AWS SSO: ✅ Completed (Issue #9)
+  - SAML/OAuth support: 🔲 Planned (Issue #52)
+  - Azure AD, Okta, Auth0 integration: 🔲 Planned
+  - Role-based access control (RBAC): 🔲 Planned (Issue #50)
+- 📋 **Custom plugin system** (No GitHub issue)
+  - Plugin SDK
+  - Custom provider support
+  - Third-party integrations
+- 📋 **Mobile app companion** (No GitHub issue)
+  - iOS and Android apps
+  - Real-time cost alerts
+  - Executive dashboards on mobile
+
+### Future Vision
+
+**FinOps & Intelligence:**
+- 📋 **Sustainability tracking expansion** (No GitHub issue)
+  - Carbon footprint tracking
+  - Green cloud recommendations
+  - Renewable energy usage analytics
+- 🔲 **FinOps best practices automation** (Issue #59 - partial)
+  - FinOps Scorecards implementation
+  - Automated best practices enforcement
+  - Team performance metrics
+- 🔲 **AI-powered cost conversations** (Issue #44 - partial)
+  - Natural language cost queries
+  - ChatOps integration
+  - AI cost assistant
+
+**Platform & Scale:**
+- 📋 **Multi-tenant SaaS platform** (No GitHub issue)
+  - Organization management
+  - Team collaboration features
+  - Centralized cost governance
+- 🔲 **Additional integrations** (Various open issues)
+  - Microsoft Teams (Issue #45)
+  - PagerDuty/OpsGenie (Issue #48)
+  - Terraform cost preview (Issue #47)
+  - API Server mode (Issue #49)
+  - Multi-cloud dashboard (Issue #62)
+  - Web-based dashboards (Issue #60)
+
+**Legend:**
+- ✅ Completed
+- 🚧 In Progress
+- 🔮 Planned (this quarter)
+- 🔲 Open GitHub Issue
+- 📋 Not yet tracked in GitHub issues
 
 ## 📋 Requirements & Permissions
 
@@ -449,6 +963,8 @@ src/
 
 ## 🧪 Development
 
+> 📚 **Developer Resources**: See the [`docs/`](./docs) folder for comprehensive technical documentation including architecture guides, testing reports, and release procedures.
+
 ### Local Development Setup
 ```bash
 # Clone repository
@@ -551,6 +1067,28 @@ For enterprise deployments, custom integrations, and professional support:
 - 🎨 Custom branding and whitelabeling
 - 🏗️ Professional services and consulting
 
+## 📚 Documentation
+
+### 📖 User Documentation
+- **[README.md](./README.md)** - Main project documentation (you are here)
+- **[CHANGELOG.md](./CHANGELOG.md)** - Version history and release notes
+- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Contribution guidelines
+
+### 🔧 Developer Documentation
+Comprehensive technical documentation is available in the [`docs/`](./docs) folder:
+
+- **[docs/RELEASE_SUMMARY.md](./docs/RELEASE_SUMMARY.md)** - Complete release guide for GitHub, npm, and Homebrew
+- **[docs/PRODUCTION_READINESS.md](./docs/PRODUCTION_READINESS.md)** - Production readiness assessment and checklist
+- **[docs/TEST_RESULTS.md](./docs/TEST_RESULTS.md)** - Comprehensive test results and analysis
+- **[docs/NPM_PUBLISHING.md](./docs/NPM_PUBLISHING.md)** - npm publishing workflow and best practices
+- **[docs/HOMEBREW_SETUP.md](./docs/HOMEBREW_SETUP.md)** - Homebrew formula creation guide
+- **[docs/code_flow.md](./docs/code_flow.md)** - Codebase architecture and flow
+- **[docs/infra_cost_cli.md](./docs/infra_cost_cli.md)** - CLI implementation details
+- **[docs/MULTI-CLOUD-INVENTORY.md](./docs/MULTI-CLOUD-INVENTORY.md)** - Multi-cloud features
+- **[docs/ENHANCED-FEATURES.md](./docs/ENHANCED-FEATURES.md)** - Advanced capabilities
+
+See [docs/README.md](./docs/README.md) for the complete documentation index.
+
 ## 📄 License
 
 MIT © [Code Collab](https://github.com/codecollab-co)
@@ -559,7 +1097,27 @@ MIT © [Code Collab](https://github.com/codecollab-co)
 
 ## 🔄 Changelog
 
-### v0.3.0 - Latest Release
+### v1.0.0 - Major Release (Phase 1: Clean Architecture) 🎉
+- ✅ **Subcommand-Based CLI** - New organized command structure
+  - `cost` - Cost analysis and trends
+  - `optimize` - Optimization recommendations
+  - `monitor` - Alerts and monitoring
+  - `export` - Data export in multiple formats
+  - `organizations` - AWS Organizations support
+  - `chargeback` - Cost allocation and reporting
+  - `config` - Configuration management
+  - `dashboard` - Interactive dashboards
+- ✅ **Unified Configuration System** - Single config file with profiles
+- ✅ **Profile Discovery** - Auto-detect cloud provider profiles
+- ✅ **Clean Architecture** - Separation of CLI, core, and providers
+- ✅ **Enhanced Logging** - Structured logging with multiple outputs
+- ✅ **Migration Tool** - Automated migration from v0.x (`infra-cost config migrate`)
+- ✅ **Improved Error Handling** - Better error messages and validation
+- ✅ **TypeScript Improvements** - Full type safety with Zod schemas
+
+**Breaking Changes:** See [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) for upgrading from v0.x
+
+### v0.3.0
 - ✅ **GitHub Marketplace Action** - Integrate cost analysis into CI/CD workflows
 - ✅ **Node.js 20+ support** - Updated runtime requirements
 - ✅ **Sprint 6 UX improvements** - Enhanced user experience
@@ -579,8 +1137,8 @@ MIT © [Code Collab](https://github.com/codecollab-co)
 - ✅ **Multi-cloud architecture** ready for expansion
 - ✅ **Enterprise features** including multi-tenancy and API server
 
-### Migration from aws-cost-cli
-This tool evolved from `aws-cost-cli` with full backward compatibility. Both `infra-cost` and `aws-cost` commands work seamlessly.
+### Migration from v0.x
+See the comprehensive [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) for step-by-step instructions on migrating from v0.x to v1.0.
 
 ---