@thunder-so/thunder 1.1.0

package/.agents/CLI.md

@@ -0,0 +1,65 @@
+# Thunder CLI Scope
+
+The Thunder CLI (`th`) is the primary interface for developing, deploying, and managing applications built with `@thunder-so/thunder`. It is designed to be a thin, context-aware wrapper around the AWS CDK, providing a developer experience similar to SST but tailored for the Thunder ecosystem.
+
+## Core Mandates
+
+1.  **Context-Awareness:** [x] **DONE**: The CLI automatically detects the current environment, application, and service from the repository structure or configuration, minimizing repetitive flag usage.
+2.  **Zero-Config Defaults:** [x] **DONE**: "It just works" out of the box with sensible defaults for AWS regions, accounts, and resource sizing.
+3.  **Local Dev Parity:** [ ] **TODO**: Enables a local development loop that closely mirrors production, including live Lambda iteration (future scope) and local emulation of static sites.
+
+## Command Reference
+
+### `th init`
+- [ ] **TODO**: Scaffolds a new Thunder project or adds a new service to an existing monorepo.
+
+-   **Usage:** `th init [template] [name]`
+-   **Features:**
+    -   Detects if running in an existing workspace (monorepo).
+    -   Prompts for project type: `static`, `lambda`, `fargate`, `nuxt`, `astro`, `ec2`, `template`.
+    -   Generates `thunder.config.ts` (or updates it).
+    -   Creates necessary `bin/*.ts` entry points.
+    -   Sets up `.gitignore` and `package.json` scripts.
+
+### `th deploy`
+- [ ] **TODO**: Deploys the application to AWS.
+
+-   **Usage:** `th deploy [--stage <stage>] [--filter <service>]`
+-   **Features:**
+    -   **Stage Management:** defaults to `dev` for local, but supports `prod`, `staging`, `pr-*`.
+    -   **Context-Driven:** [x] **DONE**: Reads `bin/*.ts` files to determine which stacks to deploy.
+    -   **Metadata Push:** [x] **DONE**: Updates the `thunder-discovery` bucket with new resource ARNs and endpoints after successful deployment.
+    -   **Output:** Prints critical URLs (CloudFront, API Gateway, ALB) to the console.
+
+### `th destroy`
+- [ ] **TODO**: Tears down resources.
+
+-   **Usage:** `th remove [--stage <stage>] [--filter <service>]`
+-   **Features:**
+    -   **Safety Checks:** Prompts for confirmation, especially for `prod` stages or stateful resources (RDS, S3).
+    -   **Metadata Cleanup:** Removes entries from the `thunder-discovery` bucket.
+
+## Implementation Details
+
+### Context Resolution (`bin/*.ts`)
+- [x] **DONE**: The CLI relies on the convention of `bin/<type>.ts` files. 
+-   `th deploy` scans `bin/` directory.
+-   It executes these scripts using `ts-node` or `tsx`.
+-   The scripts instantiate the Stacks (e.g., `NuxtStack`, `FargateStack`).
+-   The CLI injects context (app, env, service, account, region) via environment variables or context context keys.
+
+### CLI Architecture
+- [ ] **TODO**:
+-   **Runtime:** Node.js
+-   **Core Libs:** `aws-cdk` (programmatic), `aws-sdk` (v3), `inquirer` (prompts), `commander` (args), `ink` (TUI).
+-   **Build:** `esbuild` for fast bundling of Lambda code during `th dev`.
+
+## Comparison with SST
+
+| Feature | SST CLI | Thunder CLI |
+| :--- | :--- | :--- |
+| **Engine** | Pulumi / Terraform (v3) | AWS CDK (Native) |
+| **Language** | TypeScript / Python / Go | TypeScript (Strict) |
+| **State** | Cloud State Backend | CloudFormation + S3 Metadata |
+| **Local Dev** | Live Lambda (Multiplexing) | Hotswap + Local Framework Server |
+| **Constructs** | Broad (150+ providers) | Focused (AWS Web patterns) |

package/.agents/METADATA.md

