diff --git a/docs/.vale/styles/config/vocabularies/Suga/accept.txt b/docs/.vale/styles/config/vocabularies/Suga/accept.txt
index 23a8171c..55688627 100644
--- a/docs/.vale/styles/config/vocabularies/Suga/accept.txt
+++ b/docs/.vale/styles/config/vocabularies/Suga/accept.txt
@@ -12,6 +12,11 @@ allowlisting
 cdktf
 Presigned
 presigned
+Fargate
+Linode
+Vultr
+booleans
+CDNs
 
 # Defaults from mintlify
 Mintlify
diff --git a/docs/docs.json b/docs/docs.json
index 83802f81..391c3212 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -21,6 +21,10 @@
             "group": "Getting Started",
             "pages": ["introduction", "installation", "quickstart"]
           },
+          {
+            "group": "Core Concepts",
+            "pages": ["projects", "platforms"]
+          },
           {
             "group": "Guides",
             "pages": [
@@ -31,6 +35,10 @@
               "guides/local-database-setup",
               "guides/aws/environment-management"
             ]
+          },
+          {
+            "group": "Resources",
+            "pages": ["registry"]
           }
         ]
       },
diff --git a/docs/images/blueprint-property-editor.png b/docs/images/blueprint-property-editor.png
new file mode 100644
index 00000000..aa6ceb15
Binary files /dev/null and b/docs/images/blueprint-property-editor.png differ
diff --git a/docs/images/blueprint-vars-as-properties.png b/docs/images/blueprint-vars-as-properties.png
new file mode 100644
index 00000000..9d313d5c
Binary files /dev/null and b/docs/images/blueprint-vars-as-properties.png differ
diff --git a/docs/images/platform-vars.png b/docs/images/platform-vars.png
new file mode 100644
index 00000000..08d2d25a
Binary files /dev/null and b/docs/images/platform-vars.png differ
diff --git a/docs/images/project-editor-poster.png b/docs/images/project-editor-poster.png
new file mode 100644
index 00000000..b3eab025
Binary files /dev/null and b/docs/images/project-editor-poster.png differ
diff --git a/docs/introduction.mdx b/docs/introduction.mdx
index 0ca34eb3..0153cb8f 100644
--- a/docs/introduction.mdx
+++ b/docs/introduction.mdx
@@ -4,8 +4,9 @@ sidebarTitle: "Introduction"
 description: "Cloud development with visual design, local testing, and multi-cloud deployment"
 ---
 
-Suga makes cloud development simple by combining visual infrastructure design with automatic Terraform generation for AWS or GCP today (Azure coming soon).
-Build applications with any framework, test locally with emulated cloud resources, and deploy anywhere with production-ready Terraform.
+Suga bridges the gap between developer productivity and enterprise control. It delivers the instant deployment experience developers love while giving platform teams complete governance over infrastructure, security, and compliance.
+
+No more choosing between developer velocity and operational control - Suga's platform system lets enterprise teams deliver world-class developer experiences without sacrificing governance.
 ```mermaid
 graph LR
 HardenedInfra["Hardened Building Blocks"] ==> AppDesigner["Infrastructure Designer"]
@@ -26,7 +27,9 @@ class HardenedInfra,AppDesigner,Code,Test,Generate,Deploy nitricGreen
 
 ## What is Suga?
 
-Suga is a cloud development platform that adds infrastructure capabilities to your applications. You can add Suga to your existing app with minimal changes, or create a new project from scratch using templates.
+Suga is a cloud development platform that solves the enterprise developer experience challenge. It combines visual infrastructure design with platform-driven governance, enabling developers to deploy applications instantly while platform teams maintain complete control over security, compliance, and infrastructure standards.
+
+The traditional trade-off between developer velocity and enterprise control is eliminated through Suga's distributed platform system - platform engineers create reusable blueprints that deliver seamless deployment experiences while enforcing organizational requirements.
 
 <div className="relative h-96 overflow-hidden">
   <video 
@@ -36,7 +39,7 @@ Suga is a cloud development platform that adds infrastructure capabilities to yo
     muted 
     playsInline
     preload="metadata"
-    poster="/images/project-editor-poster.jpg"
+    poster="/images/project-editor-poster.png"
     aria-label="Demo of the Suga visual project editor showing drag-and-drop infrastructure design"
   >
     <source src="/images/project-editor.webm" type="video/webm" />
@@ -47,11 +50,12 @@ Suga is a cloud development platform that adds infrastructure capabilities to yo
 
 Suga provides:
 
-- **Visual infrastructure design** - Design your cloud architecture with drag-and-drop components
+- **Enterprise-grade developer experience** - Visual infrastructure design, automatic scaling, and zero-config cloud deployment with production-ready Terraform
+- **Platform-driven governance** - Security policies, compliance, and architectural standards built into reusable platforms
+- **Visual infrastructure design** - Design cloud architecture with drag-and-drop components that enforce organizational patterns
 - **Framework flexibility** - Works as an add-on to Express, Django, FastAPI, Go HTTP, and other frameworks
-- **Local cloud emulation** - Develop and test with local versions of cloud services (S3, databases, queues)
-- **Multi-cloud deployment** - Generate Terraform for AWS, GCP, or Azure from the same design
-- **Team collaboration** - Infrastructure definition separate from application code
+- **Local cloud emulation** - Develop and test with local versions of cloud services
+- **Multi-cloud deployment** - Generate Terraform for AWS, GCP, or Azure from the same design while maintaining governance
 
 ## How Suga Works
 
diff --git a/docs/platforms.mdx b/docs/platforms.mdx
new file mode 100644
index 00000000..bfe88456
--- /dev/null
+++ b/docs/platforms.mdx
@@ -0,0 +1,230 @@
+---
+title: "Platforms Overview"
+description: "Understanding Suga's platforms and ecosystem"
+---
+
+Platforms in Suga solve a critical challenge: delivering the seamless developer experience of modern deployment platforms while maintaining enterprise control and flexibility. They're blueprints that transform application specifications ([Projects](/projects)) into deployable infrastructure by generating Terraform HCL and providing runtime adapters that translate abstract resource operations into cloud-specific API calls.
+
+Platform teams can create, customize, and govern these distributed packages to provide developers with instant deployments, automatic scaling, and zero-configuration infrastructure, while maintaining full control over security, compliance, and infrastructure standards.
+
+<Card title="Browse Platforms" horizontal icon="globe" href="https://app.addsuga.com/browse/platforms">
+  Explore official and community platforms in the platform browser
+</Card>
+
+## What is a Platform?
+
+A platform is a configuration that maps Suga's abstract resource types (services, buckets, databases, entrypoints, etc.) to specific implementations.
+
+For example, the official Suga AWS platform maps:
+
+- **Services** → AWS Lambda or ECS Fargate
+- **Buckets** → S3 buckets  
+- **Entrypoints** → Amazon CloudFront CDN
+
+It also includes IAM, policies and routing between the resources. Establishing routes between CloudFront and AWS Lambda/Fargate, as well as providing least-privilege access from the application containers to resources like S3 buckets.
+
+This abstraction delivers concrete value: local development with emulated cloud services (no cloud bills or complex setup), application architectures that aren't locked to specific infrastructure choices, and the ability for platform teams to evolve deployment strategies without breaking developer workflows.
+
+Unlike opaque abstractions that hide complexity, Suga's platform system is transparent - you can inspect the generated Terraform, customize platform behavior, and maintain full control over your infrastructure while keeping application logic cleanly separated from deployment concerns.
+
+## Platform Ecosystem
+
+### Official Platforms
+
+The Suga team maintains official platforms for major cloud providers. These are general purpose, production-ready implementations:
+
+- **[AWS Platform](https://app.addsuga.com/platforms/suga/aws)** - Lambda/Fargate services, S3 storage, CloudFront CDN, IAM security
+- **[GCP Platform](https://app.addsuga.com/platforms/suga/gcp)** - Cloud Run services, Cloud Storage, Cloud CDN, Service Account security
+- **Azure Platform** _(coming soon)_ - Container Apps services, Blob Storage, etc.
+
+```yaml title="Example: Using official platforms"
+targets:
+  - suga/aws@1    # Deploy to AWS
+  - suga/gcp@1    # Deploy to GCP
+
+services:
+  api:
+    # Will be deployed as Lambda (AWS) or Cloud Run (GCP)
+    dev:
+      script: npm run dev
+```
+
+### Community Platforms
+
+The platform ecosystem extends far beyond official implementations. Community members and organizations are able to publish platforms for:
+
+- **Alternative cloud providers** - Azure, DigitalOcean, Linode, Vultr
+- **Specialized deployments** - Kubernetes, Docker Swarm, on-premises infrastructure  
+- **Development environments** - Local testing, CI/CD pipelines, staging environments
+- **Custom configurations** - Organization-specific security policies, compliance requirements
+
+<Info>
+Platform names follow the format `team/platform@version` (e.g. `acme-corp/azure@2`).
+
+You can discover available platforms through the [Suga platform registry](https://app.addsuga.com/browse/platforms) or by browsing community repositories.
+</Info>
+
+## Platform Components
+
+Platforms operate through two key mechanisms: **Infrastructure Generation** and **Runtime Adaptation**.
+
+### Infrastructure Generation
+
+When you run `suga build`, Suga uses your target platform to transform your [Project](/projects) specification into cloud-specific Terraform HCL (called stacks). This process:
+
+1. **Maps abstract resources** - Takes your high-level resource definitions (services, buckets, databases) and selects appropriate cloud implementations
+2. **Generates Terraform modules** - Creates infrastructure-as-code that provisions actual cloud resources with proper networking, security, and permissions
+3. **Applies platform policies** - Ensures generated infrastructure follows organizational security, compliance, and architectural standards
+
+### Runtime Adaptation  
+
+If you choose to use Suga's client code generation in your applications, Platforms provide runtime adapters that translate those abstract operations into cloud-specific API calls:
+
+```typescript
+import { SugaClient } from "@/suga/client";
+
+const suga = new SugaClient();
+
+// Developer writes platform-agnostic code
+await suga.files.write('file.txt', data)
+
+// Platform runtime adapter translates to:
+// AWS: s3.putObject() call
+// GCP: storage.bucket().file().save() call
+// Local dev: filesystem write
+```
+
+This dual approach unlocks portable code while platform teams control both deployment infrastructure and runtime behavior.
+
+### Resource Blueprints
+
+Ultimately, Suga Platforms map Suga Resources to specific plugins and configuration, called Resource Blueprints. Blueprints specify:
+
+- **Plugin**: The resource plugin to use, which contains Terraform code and optional Runtime Adapter
+- **Properties**: Configuration for the plugin, typically Terraform Module variables
+- **Variables**: Custom values to export as Terraform stack variables
+- **Dependencies**: Other infrastructure that should be deployed before the current resource
+
+### Plugins
+
+Platforms use a modular plugin system where each plugin handles a specific cloud service:
+
+- `suga/aws-lambda` - AWS Lambda functions
+- `suga/aws-s3-bucket` - S3 storage buckets
+- `suga/gcp-cloudrun` - Google Cloud Run containers
+- `suga/neon-db` - Neon PostgreSQL databases
+
+#### Properties
+
+Properties are key-value pairs that get passed directly as input variables to the underlying Terraform modules. They configure how the cloud resources should be deployed and behave. The visual editor provides an intuitive interface for editing blueprint properties:
+
+![Blueprint Property Editor](/images/blueprint-property-editor.png)
+
+```yaml title="Platform blueprint with properties"
+entrypoints:
+  default:
+    plugin: "suga/aws-cloudfront"
+    properties:
+      custom_domain: "api.example.com"
+      waf_enabled: true
+      cache_behavior: "optimized"
+```
+
+Properties support several value types:
+
+- **Static values** - Strings, numbers, booleans, objects, and arrays
+- **Variable references** - `${var.domain}` references platform variables
+- **Self references** - `${self.waf_enabled}` references blueprint-specific variables  
+- **Infrastructure references** - `${infra.vpc.id}` references other infrastructure outputs
+
+When Suga generates Terraform code, properties get resolved and passed to the module:
+
+```hcl title="Generated Terraform module call"
+module "cloudfront_main" {
+  source = "./modules/aws-cloudfront"
+  
+  custom_domain    = "api.example.com"
+  waf_enabled      = true
+  cache_behavior   = "optimized"
+}
+```
+
+This allows platforms to expose the full configuration surface of underlying cloud services while maintaining clean, declarative definitions.
+
+### Variables
+
+Variables provide a way to defer configuration values until deployment time, making platforms flexible and reusable. Suga supports two types of variables that become Terraform stack variables:
+
+#### Platform Variables
+
+Platform variables are defined at the top level and can be referenced by any blueprint in the platform:
+
+![Platform Variables](/images/platform-vars.png)
+
+#### Blueprint Variables
+
+Blueprint variables are specific to individual resource blueprints, allowing fine-grained customization. The visual editor shows how blueprint variables can be used as property values:
+
+![Blueprint Variables as Properties](/images/blueprint-vars-as-properties.png)
+
+#### Variable Resolution
+
+When you run `suga build`, variables become Terraform stack variables that can be provided at deployment time:
+
+```hcl title="Conceptual Example of Stack Variables"
+variable "domain" {
+  type        = string
+  description = "Custom domain for the application"
+  default     = null
+}
+
+variable "entrypoints_default_enable_waf" {
+  type        = bool
+  description = "Enable AWS WAF protection"
+  default     = false
+}
+```
+
+Variables can be provided during Terraform deployment:
+
+```bash title="Providing variables at deploy time"
+# Via command line
+terraform apply -var="domain=api.example.com" -var="entrypoints_default_enable_waf=true"
+
+# Via terraform.tfvars file
+echo 'domain = "api.example.com"' > terraform.tfvars
+echo 'entrypoints_default_enable_waf = true' >> terraform.tfvars
+terraform apply
+```
+
+#### Multi-Environment Deployments
+
+Variables work seamlessly with [Terraform workspaces](https://developer.hashicorp.com/terraform/language/state/workspaces) to support deployment to multiple environments using different configurations:
+
+```bash title="Environment-specific deployments"
+# Development environment
+terraform workspace select dev
+terraform apply -var-file="environments/dev.tfvars"
+
+# Production environment  
+terraform workspace select prod
+terraform apply -var-file="environments/prod.tfvars"
+```
+
+```hcl title="environments/dev.tfvars"
+domain = "dev-api.example.com"
+services_default_memory = 512
+services_default_storage = 1024
+entrypoints_default_enable_waf = false
+```
+
+```hcl title="environments/prod.tfvars"
+domain = "api.example.com"
+services_default_memory = 2048
+services_default_storage = 4096
+entrypoints_default_enable_waf = true
+```
+
+This pattern allows the same platform to scale resources appropriately across environments - smaller, cost-effective configurations for development and staging, while providing production-grade resources with enhanced security features for live deployments.
+
+Platform authors can expose environment-specific variables like memory allocation, storage capacity, security settings, and performance configurations, ensuring each environment gets the right balance of cost and capability.
\ No newline at end of file
diff --git a/docs/projects.mdx b/docs/projects.mdx
new file mode 100644
index 00000000..b8b753e4
--- /dev/null
+++ b/docs/projects.mdx
@@ -0,0 +1,251 @@
+---
+title: "Projects Overview"
+description: "Understanding Suga projects - the application specifications that define your cloud architecture"
+---
+
+Projects in Suga are application specifications that define your cloud architecture using abstract resource types. They're declarative YAML configurations that describe what your application needs - services, storage, databases, and networking - without being tied to specific cloud implementations.
+
+## What is a Project?
+
+A Suga project is defined by a `suga.yaml` file that describes your application's infrastructure requirements using cloud-agnostic resource types. When combined with a [Platform](/platforms), this specification gets transformed into deployable cloud infrastructure.
+
+<Tabs>
+  <Tab title="Suga Project Editor" icon="monitor-cog">
+
+    <div className="relative h-96 overflow-hidden">
+      <video
+        className="w-full h-full object-cover object-top"
+        autoPlay
+        loop
+        muted
+        playsInline
+        preload="metadata"
+        poster="/images/project-editor-poster.png"
+        aria-label="Demo of the Suga visual project editor showing drag-and-drop infrastructure design"
+      >
+        <source src="/images/project-editor.webm" type="video/webm" />
+        Your browser does not support the video tag.
+      </video>
+      <div className="absolute bottom-0 left-0 right-0 h-15 bg-gradient-to-t from-white to-transparent dark:from-gray-900 pointer-events-none"></div>
+    </div>
+
+  </Tab>
+  <Tab title="suga.yaml" icon="file-code-2">
+
+```yaml title="Example suga.yaml"
+targets:
+  - suga/aws@1
+
+name: my-app
+description: An example web application with storage
+
+services:
+  app:
+    dev:
+      script: npm run dev
+    path: ./app
+  frontend:
+    dev:
+      script: npm run dev
+    path: ./frontend
+
+buckets:
+  bucket:
+    access:
+      app:
+        - read
+        - write
+
+entrypoints:
+  api:
+    routes:
+      /:
+        name: frontend
+      /api/:
+        name: app
+```
+
+</Tab>
+</Tabs>
+
+## Project Structure
+
+### Basic Configuration
+
+Every project starts with basic metadata and target platforms:
+
+```yaml title="Basic project configuration"
+name: project-name
+description: Brief description of your application
+
+targets:
+  - suga/aws@1 # Deploy to AWS
+  - suga/gcp@1 # Or deploy to GCP
+```
+
+- **name**: Project identifier (used in Terraform stack and resource naming)
+- **description**: Human-readable project description
+- **targets**: List of platforms this project can use for deployments
+
+### Resource Types
+
+Projects currently offer four main resource types:
+
+- **[Services](#services)** - Application containers that handle business logic
+- **[Buckets](#buckets)** - Cloud storage for files, images, and other assets
+- **[Entrypoints](#entrypoints)** - HTTP routing and CDN configuration to expose your application
+- **[Databases](#databases)** - Persistent data storage with access controls (currently PostgreSQL only)
+
+#### Services
+
+Services are your application containers that handle business logic:
+
+```yaml title="Service definitions"
+services:
+  app:
+    env:
+      EXT_URL: https://somewhere.example.com
+    container:
+      docker:
+        dockerfile: Dockerfile
+        context: .
+    dev:
+      script: npm run dev
+
+  worker:
+    container:
+      image:
+        id: "my-registry/worker:latest"
+```
+
+Services support:
+
+- **Environment variables** for configuration
+- **Container definitions** (Dockerfile or pre-built images)
+- **Development scripts** for local testing with the `suga dev` CLI command
+
+#### Buckets
+
+Buckets provide cloud storage for files, images, and other assets:
+
+```yaml title="Bucket definitions"
+buckets:
+  uploads:
+    access:
+      app:
+        - read
+        - write
+        - delete
+
+  public-assets:
+    content_path: ./build-static
+    access:
+      app:
+        - read
+```
+
+Bucket access permissions define which services can read, write or delete files in the bucket.
+
+Buckets can optionally include a `content_path` which, if provided, is used to seed the bucket with files during deployments. This is useful when you want to deploy static website assets, then route to them via an entrypoint.
+
+#### Entrypoints
+
+Entrypoints expose your application to the internet, typically through CDNs and/or load balancers:
+
+```yaml title="Entrypoint definitions"
+entrypoints:
+  web:
+    routes:
+      /:
+        name: public-assets
+      /api/:
+        name: app
+```
+
+Routes map URL patterns to services or storage buckets.
+
+#### Databases
+
+Databases provide persistent SQL data storage (currently PostgreSQL only):
+
+```yaml title="Database definitions"
+databases:
+  main:
+    access:
+      app:
+        - query
+```
+
+Database access controls which services can access and query the database.
+
+## Project Benefits
+
+### Deployment-Agnostic Architecture
+
+Projects describe _what_ your application needs, not _how_ it's implemented:
+
+- **Portable designs** that work across different cloud providers
+- **Platform independence** - switch from one AWS service to another, or to another cloud like GCP without changing your project
+- **Future-proof architecture** that adapts as platforms evolve
+
+### Developer Experience
+
+Projects enable smooth local development and deployment workflows:
+
+- **Local emulation** - Test with emulated cloud services on your machine using `suga dev`
+- **Hot reloading** - Services restart automatically when code changes
+- **Environment parity** - Same resource relationships locally and in production
+
+### Platform Team Control
+
+Projects maintain separation between application architecture and infrastructure implementation:
+
+- **Governance enforcement** - Platform teams control how resources get deployed
+- **Security policies** - Access patterns and configurations managed at the platform level
+- **Operational consistency** - Standardized deployment and monitoring across teams
+
+## Project Lifecycle
+
+### 1. Design Phase
+
+Define your application architecture using the visual editor `suga edit` or by editing `suga.yaml` directly:
+
+- Drag and drop resources onto the canvas
+- Connect services to storage and databases
+- Configure access permissions and routing
+- Set environment variables and deployment options
+
+### 2. Development Phase
+
+Test your project locally with emulated cloud services:
+
+```bash
+suga dev
+```
+
+- Services run using your `dev.script` commands
+- Storage operations use local filesystem
+- Database connections point to local instances
+- HTTP requests route through local entrypoints
+
+### 3. Build Phase
+
+Generate cloud-specific infrastructure from your project:
+
+```bash
+suga build
+```
+
+- Suga combines your project with the target platform specifications
+- Terraform stacks are generated for your target platform using pre-built modules
+- Resource dependencies and networking get configured automatically
+
+### 4. Deploy Phase
+
+Deploy the generated infrastructure using Terraform:
+
+```bash
+cd .suga/stacks/my-app-aws-*
+terraform init
+terraform apply
+```
\ No newline at end of file
diff --git a/docs/registry.mdx b/docs/registry.mdx
new file mode 100644
index 00000000..649ed441
--- /dev/null
+++ b/docs/registry.mdx
@@ -0,0 +1,4 @@
+---
+title: "Suga Registry"
+url: "https://app.addsuga.com/browse/platforms"
+---
\ No newline at end of file