@@ -0,0 +1,75 @@
+# Metadata Discovery
+
+Thunder implements an "SST-style" discovery mechanism to enable the Thunder CLI and potential future Thunder Console to automatically identify and interact with deployed resources without relying on manual tagging or complex CloudFormation stack queries.
+
+## How Thunder Tags Deployments
+
+- [x] **DONE**: Thunder uses a state-based approach rather than traditional AWS resource tags for discovery.
+
+### State Storage
+When you deploy a Thunder service, it automatically stores its deployment state in a centralized S3 bucket named `thunder-discovery-<account>-<region>`.
+
+### Key Structure
+Metadata files are stored with the following hierarchy:
+`apps/<application>/<environment>/<service>/metadata.json`
+
+### Metadata Content
+The `metadata.json` file contains a standardized set of properties that align with the service's `CfnOutput` names:
+```json
+{
+  "id": "myapp-prod-web",
+  "application": "myapp",
+  "service": "web",
+  "environment": "prod",
+  "region": "us-east-1",
+  "timestamp": "2026-03-04T12:00:00.000Z",
+  "type": "Nuxt",
+  "DistributionId": "E1234567890",
+  "DistributionUrl": "https://d123.cloudfront.net",
+  "Route53Domain": "https://myapp.com",
+  "CodePipelineName": "myapp-prod-web-pipeline"
+}
+```
+
+## How the CLI/Console Discovers Apps
+
+1.  **Bucket Resolution**: The tool determines the discovery bucket name based on the current AWS account and region.
+2.  **S3 Scanning**: It lists the objects in the bucket under the `apps/` prefix.
+3.  **Metadata Parsing**: It reads the `metadata.json` files to discover:
+    - All deployed Thunder apps.
+    - Their environments/stages.
+    - Their individual services and associated resource IDs/URLs.
+4.  **Automatic Discovery**: Because the `DiscoveryConstruct` is embedded in every Thunder stack, new services and updates are automatically reflected in S3 upon successful deployment.
+
+## Implementation Details
+
+- [x] **DONE**: **`DiscoveryConstruct`**: A shared construct located in `lib/constructs/discovery.ts`.
+- [x] **DONE**: **`BucketDeployment`**: Uses `aws-s3-deployment` to upload `Source.jsonData` during the CDK deployment phase.
+- [x] **DONE**: **Standardization**: Metadata field names are strictly aligned with `CfnOutput` logical IDs (e.g., `DistributionId`, `ServiceUrl`).
+- [x] **DONE**: Each deployment stores its metadata in a centralized S3 bucket (`thunder-discovery-<account>-<region>`). 
+
+Metadata includes:
+- [x] App identity (application, service, environment)
+- [x] Resource ARNs, IDs and URLs (Aligned with `CfnOutput` names)
+- [x] Deployment timestamps
+- [x] Framework-specific metadata
+- [x] Route53 domain integration
+
+
+## ISSUES:
+
+7:11:10 PM | CREATE_FAILED        | Custom::CDKBucketDeployment               | Discovery/StoreMet...omResource/Default
+Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'sync', '/tmp/tmpxgahyp87/contents', 's3://thunder-discovery-047719662375-us-east
+-1/apps/nuxt3/dev/fargate']' returned non-zero exit status 1. (RequestId: afc6bb52-d373-4b97-9a7d-36d0ab9b9425)
+7:11:10 PM | ROLLBACK_IN_PROGRESS | AWS::CloudFormation::Stack                | nuxt3-fargate-dev-stack
+The following resource(s) failed to create: [DiscoveryStoreMetadataCustomResource5F6695DB, FargateFargateService7449B65B]. Rollback requested by user.
+7:11:10 PM | ROLLBACK_IN_PROGRESS | AWS::CloudFormation::Stack                | nuxt3-fargate-dev-stack
+The following resource(s) failed to create: [DiscoveryStoreMetadataCustomResource5F6695DB, FargateFargateService7449B65B]. Rollback requested by user.
+7:11:37 PM | DELETE_FAILED        | Custom::CDKBucketDeployment               | Discovery/StoreMet...omResource/Default
+Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'rm', 's3://thunder-discovery-047719662375-us-east-1/apps/nuxt3/dev/fargate', '--
+recursive']' returned non-zero exit status 1. (RequestId: f9383113-0976-4fe3-af60-bcefbf14d514)
+
+❌  nuxt3-fargate-dev-stack failed: ToolkitError: The stack named nuxt3-fargate-dev-stack failed creation, it may need to be manually deleted from the AWS console: ROLLBACK_FAILED (The following resource(s) failed to delete: [DiscoveryStoreMetadataCustomResource5F6695DB]. ): Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'sync', '/tmp/tmpxgahyp87/contents', 's3://thunder-discovery-047719662375-us-east-1/apps/nuxt3/dev/fargate']' returned non-zero exit status 1. (RequestId: afc6bb52-d373-4b97-9a7d-36d0ab9b9425), Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'rm', 's3://thunder-discovery-047719662375-us-east-1/apps/nuxt3/dev/fargate', '--recursive']' returned non-zero exit status 1. (RequestId: f9383113-0976-4fe3-af60-bcefbf14d514)
+
+The following resource(s) failed to delete: [DiscoveryStoreMetadataCustomResource5F6695DB].
+Received response status [FAILED] from custom resource. Message returned: Command '['/opt/awscli/aws', 's3', 'rm', 's3://thunder-discovery-047719662375-us-east-1/apps/nuxt3/dev/fargate', '--recursive']' returned non-zero exit status 1. (RequestId: f9383113-0976-4fe3-af60-bcefbf14d514)

package/.agents/PRD.md

@@ -0,0 +1,537 @@
+# Thunder - CDK Library for AWS Deployments
+
+## Executive Summary
+
+Thunder (`@thunder-so/thunder`) is an AWS CDK library for deploying modern web applications. It provides opinionated, production-ready infrastructure patterns for one-line deployment of common web application architectures.
+
+**One library to rule them all**: Static SPAs, Lambda Functions, Containers (Fargate/EC2), and Full-stack Frameworks (Nuxt/Astro).
+
+---
+
+## Project Overview
+
+Thunder provides high-level abstractions over AWS CDK, enabling developers to deploy complete infrastructure stacks with minimal configuration. The library covers the full spectrum of web deployment patterns from static sites to full-stack serverless applications.
+
+---
+
+## Stacks
+
+| Stack | Description | Use Cases | Status |
+|-----------|-------------|-----------|--------|
+| `Static` | S3 + CloudFront for static SPAs | React, Vue, Svelte, Next.js (SSG), Gatsby | **DONE** |
+| `Lambda` | Lambda + API Gateway for serverless | API endpoints, background jobs, microservices | **DONE** |
+| `Fargate` | ECS Fargate + ALB for containers | Long-running containers, microservices | **DONE** |
+| `EC2` | EC2 instance with Docker + Elastic IP | Single containers, dev environments | **DONE** |
+| `Template` | Coolify One-Click Service Template on EC2 | Pre-built apps (n8n, Plausible, etc.) | **DONE** |
+| `Nuxt` | Full-stack Nuxt.js (Lambda + S3 + CloudFront) | SSR Nuxt applications | **DONE** |
+| `Astro` | Full-stack Astro SSR (with Edge fallback) | SSR Astro applications | **DONE** |
+| `VPC` | Shared VPC with public/private subnets | Shared networking infrastructure | **DONE** |
+
+---
+
+## Stack Details
+
+### 1. Static Stack
+**Purpose**: Static SPA hosting
+**Resources**: S3 + CloudFront (OAC) + Route53 + Lambda@Edge
+**Key Features**:
+- Zero-downtime deployment without bucket pruning
+- Origin Access Control (OAC) for secure S3 access
+- Lambda@Edge for redirects/rewrites
+- Custom security headers policy
+- CI/CD pipeline support
+
+**Entry Point**: `bin/static.ts`
+**Stack File**: `stacks/StaticStack.ts`
+**Constructs**:
+- `HostingConstruct` (S3 + CloudFront + Route53)
+- `DeployConstruct` (direct local deployment)
+- `PipelineConstruct` (CodePipeline CI/CD)
+
+### 2. Lambda Stack
+**Purpose**: Serverless functions
+**Resources**: Lambda (Zip or Container) + API Gateway v2 + ECR + Route53
+**Key Features**:
+- Bun runtime support via Lambda Layer
+- Keep-warm scheduling (EventBridge)
+- Provisioned concurrency support
+- X-Ray tracing
+- VPC integration
+
+**Entry Point**: `bin/lambda.ts`
+**Stack File**: `stacks/LambdaStack.ts`
+**Constructs**:
+- `FunctionsConstruct` (Lambda + API Gateway)
+- `PipelineConstruct` (ECR-based CI/CD)
+
+### 3. Fargate Stack
+**Purpose**: Container orchestration
+**Resources**: ECS Fargate + ALB + VPC + ECR + Route53
+**Key Features**:
+- ARM64 or X86_64 architecture support
+- Auto-scaling capabilities
+- Health checks with customizable paths
+- Circuit breaker deployments
+- Nixpacks integration for Dockerfile generation
+- Rolling updates
+
+**Entry Point**: `bin/fargate.ts`
+**Stack File**: `stacks/FargateStack.ts`
+**Constructs**:
+- `ServiceConstruct` (ECS service + ALB + VPC)
+- `PipelineConstruct` (ECR-based CI/CD)
+
+### 4. EC2 Stack
+**Purpose**: Single EC2 container hosting
+**Resources**: EC2 + Elastic IP + Route53 + CloudWatch Agent
+**Key Features**:
+- Docker-on-EC2 deployment
+- Elastic IP assignment
+- Let's Encrypt SSL (via acmeEmail)
+- SSH access with authorized keys
+- CloudWatch monitoring
+- Nixpacks support
+
+**Entry Point**: `bin/ec2.ts`
+**Stack File**: `stacks/Ec2Stack.ts`
+**Constructs**:
+- `ComputeConstruct` (EC2 instance + Docker)
+- `PipelineConstruct` (CI/CD)
+- `Ec2Instance` (instance provisioning)
+- `UserData` (EC2 bootstrap scripts)
+- `CloudwatchAgent` (monitoring)
+
+### 5. Template Stack
+**Purpose**: Coolify one-click templates
+**Resources**: EC2 + Docker Compose + Traefik
+**Key Features**:
+- Fetches templates from Coolify GitHub repo
+- Hydrates SERVICE_FQDN, SERVICE_PASSWORD variables
+- Traefik reverse proxy with Let's Encrypt
+- Multi-service Docker Compose support
+
+**Entry Point**: `bin/template.ts`
+**Stack File**: `stacks/TemplateStack.ts`
+**Constructs**:
+- `TemplateConstruct` (template deployment)
+- `TemplateFetcher` (fetches from GitHub)
+- `TemplateHydrator` (variable substitution)
+
+### 6. Nuxt Stack
+**Purpose**: Full-stack Nuxt.js deployment
+**Resources**: Lambda (SSR) + S3 (Assets) + CloudFront (Dual Origin) + API Gateway
+**Key Features**:
+- Nitro preset optimized for AWS Lambda
+- Static assets served from S3
+- SSR via Lambda function
+- API routes support
+- Unified CloudFront distribution
+
+**Entry Point**: `bin/nuxt.ts`
+**Stack File**: `stacks/NuxtStack.ts`
+**Constructs**:
+- `NuxtConstruct` (SSR server + client)
+- `ServerConstruct` (Lambda SSR)
+- `ClientConstruct` (S3 + CloudFront)
+- `FrameworkPipeline` (CI/CD)
+
+### 7. Astro Stack
+**Purpose**: Full-stack Astro SSR deployment
+**Resources**: Lambda (SSR) + S3 + CloudFront + Edge Function fallback
+**Key Features**:
+- Same architecture as Nuxt (Lambda + S3 + CloudFront)
+- Lambda@Edge fallback for 404/403 handling
+- Edge-optimized for global distribution
+- Astro-specific optimizations
+
+**Entry Point**: `bin/astro.ts`
+**Stack File**: `stacks/AstroStack.ts`
+**Constructs**:
+- `AstroConstruct` (SSR server + client)
+- `ClientConstruct` (S3 + CloudFront + Edge fallback)
+- `FrameworkPipeline` (CI/CD)
+
+### 8. VPC Stack
+**Purpose**: Shared VPC infrastructure
+**Resources**: VPC with public/private subnets, NAT gateways
+**Key Features**:
+- Shared networking for multiple services
+- Implements IVpcLink interface
+- Configurable CIDR, AZs, NAT gateways
+- Can be linked to other stacks
+
+**Entry Point**: `bin/vpc.ts`
+**Stack File**: `stacks/VpcStack.ts`
+**Constructs**:
+- `VPC` (shared VPC construct)
+
+---
+
+## Architecture
+
+### Project Structure
+
+```
+@thunder-so/thunder/
+├── bin/                          # CDK entry points
+│   ├── static.ts                 # Static SPA deployment
+│   ├── lambda.ts                 # Lambda deployment
+│   ├── fargate.ts                # Fargate deployment
+│   ├── ec2.ts                    # EC2 deployment
+│   ├── template.ts               # Coolify template deployment
+│   ├── nuxt.ts                   # Nuxt deployment
+│   ├── astro.ts                  # Astro deployment
+│   └── vpc.ts                    # VPC deployment
+│
+├── cli/                          # Thunder CLI
+│   ├── th.mjs                    # Main CLI entry
+│   ├── th-init.mjs               # Init command
+│   ├── th-deploy.mjs             # Deploy command
+│   └── th-destroy.mjs            # Destroy command
+│
+├── lib/                          # CDK constructs
+│   ├── astro/                    # Astro framework support
+│   │   ├── index.ts              # AstroConstruct
+│   │   └── client.ts             # Astro client (S3 + CloudFront + Edge)
+│   │
+│   ├── constructs/               # Shared constructs
+│   │   ├── vpc.ts                # VPC construct
+│   │   └── discovery.ts          # SST-style metadata discovery
+│   │
+│   ├── ec2/                      # EC2 implementation
+│   │   ├── compute.ts            # EC2 compute
+│   │   ├── pipeline.ts           # EC2 pipeline
+│   │   └── constructs/
+│   │       ├── cloudwatch-agent.ts
+│   │       ├── ec2-instance.ts
+│   │       └── user-data.ts
+│   │
+│   ├── fargate/                  # Fargate implementation
+│   │   ├── service.ts            # ECS Fargate service
+│   │   └── pipeline.ts           # Fargate pipeline
+│   │
+│   ├── frameworks/               # Framework pipeline
+│   │   └── pipeline.ts           # Shared framework CI/CD
+│   │
+│   ├── lambda/                   # Lambda implementation
+│   │   ├── functions.ts          # Lambda + API Gateway
+│   │   └── pipeline.ts           # Lambda pipeline
+│   │
+│   ├── nuxt/                     # Nuxt implementation
+│   │   ├── index.ts              # NuxtConstruct
+│   │   ├── server.ts             # Nuxt server (Lambda)
+│   │   └── client.ts             # Nuxt client (S3 + CloudFront)
+│   │
+│   ├── static/                   # Static implementation
+│   │   ├── hosting.ts            # S3 + CloudFront + Route53
+│   │   ├── pipeline.ts           # Static CI/CD
+│   │   └── deploy.ts             # Direct S3 deployment
+│   │
+│   ├── template/                 # Coolify template implementation
+│   │   ├── index.ts              # TemplateConstruct
+│   │   ├── template/
+│   │   │   ├── fetch.ts          # Fetch from GitHub
+│   │   │   └── hydrate.ts        # Variable hydration
+│   │   └── constructs/
+│   │       ├── cloudwatch-agent.ts
+│   │       ├── ec2-instance.ts
+│   │       └── user-data.ts
+│   │
+│   └── utils/                    # Shared utilities
+│       ├── index.ts              # Main exports
+│       ├── naming.ts             # Resource naming
+│       ├── paths.ts              # Path sanitization
+│       ├── nixpacks.ts           # Nixpacks integration
+│       └── vpc-link.ts           # VPC linking
+│
+├── stacks/                       # Stack definitions
+│   ├── StaticStack.ts
+│   ├── LambdaStack.ts
+│   ├── FargateStack.ts
+│   ├── Ec2Stack.ts
+│   ├── TemplateStack.ts
+│   ├── NuxtStack.ts
+│   ├── AstroStack.ts
+│   └── VpcStack.ts
+│
+├── types/                        # TypeScript interfaces
+│   ├── AppProps.ts               # Base props
+│   ├── StaticProps.ts
+│   ├── LambdaProps.ts
+│   ├── FargateProps.ts
+│   ├── Ec2Props.ts
+│   ├── TemplateProps.ts
+│   ├── NuxtProps.ts
+│   ├── VpcProps.ts
+│   ├── CloudFrontProps.ts
+│   └── PipelineProps.ts
+│
+├── .agents/                      # Documentation
+│   ├── PRD.md                    # This file
+│   ├── CLI.md                    # CLI scope
+│   ├── SKILLS.md                 # Claude skills plan
+│   └── METADATA.md               # Discovery mechanism
+│
+├── index.ts                      # Main exports
+└── package.json
+```
+---
+
+## Shared Infrastructure Patterns
+
+### VPC Link Pattern
+All compute stacks (Lambda, Fargate, EC2, Template) support a `link` pattern for VPC integration:
+
+- Implemented via `resolveVpc()` utility
+- Accepts `IVpc` directly or `IVpcLink` implementing construct
+- Provides consistent VPC connectivity across stacks
+
+```typescript
+// Explicit VPC passing
+const vpc = new VpcStack(this, 'MyVPC', { ... });
+
+new FargateStack(this, 'MyService', {
+  vpc: vpc,
+  // ...
+});
+
+// Via link property
+new FargateStack(this, 'MyService', {
+  link: vpc,  // IVpcLink interface
+  // ...
+});
+```
+
+### Resource Naming
+**Pattern**: 23-character prefix ensuring uniqueness and AWS name limits
+- **Format**: `${app.substring(0,7)}-${service.substring(0,7)}-${env.substring(0,7)}`
+- **Utility**: `getResourceIdPrefix()` in `lib/utils/naming.ts`
+- **Example**: `myapp-t-web-dev` (app="myapplication", service="webfrontend", env="development")
+
+### Path Sanitization
+**Purpose**: Ensure valid Unix directory paths for Docker builds and deployments
+- **Utility**: `sanitizePath()` in `lib/utils/paths.ts`
+- **Regex**: Removes invalid characters, normalizes slashes
+- **Use Case**: User-provided rootDir/outputDir sanitization
+
+---
+
+## Common Features Across Stacks
+
+### 1. Monorepo Support
+- **Path-based filters** in CodeBuild webhooks
+- **rootDir/outputDir** resolution for monorepo packages
+- **Context directory** support for taking source from any path
+
+### 2. CI/CD Pipeline Integration
+Optional AWS CodePipeline with GitHub support:
+- Triggered by `accessTokenSecretArn` + `sourceProps` + `buildProps`
+- Path-based filtering for monorepos
+- ECR integration for container stacks
+- S3 deployment for static stacks
+
+### 3. Nixpacks Integration
+Automatic Dockerfile generation:
+- **Utility**: `generateNixpacksDockerfile()` in `lib/utils/nixpacks.ts`
+- **Supported**: Fargate, EC2, Template stacks
+- **Build system**: Detects language and generates optimized Dockerfile
+
+### 4. Framework Fallbacks
+Astro-specific Edge function for 404/403 handling:
+- Implemented in `lib/astro/client.ts`
+- CloudFront origin failover to S3 for SPA routing
+
+### 5. Bun Support
+Bun runtime for Lambda:
+- Lambda Layer integration
+- Custom runtime configuration for CodeBuild
+
+---
+
+## Thunder CLI
+
+**Location**: `cli/th.mjs`
+
+The Thunder CLI provides context-aware infrastructure management:
+
+### Commands
+
+| Command | Description | Status |
+|---------|-------------|--------|
+| `th init` | Scaffold new project/service | [ ] **TODO** |
+| `th deploy` | Deploy stacks to AWS | [ ] **TODO** |
+| `th destroy` | Remove resources from AWS | [ ] **TODO** |
+
+### CLI Architecture
+- **Runtime**: Node.js
+- **Core Libraries**: `commander`, `inquirer`, `chalk`, `ora`, `shelljs`
+- **Context Resolution**: Reads `bin/*.ts` files
+- **Environment**: Injects CDK context via environment variables
+
+### Context Resolution
+1. CLI scans `bin/` directory for stack entry points
+2. Executes via `ts-node` or `tsx`
+3. Injects context: app, env, service, account, region
+4. Delegates to CDK for actual deployment
+
+**Status**: Basic CLI structure done, full implementation pending
+
+---
+
+## CLI Mandates
+
+1. **Context-Awareness**: [x] **DONE** - Auto-detects environment from repository
+2. **Zero-Config Defaults**: [x] **DONE** - Sensible defaults for AWS regions, accounts, resource sizing
+3. **Local Dev Parity**: [ ] **TODO** - Local development loop (future scope)
+4. **SST-Style Metadata**: [x] **DONE** - Discovery bucket for deployment state
+
+---
+
+## Future Extensibility
+
+### Framework Support
+
+The library should support additional Vite + Nitro-based frameworks:
+- [ ] TanStack Start
+- [ ] Angular AnalogJS
+- [ ] SvelteKit
+- [ ] React Router v7
+- [ ] SolidStart
+
+Each framework construct will have preset configurations optimized for that framework.
+
+### Console UI
+
+Future scope: SST-style Console UI for:
+- Resource visualization
+- Log streaming
+- Real-time monitoring
+- Deployment history
+
+**Prerequisite**: Metadata Discovery system (already implemented)
+
+---
+
+## Status Overview
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| **Static Stack** | [x] **DONE** | Production-ready |
+| **Lambda Stack** | [x] **DONE** | Production-ready |
+| **Fargate Stack** | [x] **DONE** | Production-ready |
+| **EC2 Stack** | [x] **DONE** | Production-ready |
+| **Template Stack** | [x] **DONE** | Production-ready |
+| **Nuxt Stack** | [x] **DONE** | Production-ready |
+| **Astro Stack** | [x] **DONE** | Production-ready |
+| **VPC Stack** | [x] **DONE** | Production-ready |
+| **VPC Link Pattern** | [x] **DONE** | All compute stacks |
+| **Monorepo Support** | [x] **DONE** | Path filters, rootDir |
+| **Nixpacks Integration** | [x] **DONE** | Auto Dockerfile gen |
+| **Metadata Discovery** | [x] **DONE** | SST-style in S3 |
+| **CI/CD Pipelines** | [x] **DONE** | CodePipeline + GitHub |
+| **Bun Support** | [x] **DONE** | Lambda layer |
+| **CLI Framework** | [x] **DONE** | Basic structure |
+| **th init Command** | [ ] **TODO** | Scaffold projects |
+| **th deploy Command** | [ ] **TODO** | Deploy stacks |
+| **th destroy Command** | [ ] **TODO** | Remove resources |
+| **Console UI** | [ ] **TODO** | Future scope |
+| **Additional Frameworks** | [ ] **TODO** | TanStack, SvelteKit, etc. |
+| **Claude Skills** | [ ] **TODO** | See SKILLS.md |
+
+---
+
+## Supported Frameworks & Patterns
+
+### Static Sites
+- **Vite-based**: React, Vue, Svelte, Solid
+- **Next.js**: Static Site Generation (SSG)
+- **Astro**: Static Site Generation
+- **Gatsby**: Static site generator
+- **Other**: Any framework outputting to a directory
+
+### Serverless
+- **Node.js**: Lambda functions
+- **Bun**: Via Lambda Layer
+- **Containers**: Container-based Lambda
+- **Runtimes**: Node.js 18.x, 20.x
+
+### Containers
+- **ECS Fargate**: Serverless containers with ALB
+- **EC2 Docker**: Single-container on EC2
+- **Architectures**: ARM64, X86_64
+- **Orchestration**: Supports docker-compose (Template)
+
+### Full-Stack SSR
+- **Nuxt.js**: Universal Vue applications
+- **Astro**: Content-focused websites with SSR
+- **Extensible**: TanStack Start, SvelteKit, AnalogJS (planned)
+
+---
+
+## Key Design Principles
+
+1. **One-Line Deployment**: Minimal configuration for common patterns
+2. **Convention over Configuration**: Sensible defaults, customization when needed
+3. **Framework Agnostic**: Works with any framework, optimized for popular ones
+4. **Production Ready**: Security, monitoring, CI/CD included
+5. **Cost Optimized**: Uses most cost-effective AWS services for each pattern
+6. **Developer Experience**: Fast feedback loops, clear errors, helpful defaults
+7. **Composable**: Stacks can be combined for complex architectures
+
+---
+
+## Quick Start
+
+### Installation
+```bash
+bun add @thunder-so/thunder -d
+```
+
+### Basic Usage
+```typescript
+// stack/dev.ts
+import { Cdk, Static, type StaticProps } from '@thunder-so/thunder';
+
+const myApp: StaticProps = {
+  env: { 
+    account: '123456789012', 
+    region: 'us-east-1' 
+  },
+  application: 'myapp',
+  service: 'web',
+  environment: 'prod',
+  rootDir: '.',
+  outputDir: 'dist',
+};
+
+new Static(
+  new Cdk.App(),
+  `${myApp.application}-${myApp.service}-${myApp.environment}-stack`,
+  myApp
+);
+```
+
+### Deployment
+```bash
+npx cdk deploy --app "npx tsx stack/dev.ts" --profile default
+```
+
+---
+
+## Documentation
+
+- **This PRD**: Project overview and architecture
+- **CLI.md**: CLI command reference and scope
+- **SKILLS.md**: Claude Code skills implementation plan
+- **METADATA.md**: Discovery/metadata mechanism details
+
+---
+
+## License
+
+Apache-2.0
+
+---
+
+**Last Updated**: 2026-03-08
+**Status**: Production-ready stacks, CLI implementation in progress