typekro 0.1.0 → 0.2.1

package/README.md

@@ -6,12 +6,16 @@
 
 [![NPM Version](https://img.shields.io/npm/v/typekro.svg)](https://www.npmjs.com/package/typekro)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/yehudacohen/typekro)](https://github.com/yehudacohen/typekro)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/yehudacohen/typekro/deploy.yml?branch=master)](https://github.com/yehudacohen/typekro/actions)
+[![Coverage](https://codecov.io/gh/yehudacohen/typekro/branch/master/graph/badge.svg)](https://codecov.io/gh/yehudacohen/typekro)
 
-> **Kubernetes infrastructure with TypeScript instead of YAML**
+📚 **[Documentation](https://typekro.run)** • 💬 **[Discord Community](https://discord.gg/kKNSDDjW)** • 🚀 **[Getting Started](https://typekro.run/guide/getting-started)**
+## **TypeKro: Kubernetes with TypeScript**
 
-TypeKro combines the type safety of TypeScript, the GitOps-friendly output of declarative YAML, and the runtime intelligence of **Kubernetes Resource Orchestrator (KRO)** - an open-source project that enables advanced resource orchestration with runtime dependencies and CEL expressions. Write infrastructure in pure TypeScript with full IDE support, then deploy directly to clusters or generate deterministic YAML for GitOps workflows.
+**A control plane aware framework for orchestrating kubernetes resources like a programmer**
 
-> **What is KRO?** [Kubernetes Resource Orchestrator](https://kro.run/) is an open-source project by AWS Labs that enables resources to reference each other's runtime state using CEL expressions. TypeKro works in Direct Mode (no KRO required) for simple deployments, or KRO Mode for advanced orchestration.
+TypeKro combines the type safety of TypeScript, the GitOps-friendly output of declarative YAML, and the runtime intelligence of **Kubernetes Resource Orchestrator (KRO)** - an open-source project that enables advanced resource orchestration with runtime dependencies and CEL expressions. Write infrastructure in pure TypeScript with full IDE support, then deploy directly to clusters or generate deterministic YAML for GitOps workflows.
 
 ## Table of Contents
 
@@ -30,106 +34,127 @@ TypeKro combines the type safety of TypeScript, the GitOps-friendly output of de
 
 ## Quick Start
 
-Here's a complete web application with database in ~30 lines of TypeScript:
+Write Kubernetes infrastructure in pure TypeScript with full IDE support and type safety:
 
 ```typescript
-import { type } from 'arktype';  // Runtime-safe TypeScript schemas with concise syntax
-import { toResourceGraph, simpleDeployment, simpleService, Cel } from 'typekro';
-
-// Define your app's interface
-const WebAppSpec = type({ 
-  name: 'string', 
-  image: 'string', 
-  replicas: 'number' 
-});
-
-const WebAppStatus = type({ 
-  ready: 'boolean', 
-  url: 'string' 
-});
-
-// Create your infrastructure
-const webapp = toResourceGraph(
-  {
-    name: 'my-webapp',
-    apiVersion: 'example.com/v1',
-    kind: 'WebApp',
-    spec: WebAppSpec,
-    status: WebAppStatus
-  },
-  (schema) => ({
-    // Database
-    database: simpleDeployment({
-      name: 'postgres', 
-      image: 'postgres:15',
-      env: { POSTGRES_DB: 'app', POSTGRES_USER: 'user', POSTGRES_PASSWORD: 'secret' }
-    }),
-    
-    // Service (defined first to show cross-references work in any order)
-    service: simpleService({
-      name: schema.spec.name,  // Type-safe schema reference
-      selector: { app: schema.spec.name },
-      ports: [{ port: 80, targetPort: 80 }]
-    }),
-    
-    // Web app that references schema fields
-    app: simpleDeployment({
-      name: schema.spec.name,    // Type-safe schema reference
-      image: schema.spec.image,  // Full IDE autocomplete
-      replicas: schema.spec.replicas,
-      env: { DATABASE_HOST: 'postgres' }
-    })
-  }),
-  (schema, resources) => ({
-    ready: Cel.expr(resources.app.status.readyReplicas, ' > 0'),  // Runtime logic
-    url: Cel.template('http://%s', schema.spec.name)  // String templating with schema reference
-  })
+import { type } from 'arktype';
+import { kubernetesComposition, simple, Cel } from 'typekro';
+
+// Build your infrastructure with full type safety using imperative composition
+const deploymentService = kubernetesComposition(
+  {
+    name: 'deployment-service',
+    apiVersion: 'example.com/v1alpha1',
+    kind: 'DeploymentService',
+    spec: type({ name: 'string', environment: '"dev" | "staging" | "prod"' }),
+    status: type({ ready: 'boolean', url: 'string' })
+  },
+  (spec) => {
+    // Resources auto-register when created - no explicit builders needed!
+    const deployment = simple.Deployment({
+      name: spec.name,                    // ← Full IDE autocomplete
+      image: 'nginx',
+      replicas: spec.environment === 'prod' ? 3 : 1,  // ← Type-safe logic
+      labels: { 
+        app: 'deployment',
+        env: spec.environment             // ← Validated enum
+      },
+      ports: [{ containerPort: 80 }]
+    });
+    
+    const service = simple.Service({
+      name: spec.name,
+      selector: { app: 'deployment' },           // ← Cross-resource reference
+      ports: [{ port: 80, targetPort: 80 }]
+    });
+
+    // Return status with CEL expressions and resource references
+    return {
+      ready: Cel.expr<boolean>(deployment.status.readyReplicas, ' > 0'),
+      url: Cel.template('http://%s.%s.svc', spec.name, spec.environment)
+    };
+  }
 );
 
-// Deploy it directly to your cluster
-const factory = await webapp.factory('direct', { namespace: 'default' });
-await factory.deploy({ name: 'my-app', image: 'nginx', replicas: 3 });
+// Deploy instantly with full type checking
+await deploymentService.factory('direct').deploy({
+  name: 'my-app',           // ← IDE validates this exists
+  environment: 'staging'    // ← Only accepts: "dev" | "staging" | "prod"
+});
 ```
 
 **Key Features Demonstrated:**
-- **Schema References**: `schema.spec.name` becomes runtime CEL expressions
-- **Type Safety**: Full TypeScript validation and autocomplete  
-- **CEL Expressions**: `Cel.template()` for dynamic resource configuration
-- **Direct Deployment**: Resources are created immediately in your cluster
+- **Full IDE autocomplete** - IntelliSense for all properties
+- **Compile-time type checking** - Catch errors before deployment
+- **Runtime validation** - ArkType validates deployment specs
+- **Zero YAML required** - Pure TypeScript infrastructure
+- **Instant deployment** - No kubectl, no YAML files
 
-*Note: You can also generate GitOps-ready YAML with `factory.toYaml()` instead of deploying directly.*
+**Deploy anywhere:** Generate KRO YAML for GitOps with `factory.toYaml()` or integrate with multi-cloud using Alchemy.
 
-**Need advanced features?** Bootstrap a complete runtime environment with Flux CD and KRO:
-```typescript
-import { typeKroRuntimeBootstrap } from 'typekro';
-const bootstrap = typeKroRuntimeBootstrap({ fluxVersion: 'v2.4.0', kroVersion: '0.3.0' });
-await bootstrap.factory('direct').deploy({ namespace: 'flux-system' });
-```
+::: tip Imperative vs Declarative
+This example uses TypeKro's **imperative composition pattern** (`kubernetesComposition`) - the recommended approach for most use cases. For teams preferring explicit resource/status builders, TypeKro also supports a **declarative pattern** (`toResourceGraph`). [Learn more about both patterns →](https://typekro.run/guide/imperative-composition)
+:::
+
+---
+
+## Comparison Grid
+
+| Feature | TypeKro | Pulumi | CDK8s | Helm | Kustomize | Crossplane |
+|---------|---------|---------|--------|------|-----------|------------|
+| **Type Safety** | ✅ Full TypeScript | ✅ Multi-language | ✅ TypeScript | ❌ Templates | ❌ YAML | ❌ YAML |
+| **GitOps Ready** | ✅ Deterministic YAML | ❌ State backend | ✅ YAML output | ✅ Charts | ✅ YAML | ✅ YAML |
+| **Runtime Dependencies** | ✅ KRO + CEL expressions | ❌ Deploy-time only | ❌ Static | ❌ Templates | ❌ Static | ✅ Compositions |
+| **IDE Support** | ✅ Full autocomplete | ✅ Language support | ✅ TypeScript | ❌ Limited | ❌ Limited | ❌ Limited |
+| **Learning Curve** | 🟢 Just TypeScript | 🔴 New concepts | 🟡 TypeScript + K8s | 🔴 Templates | 🔴 YAML hell | 🔴 Complex |
+| **Kubernetes Native** | ✅ Pure K8s resources | ❌ Abstraction layer | ✅ Pure K8s | ✅ K8s resources | ✅ K8s resources | ✅ K8s + CRDs |
+| **Cross-Resource Refs** | ✅ Runtime resolution | ❌ Deploy-time | ❌ Manual | ❌ Manual | ❌ Manual | ✅ Built-in |
+| **Multi-Cloud** | 🟡 Via Alchemy | ✅ Native | ❌ K8s only | ❌ K8s only | ❌ K8s only | ✅ Native |
+| **State Management** | ✅ Stateless | ❌ State backend | ✅ Stateless | ✅ Stateless | ✅ Stateless | ✅ Controller |
+| **CRD Timing** | ✅ Automatic | ❌ Manual | ❌ Manual | ❌ Manual | ❌ Manual | ✅ Built-in |
 
 ---
 
 ## Deployment Flexibility
 
-### Write Once, Deploy Everywhere
+### Deploy the Same Resource Graph using GitOps, Direct Kubernetes API Integration, or using KRO
+
+TypeKro offers deployment flexibility.
+
+> **What is KRO?** [Kubernetes Resource Orchestrator](https://kro.run/) is an open-source project by AWS Labs that enables resources to reference each other's runtime state using CEL expressions. TypeKro works in Direct Mode (no KRO required) for simple deployments, or KRO Mode for advanced orchestration.
 
-TypeKro's core strength is **deployment flexibility**. The same TypeScript code can be deployed in multiple ways without modification:
+ The same TypeScript code can be deployed in multiple ways without modification:
 
 ```typescript
-// Define your infrastructure once  
-const webappGraph = toResourceGraph(
-  {
-    name: 'my-webapp',
-    apiVersion: 'example.com/v1',
-    kind: 'WebApp', 
-    spec: WebAppSpec,
-    status: WebAppStatus
-  },
-  (schema) => ({
-    // ... your resources
-  }),
-  (schema, resources) => ({
-    // ... status builder
-  })
+// Define your infrastructure once with imperative composition
+const webappGraph = kubernetesComposition(
+  {
+    name: 'my-webapp',
+    apiVersion: 'example.com/v1',
+    kind: 'WebApp', 
+    spec: WebAppSpec,
+    status: WebAppStatus
+  },
+  (spec) => {
+    // Resources auto-register when created - no explicit builders needed!
+    const deployment = simple.Deployment({
+      name: spec.name,
+      image: spec.image,
+      replicas: spec.replicas
+    });
+    
+    const service = simple.Service({
+      name: `${spec.name}-service`,
+      selector: { app: spec.name },
+      ports: [{ port: 80, targetPort: 80 }]
+    });
+
+    // Return status with CEL expressions and resource references
+    return {
+      ready: Cel.expr<boolean>(deployment.status.readyReplicas, ' > 0'),
+      url: Cel.template('http://%s-service', spec.name)
+    };
+  }
 );
 
 const spec = { name: 'my-app', image: 'nginx:1.21', replicas: 3 };
@@ -137,21 +162,21 @@ const spec = { name: 'my-app', image: 'nginx:1.21', replicas: 3 };
 // Deploy the SAME code in different ways:
 
 // 1. Generate YAML for GitOps (no cluster interaction)
-const kroFactory = await webappGraph.factory('kro', { namespace: 'dev' });
+const kroFactory = webappGraph.factory('kro', { namespace: 'dev' });
 const yaml = kroFactory.toYaml();
 writeFileSync('k8s/webapp.yaml', yaml);
 
 // 2. Deploy directly to cluster (immediate)
-const directFactory = await webappGraph.factory('direct', { namespace: 'dev' });
+const directFactory = webappGraph.factory('direct', { namespace: 'dev' });
 const directInstance = await directFactory.deploy(spec);
 
 // 3. Integrate with Alchemy for multi-cloud coordination
 await alchemyScope.run(async () => {
-  const factory = await webappGraph.factory('direct', { 
+  const alchemyFactory = webappGraph.factory('direct', { 
     namespace: 'dev',
     alchemyScope: alchemyScope 
   });
-  await factory.deploy(spec);
+  await alchemyFactory.deploy(spec);
 });
 ```
 
@@ -165,7 +190,7 @@ Generate deterministic Kubernetes YAML that integrates with any GitOps workflow:
 
 ```typescript
 // Generate ResourceGraphDefinition YAML
-const kroFactory = await webappGraph.factory('kro', { namespace: 'default' });
+const kroFactory = webappGraph.factory('kro', { namespace: 'default' });
 const yaml = kroFactory.toYaml();
 
 // Save for GitOps deployment
@@ -193,7 +218,7 @@ Deploy directly to your cluster for rapid iteration:
 
 ```typescript
 // Create factory and deploy immediately
-const factory = await webappGraph.factory('direct', { namespace: 'development' });
+const factory = webappGraph.factory('direct', { namespace: 'development' });
 
 // Deploy with specific configuration
 const instance = await factory.deploy({
@@ -224,7 +249,7 @@ Leverage Kubernetes Resource Orchestrator for advanced runtime capabilities:
 
 ```typescript
 // Deploy as ResourceGraphDefinition with runtime resolution
-const kroFactory = await webappGraph.factory('kro', { namespace: 'production' });
+const kroFactory = webappGraph.factory('kro', { namespace: 'production' });
 
 // Apply the ResourceGraphDefinition to cluster
 await kroFactory.deploy({ 
@@ -260,7 +285,7 @@ Deploy the same graph to different environments with environment-specific config
 
 ```typescript
 // Development: Direct deployment for fast iteration
-const devFactory = await webappGraph.factory('direct', { namespace: 'dev' });
+const factory = webappGraph.factory('direct', { namespace: 'dev' });
 await devFactory.deploy({
   name: 'webapp-dev',
   image: 'nginx:latest',
@@ -268,7 +293,7 @@ await devFactory.deploy({
 });
 
 // Staging: Kro deployment for testing runtime dependencies  
-const stagingFactory = await webappGraph.factory('kro', { namespace: 'staging' });
+const factory = webappGraph.factory('kro', { namespace: 'staging' });
 await stagingFactory.deploy({
   name: 'webapp-staging',
   image: 'nginx:1.21-rc',
@@ -276,7 +301,7 @@ await stagingFactory.deploy({
 });
 
 // Production: GitOps deployment
-const prodFactory = await webappGraph.factory('kro', { namespace: 'production' });
+const factory = webappGraph.factory('kro', { namespace: 'production' });
 const prodYaml = prodFactory.toYaml();
 writeFileSync('k8s/production/webapp.yaml', prodYaml);
 // Deployed via ArgoCD/Flux
@@ -298,175 +323,6 @@ writeFileSync('k8s/production/webapp.yaml', prodYaml);
 
 ---
 
-## Core Architecture
-
-TypeKro's architecture enables compile-time type safety with runtime intelligence through three key systems:
-
-```mermaid
-graph TD
-    A[TypeScript Code] --> B[Magic Proxy System]
-    B --> C[Schema References]
-    B --> D[Static Values]
-    C --> E[CEL Expressions]
-    D --> F[Direct Values]
-    E --> G[Runtime Resolution]
-    F --> G
-    G --> H{Deployment Strategy}
-    
-    H --> I[YAML Generation]
-    H --> J[Direct Deployment]
-    H --> K[KRO Deployment]
-    
-    I --> L[GitOps Tools<br/>ArgoCD, Flux, kubectl]
-    J --> M[Kubernetes API<br/>Immediate Deployment]
-    K --> N[KRO Controller<br/>Runtime Dependencies]
-    
-    L --> O[Kubernetes Cluster]
-    M --> O
-    N --> O
-    
-    subgraph "Compile Time"
-        A
-        B
-        C
-        D
-        P[IDE Support<br/>Autocomplete<br/>Type Safety]
-    end
-    
-    subgraph "Runtime"
-        E
-        G
-        Q[CEL Evaluation<br/>Cross-Resource Refs<br/>Status Propagation]
-    end
-    
-    A -.-> P
-    N -.-> Q
-    
-    style A fill:#e1f5fe
-    style B fill:#f3e5f5
-    style O fill:#e8f5e8
-    style P fill:#fff3e0
-    style Q fill:#fff3e0
-```
-
-### Magic Proxy System
-
-TypeKro's "magic" comes from its **proxy system** that creates different behaviors for execution-time vs runtime values:
-
-#### Static Values (Known at Execution Time)
-```typescript
-const deployment = simpleDeployment({
-  name: 'my-app',        // Static string
-  replicas: 3,           // Static number
-});
-
-// Accessing static values returns the actual value
-console.log(deployment.spec.replicas); // Returns: 3
-```
-
-#### Dynamic References (Unknown at Execution Time)
-```typescript
-const deployment = simpleDeployment({
-  name: schema.spec.name,  // Schema reference - unknown until runtime
-});
-
-// Accessing schema or status fields creates KubernetesRef objects
-const nameRef = schema.spec.name;        // Creates: KubernetesRef<string>
-const statusRef = deployment.status.readyReplicas; // Creates: KubernetesRef<number>
-```
-
-#### The `$` Prefix for Explicit References
-```typescript
-const configMap = simpleConfigMap({
-  name: 'config',
-  data: { key: 'value' }  // Static value
-});
-
-const deployment = simpleDeployment({
-  name: 'app',
-  env: {
-    // Static behavior: Uses the known value "value" at execution time
-    STATIC_VALUE: configMap.data.key,
-    
-    // Dynamic behavior: Creates reference resolved by Kro at runtime
-    DYNAMIC_VALUE: configMap.data.$key,
-  }
-});
-```
-
-**Key Rule**: Schema references (`schema.spec.*`) and status references (`resource.status.*`) are automatically converted to CEL expressions. For explicit runtime references to other resource properties, use the `$` prefix.
-
-### Enhanced Types (RefOrValue Pattern)
-
-Every factory function accepts `RefOrValue<T>`, which means any parameter can be:
-
-```typescript
-// 1. Direct value
-name: "my-app"
-
-// 2. Schema reference (becomes CEL)
-name: schema.spec.name
-
-// 3. CEL expression 
-name: Cel.template("%s-service", schema.spec.name)
-
-// 4. Reference to another resource
-env: {
-  DB_HOST: database.service.spec.clusterIP  // Runtime resolution
-}
-```
-
-This pattern provides **compile-time type safety** while enabling **runtime flexibility**.
-
-### CRD Installation Intelligence
-
-TypeKro's direct deployer automatically handles Custom Resource Definition timing:
-
-```typescript
-// TypeKro automatically detects CRD dependencies
-const kroResources = [
-  kroDefinition,           // CRD must be installed first
-  kroInstance             // Instance depends on CRD
-];
-
-const factory = await graph.factory('direct', { namespace: 'default' });
-await factory.deploy(spec);  // ✅ Automatically waits for CRD readiness
-```
-
-**Benefits:**
-- **No "CRD not found" errors** - Automatic timing coordination
-- **Zero manual ordering** - Intelligent dependency detection  
-- **Production reliability** - Handles CRD establishment properly
-
-### Runtime vs Compile-time Behavior
-
-| **Aspect** | **Compile-time** | **Runtime** |
-|------------|------------------|-------------|
-| **Type checking** | Full TypeScript validation | N/A |
-| **IDE support** | Autocomplete, refactoring | N/A |
-| **Schema references** | Appear as typed properties | Resolve to CEL expressions |
-| **Resource references** | Type-safe property access | Runtime cluster state lookup |
-| **Validation** | TypeScript + arktype schemas | Kubernetes validation + CEL |
-
----
-
-## Comparison Grid
-
-| Feature | TypeKro | Pulumi | CDK8s | Helm | Kustomize | Crossplane |
-|---------|---------|---------|--------|------|-----------|------------|
-| **Type Safety** | ✅ Full TypeScript | ✅ Multi-language | ✅ TypeScript | ❌ Templates | ❌ YAML | ❌ YAML |
-| **GitOps Ready** | ✅ Deterministic YAML | ❌ State backend | ✅ YAML output | ✅ Charts | ✅ YAML | ✅ YAML |
-| **Runtime Dependencies** | ✅ KRO + CEL expressions | ❌ Deploy-time only | ❌ Static | ❌ Templates | ❌ Static | ✅ Compositions |
-| **IDE Support** | ✅ Full autocomplete | ✅ Language support | ✅ TypeScript | ❌ Limited | ❌ Limited | ❌ Limited |
-| **Learning Curve** | 🟢 Just TypeScript | 🔴 New concepts | 🟡 TypeScript + K8s | 🔴 Templates | 🔴 YAML hell | 🔴 Complex |
-| **Kubernetes Native** | ✅ Pure K8s resources | ❌ Abstraction layer | ✅ Pure K8s | ✅ K8s resources | ✅ K8s resources | ✅ K8s + CRDs |
-| **Cross-Resource Refs** | ✅ Runtime resolution | ❌ Deploy-time | ❌ Manual | ❌ Manual | ❌ Manual | ✅ Built-in |
-| **Multi-Cloud** | 🟡 Via Alchemy | ✅ Native | ❌ K8s only | ❌ K8s only | ❌ K8s only | ✅ Native |
-| **State Management** | ✅ Stateless | ❌ State backend | ✅ Stateless | ✅ Stateless | ✅ Stateless | ✅ Controller |
-| **CRD Timing** | ✅ Automatic | ❌ Manual | ❌ Manual | ❌ Manual | ❌ Manual | ✅ Built-in |
-
----
-
 ## GitOps Workflows
 
 ### Deterministic YAML Generation
@@ -477,10 +333,10 @@ TypeKro generates stable, deterministic YAML output perfect for GitOps workflows
 // generate-manifests.ts
 import { writeFileSync } from 'fs';
 
-const graph = toResourceGraph(/* ... */);
+const graph = kubernetesComposition(/* ... */);
 
 // Same input always generates identical YAML
-const factory = await graph.factory('kro', { namespace: 'default' });
+const factory = graph.factory('kro', { namespace: 'default' });
 const yaml = factory.toYaml();
 
 // Write to file for GitOps
@@ -496,7 +352,7 @@ const environments = ['development', 'staging', 'production'];
 
 for (const env of environments) {
   // Generate ResourceGraphDefinition YAML for this environment
-  const factory = await webappGraph.factory('kro', { namespace: env });
+  const factory = webappGraph.factory('kro', { namespace: env });
   const rgdYaml = factory.toYaml();
   writeFileSync(`k8s/${env}/webapp-rgd.yaml`, rgdYaml);
   
@@ -532,7 +388,7 @@ const InfraSpec = type({
   environment: 'string'
 });
 
-const infraGraph = toResourceGraph(
+const infraGraph = kubernetesComposition(
   {
     name: 'ingress-infrastructure',
     apiVersion: 'infrastructure.example.com/v1',
@@ -540,46 +396,40 @@ const infraGraph = toResourceGraph(
     spec: InfraSpec,
     status: type({ ready: 'boolean' })
   },
-  (schema) => ({
-    // Helm repository source
-    repository: helmRepository({
-      name: 'nginx-repo',
-      url: 'https://kubernetes.github.io/ingress-nginx'
-    }),
-    
-    // Type-safe Helm release with schema references
-    controller: helmRelease({
-      name: Cel.template('%s-ingress', schema.spec.name),
-      chart: {
-        spec: {
-          chart: 'ingress-nginx',
-          sourceRef: {
-            kind: 'HelmRepository',
-            name: 'nginx-repo'
-          },
-          version: '4.8.0'
-        }
-      },
-      values: {
-        controller: {
-          replicaCount: schema.spec.replicas,                    // Schema reference
-          service: {
-            loadBalancerIP: schema.spec.loadBalancerIP           // Schema reference
-          },
-          config: {
-            'custom-config': Cel.template('env-%s', schema.spec.environment)  // CEL expression
-          }
-        }
-      }
-    })
-  }),
+  (schema) => {
+    // Create Helm repository first
+    const repository = helmRepository({
+      name: 'nginx-repo',
+      url: 'https://kubernetes.github.io/ingress-nginx'
+    });
+    
+    // Create Helm release using helmRelease factory
+    const controller = helmRelease({
+      name: Cel.template('%s-ingress', schema.spec.name),
+      repository: repository,  // Reference repository
+      chart: 'ingress-nginx',
+      values: {
+        controller: {
+          replicaCount: schema.spec.replicas,                    // Schema reference
+          service: {
+            loadBalancerIP: schema.spec.loadBalancerIP           // Schema reference
+          },
+          config: {
+            'custom-config': Cel.template('env-%s', schema.spec.environment)  // CEL expression
+          }
+        }
+      }
+    });
+
+    return { repository, controller };
+  },
   (schema, resources) => ({
     ready: Cel.expr(resources.controller.status.conditions, '[?@.type=="Ready"].status == "True"')
   })
 );
 
 // Deploy via Flux
-const factory = await infraGraph.factory('kro', { namespace: 'flux-system' });
+const factory = infraGraph.factory('kro', { namespace: 'flux-system' });
 const yaml = factory.toYaml();
 writeFileSync('k8s/ingress-controller.yaml', yaml);
 ```
@@ -602,53 +452,55 @@ const AppSpec = type({
   image: 'string'
 });
 
-const hybridGraph = toResourceGraph(
-  {
-    name: 'hybrid-app',
-    apiVersion: 'apps.example.com/v1',
-    kind: 'HybridApp',
-    spec: AppSpec,
-    status: type({ ready: 'boolean' })
-  },
-  (schema) => ({
-    // Include external YAML files
-    monitoring: yamlFile({
-      path: './k8s/prometheus-operator.yaml',
-      namespace: schema.metadata.namespace  // Schema reference for namespace
-    }),
-    
-    // Include entire directories with Kustomization
-    monitoringStack: yamlDirectory({
-      path: './k8s/monitoring/',
-      recursive: true,
-      kustomization: {
-        namePrefix: Cel.template('%s-', schema.spec.name),     // Dynamic prefix
-        namespace: schema.metadata.namespace,
-        commonLabels: {
-          'app.kubernetes.io/instance': schema.spec.name        // Schema reference
-        }
-      }
-    }),
-    
-    // Include from Git repositories
-    kubePrometheus: yamlDirectory({
-      path: 'https://github.com/prometheus-operator/kube-prometheus.git//manifests',
-      ref: 'v0.12.0',
-      namespace: 'monitoring'
-    }),
-    
-    // TypeKro resources that reference external resources
-    app: simpleDeployment({
-      name: schema.spec.name,
-      image: schema.spec.image,
-      env: {
-        PROMETHEUS_URL: 'http://prometheus-operated.monitoring.svc.cluster.local:9090'
-      }
-    })
-  }),
-  (schema, resources) => ({
-    ready: Cel.expr(resources.app.status.readyReplicas, ' > 0')
-  })
+const hybridGraph = kubernetesComposition(
+  {
+    name: 'hybrid-app',
+    apiVersion: 'apps.example.com/v1',
+    kind: 'HybridApp',
+    spec: AppSpec,
+    status: type({ ready: 'boolean' })
+  },
+  (spec) => {
+    // Include external YAML files
+    const monitoring = yamlFile({
+      path: './k8s/prometheus-operator.yaml',
+      namespace: 'default'  // Can use static namespace or reference
+    });
+    
+    // Include entire directories with Kustomization
+    const monitoringStack = yamlDirectory({
+      path: './k8s/monitoring/',
+      recursive: true,
+      kustomization: {
+        namePrefix: Cel.template('%s-', spec.name),     // Dynamic prefix
+        namespace: 'default',
+        commonLabels: {
+          'app.kubernetes.io/instance': spec.name        // Schema reference
+        }
+      }
+    });
+    
+    // Include from Git repositories
+    const kubePrometheus = yamlDirectory({
+      path: 'https://github.com/prometheus-operator/kube-prometheus.git//manifests',
+      ref: 'v0.12.0',
+      namespace: 'monitoring'
+    });
+    
+    // TypeKro resources that reference external resources
+    const app = simple.Deployment({
+      name: spec.name,
+      image: spec.image,
+      env: {
+        PROMETHEUS_URL: 'http://prometheus-operated.monitoring.svc.cluster.local:9090'
+      }
+    });
+
+    // Return status
+    return {
+      ready: Cel.expr<boolean>(app.status.readyReplicas, ' > 0')
+    };
+  }
 );
 ```
 
@@ -664,7 +516,7 @@ const hybridGraph = toResourceGraph(
 
 TypeKro provides 50+ factory functions for all major Kubernetes resources:
 
-**Core Resources:** `simpleDeployment()`, `simpleService()`, `simpleConfigMap()`, `simpleSecret()`, `simplePvc()`
+**Core Resources:** `simple.Deployment()`, `simple.Service()`, `simple.ConfigMap()`, `simple.Secret()`, `simple.Pvc()`
 
 **Advanced:** `helmRelease()`, `yamlFile()`, `customResource()`, `networkPolicy()`, `serviceAccount()`, plus comprehensive RBAC, storage, networking, and workload resources.
 
@@ -679,7 +531,7 @@ All resources support full type safety, cross-resource references, IDE autocompl
 ### 🆕 "I'm new to Kubernetes"
 **→ Use: Direct Deployment**
 ```typescript
-const factory = await graph.factory('direct', { namespace: 'default' });
+const factory = graph.factory('direct', { namespace: 'default' });
 await factory.deploy(spec);
 ```
 - Immediate feedback loop
@@ -690,24 +542,25 @@ await factory.deploy(spec);
 ### 🔄 "I have existing YAML and want to migrate gradually"  
 **→ Use: yamlFile() + gradual adoption**
 ```typescript
-const hybridGraph = toResourceGraph(
-  {
-    name: 'legacy-app',
-    apiVersion: 'apps.example.com/v1',
-    kind: 'LegacyApp',
-    spec: type({ name: 'string' }),
-    status: type({ ready: 'boolean' })
-  },
-  (schema) => ({
-    existing: yamlFile({ path: './existing/app.yaml' }),        // Keep existing
-    newService: simpleService({                                 // Add TypeKro gradually
-      name: schema.spec.name,
-      selector: { app: schema.spec.name }
-    })
-  }),
-  (schema, resources) => ({
-    ready: Cel.expr(resources.newService.status.ready, ' == true')
-  })
+const hybridGraph = kubernetesComposition(
+  {
+    name: 'legacy-app',
+    apiVersion: 'apps.example.com/v1',
+    kind: 'LegacyApp',
+    spec: type({ name: 'string' }),
+    status: type({ ready: 'boolean' })
+  },
+  (spec) => {
+    const existing = yamlFile({ path: './existing/app.yaml' });        // Keep existing
+    const newService = simple.Service({                                 // Add TypeKro gradually
+      name: spec.name,
+      selector: { app: spec.name }
+    });
+
+    return {
+      ready: Cel.expr<boolean>(newService.status.ready, ' == true')
+    };
+  }
 );
 ```
 - Preserve existing workflows
@@ -717,7 +570,7 @@ const hybridGraph = toResourceGraph(
 ### 🚀 "I want GitOps workflows"
 **→ Use: YAML Generation + Flux HelmRelease**
 ```typescript
-const factory = await graph.factory('kro', { namespace: 'production' });
+const factory = graph.factory('kro', { namespace: 'production' });
 const yaml = factory.toYaml();
 writeFileSync('k8s/app.yaml', yaml);
 ```
@@ -729,7 +582,7 @@ writeFileSync('k8s/app.yaml', yaml);
 **→ Use: [Alchemy Integration](#multi-cloud-integration-with-alchemy)**
 ```typescript
 await alchemyScope.run(async () => {
-  const factory = await graph.factory('direct', { 
+  const factory = graph.factory('direct', { 
     namespace: 'default',
     alchemyScope: alchemyScope 
   });
@@ -744,14 +597,15 @@ await alchemyScope.run(async () => {
 **→ Use: helmRelease() patterns**
 ```typescript
 helmRelease({
-  name: 'nginx',
-  chart: { /* ... */ },
-  values: {
-    replicaCount: schema.spec.replicas,  // Type-safe values
-    service: {
-      loadBalancerIP: schema.spec.ip     // Schema references
-    }
-  }
+  name: 'nginx',
+  repository: repository,
+  chart: 'nginx',
+  values: {
+    replicaCount: spec.replicas,  // Type-safe values
+    service: {
+      loadBalancerIP: spec.ip     // Schema references
+    }
+  }
 })
 ```
 - Type-safe Helm values
@@ -761,7 +615,7 @@ helmRelease({
 ### 🔗 "I have complex runtime dependencies"
 **→ Use: Kro Deployment + CEL expressions**
 ```typescript
-simpleDeployment({
+simple.Deployment({
   env: {
     DB_HOST: database.service.spec.clusterIP,           // Runtime resolution
     API_URL: Cel.template('http://%s:8080', 
@@ -789,129 +643,16 @@ Choose based on your team's needs, not just technical capabilities. You can alwa
 
 ---
 
-## Enhanced Type System
+## Multi-Cloud Integration with Alchemy
 
-TypeKro provides **enhanced types** through its magic proxy system, eliminating the need for optional chaining (`?.`) when working with schema and resource references.
+TypeKro integrates seamlessly with [Alchemy](https://alchemy.run) to enable unified cloud + Kubernetes infrastructure management. Alchemy is infrastructure-as-TypeScript that lets you deploy to Cloudflare, AWS, and more with pure TypeScript.
 
-### Schema References - Always Present
+### Why Use TypeKro + Alchemy?
 
-When you access schema fields in the resource builder, TypeScript treats them as always present:
-
-```typescript
-const graph = toResourceGraph(
-  {
-    name: 'my-app',
-    spec: type({
-      name: 'string',
-      image: 'string',
-      replicas: 'number',
-      environment: 'string',
-    }),
-    status: type({
-      ready: 'boolean',
-      url: 'string',
-    }),
-  },
-  (schema) => ({
-    deployment: simpleDeployment({
-      // ✅ No optional chaining needed - TypeScript knows these exist
-      name: schema.spec.name,           // Type: string (not string | undefined)
-      image: schema.spec.image,         // Type: string (not string | undefined)
-      replicas: schema.spec.replicas,   // Type: number (not number | undefined)
-      
-      env: {
-        NODE_ENV: schema.spec.environment,  // Type: string
-      },
-    }),
-  }),
-  (schema, resources) => ({
-    // ✅ Status fields are also enhanced - no optional chaining needed
-    ready: Cel.expr(resources.deployment.status.readyReplicas, ' > 0'),
-    url: Cel.template('https://%s.example.com', schema.spec.name),
-  })
-);
-```
-
-### Resource Status References - Enhanced Types
-
-Resource status fields are enhanced to be non-optional within the builders:
-
-```typescript
-// Without TypeKro (regular Kubernetes types)
-const regularK8s = {
-  // These would require optional chaining
-  replicas: deployment.status?.readyReplicas,        // number | undefined
-  conditions: deployment.status?.conditions?.[0],   // Condition | undefined
-};
-
-// With TypeKro (enhanced types)
-const graph = toResourceGraph(
-  // ... schema definition
-  (schema, resources) => ({
-    // ✅ No optional chaining needed - enhanced types guarantee presence
-    replicas: resources.deployment.status.readyReplicas,     // Type: number
-    phase: resources.deployment.status.phase,                // Type: string
-    conditions: resources.deployment.status.conditions[0],   // Type: Condition
-    
-    // Complex expressions work naturally
-    healthy: Cel.expr(
-      resources.deployment.status.readyReplicas, ' == ',
-      resources.deployment.spec.replicas
-    ),
-  })
-);
-```
-
-### How Enhanced Types Work
-
-The magic proxy system provides type enhancement while respecting the static/dynamic value distinction:
-
-1. **Enhanced Type Safety**: Schema and resource references appear as non-optional TypeScript types
-2. **Dynamic Reference Creation**: Schema and status field access creates `KubernetesRef<T>` objects
-3. **Static Value Preservation**: Known values at execution time remain as actual values
-
-```typescript
-// Schema references (always dynamic - unknown until runtime)
-const nameRef = schema.spec.name;                    // Creates: KubernetesRef<string>
-const imageRef = schema.spec.image;                  // Creates: KubernetesRef<string>
-
-// Resource status references (always dynamic - runtime cluster state)
-const replicasRef = resources.deployment.status.readyReplicas;  // Creates: KubernetesRef<number>
-
-// Static values (known at execution time)
-const staticName = 'my-app';                         // Remains: string
-const staticReplicas = 3;                            // Remains: number
-
-// Mixed usage in factory functions
-const deployment = simpleDeployment({
-  name: schema.spec.name,        // Dynamic: KubernetesRef<string> → CEL expression
-  replicas: 3,                   // Static: number → direct value
-  image: 'nginx:latest'          // Static: string → direct value
-});
-```
-
-### Benefits of Enhanced Types
-
-- **No Optional Chaining**: Write cleaner code without `?.` operators
-- **Better IntelliSense**: Full autocomplete for all schema and status fields
-- **Execution-Time Safety**: Catch typos and missing fields when building resources
-- **Runtime Flexibility**: References are resolved dynamically by Kro
-- **Natural Syntax**: Write code that looks like direct property access
-
-This enhanced type system makes TypeKro feel natural to use while maintaining the powerful reference resolution capabilities needed for complex Kubernetes deployments.
-
----
-
-## Multi-Cloud Integration with Alchemy
-
-TypeKro integrates seamlessly with [Alchemy](https://alchemy.run) to enable unified cloud + Kubernetes infrastructure management. Alchemy is infrastructure-as-TypeScript that lets you deploy to Cloudflare, AWS, and more with pure TypeScript.
-
-### Why Use TypeKro + Alchemy?
-
-- **Unified TypeScript Experience**: Write both cloud resources and Kubernetes resources in the same language
-- **Cross-Platform References**: Cloud resources can reference Kubernetes resources and vice versa
-- **Type-Safe Integration**: Full TypeScript validation across your entire infrastructure stack
-- **Flexible Deployment**: Use any TypeKro deployment strategy (Direct, YAML, KRO) with Alchemy
+- **Unified TypeScript Experience**: Write both cloud resources and Kubernetes resources in the same language
+- **Cross-Platform References**: Cloud resources can reference Kubernetes resources and vice versa
+- **Type-Safe Integration**: Full TypeScript validation across your entire infrastructure stack
+- **Flexible Deployment**: Use any TypeKro deployment strategy (Direct, YAML, KRO) with Alchemy
 
 ### Individual Resource Registration Pattern
 
@@ -928,32 +669,33 @@ const app = await alchemy('webapp-infrastructure');
 const bucket = await Bucket('webapp-uploads');
 
 // 3. Create Kubernetes resources that reference cloud resources
-const webappGraph = toResourceGraph(
-  {
-    name: 'webapp-with-cloud',
-    apiVersion: 'example.com/v1',
-    kind: 'CloudWebApp',
-    spec: type({ name: 'string', image: 'string', replicas: 'number' }),
-    status: type({ ready: 'boolean' })
-  },
-  (schema) => ({
-    app: simpleDeployment({
-      name: schema.spec.name,
-      image: schema.spec.image,
-      env: {
-        BUCKET_NAME: bucket.name,  // Reference to Alchemy resource
-        API_URL: Cel.template('http://%s-service', schema.spec.name)
-      }
-    })
-  }),
-  (schema, resources) => ({
-    ready: Cel.expr(resources.app.status.readyReplicas, ' > 0')
-  })
+const webappGraph = kubernetesComposition(
+  {
+    name: 'webapp-with-cloud',
+    apiVersion: 'example.com/v1',
+    kind: 'CloudWebApp',
+    spec: type({ name: 'string', image: 'string', replicas: 'number' }),
+    status: type({ ready: 'boolean' })
+  },
+  (spec) => {
+    const app = simple.Deployment({
+      name: spec.name,
+      image: spec.image,
+      env: {
+        BUCKET_NAME: bucket.name,  // Reference to Alchemy resource
+        API_URL: Cel.template('http://%s-service', spec.name)
+      }
+    });
+
+    return {
+      ready: Cel.expr<boolean>(app.status.readyReplicas, ' > 0')
+    };
+  }
 );
 
 // Deploy TypeKro resources with Alchemy integration
 await app.run(async () => {
-  const factory = await webappGraph.factory('direct', { 
+  const factory = webappGraph.factory('direct', { 
     namespace: 'default',
     alchemyScope: app 
   });
@@ -972,7 +714,7 @@ Here's a complete example showing TypeKro + Alchemy for a production cloud-nativ
 ```typescript
 import alchemy from 'alchemy';
 import { Bucket, Function as LambdaFunction } from 'alchemy/aws';
-import { toResourceGraph, simpleDeployment, type } from 'typekro';
+import { kubernetesComposition, simple, type } from 'typekro';
 
 // 1. Create Alchemy scope
 const app = await alchemy('cloud-native-app');
@@ -994,40 +736,45 @@ const AppSpec = type({
   replicas: 'number'
 });
 
-const appGraph = toResourceGraph(
-  {
-    name: 'cloud-native-app',
-    apiVersion: 'example.com/v1',
-    kind: 'CloudNativeApp',
-    spec: AppSpec,
-    status: type({ ready: 'boolean' })
-  },
-  (schema) => ({
-    app: simpleDeployment({
-      name: schema.spec.name,
-      image: schema.spec.image,
-      env: {
-        // Reference cloud resources
-        API_URL: api.url,
-        UPLOAD_BUCKET: bucket.name,
-        // Reference other Kubernetes resources  
-        REDIS_HOST: Cel.template('%s-redis', schema.spec.name)
-      }
-    }),
-    
-    redis: simpleDeployment({
-      name: Cel.template('%s-redis', schema.spec.name),
-      image: 'redis:7'
-    })
-  }),
-  (schema, resources) => ({
-    ready: Cel.expr(resources.app.status.readyReplicas, ' > 0')
-  })
+const appGraph = kubernetesComposition(
+  {
+    name: 'cloud-native-app',
+    apiVersion: 'example.com/v1',
+    kind: 'CloudNativeApp',
+    spec: AppSpec,
+    status: type({ ready: 'boolean' })
+  },
+  (spec) => {
+    // Create redis first
+    const redis = simple.Deployment({
+      name: Cel.template('%s-redis', spec.name),
+      image: 'redis:7',
+      labels: { app: Cel.template('%s-redis', spec.name), component: 'cache' }
+    });
+    
+    // Create app that references redis
+    const app = simple.Deployment({
+      name: spec.name,
+      image: spec.image,
+      labels: { app: spec.name, component: 'web' },
+      env: {
+        // Reference cloud resources
+        API_URL: api.url,
+        UPLOAD_BUCKET: bucket.name,
+        // Reference other Kubernetes resources by field
+        REDIS_HOST: redis.metadata.name
+      }
+    });
+
+    return {
+      ready: Cel.expr<boolean>(app.status.readyReplicas, ' > 0')
+    };
+  }
 );
 
 // 4. Deploy as unified infrastructure
 await app.run(async () => {
-  const factory = await appGraph.factory('direct', { 
+  const factory = appGraph.factory('direct', { 
     namespace: 'production',
     alchemyScope: app 
   });
@@ -1051,9 +798,9 @@ const database = await RDS('main-db');
 const cache = await ElastiCache('redis-cluster');
 
 // Add Kubernetes workloads that use cloud resources
-const k8sWorkloads = await webappGraph.factory('kro', { namespace: 'apps' });
+const k8sWorkloads = webappGraph.factory('kro', { namespace: 'apps' });
 await app.run(async () => {
-  const factory = await k8sWorkloads.factory('kro', { 
+  const factory = k8sWorkloads.factory('kro', { 
     namespace: 'apps',
     alchemyScope: app 
   });
@@ -1066,20 +813,24 @@ await app.run(async () => {
 
 #### Pattern 2: Kubernetes-First with Cloud Services
 ```typescript
-// Start with Kubernetes infrastructure
-const webappFactory = await webappGraph.factory('direct', { namespace: 'default' });
-
-// Add cloud resources that support the Kubernetes workloads
+// Start with cloud infrastructure first
 const app = await alchemy('support-services');
 const monitoring = await CloudWatch('webapp-metrics');
 const storage = await S3('webapp-data');
 
+// Deploy Kubernetes resources with access to cloud resources
 await app.run(async () => {
-  const factory = await webappGraph.factory('direct', { 
+  const factory = webappGraph.factory('direct', { 
     namespace: 'default',
     alchemyScope: app 
   });
-  await factory.deploy({ /* config */ });
+  await factory.deploy({ 
+    name: 'webapp',
+    image: 'myapp:latest',
+    // Kubernetes resources can reference cloud resources
+    monitoring: monitoring.endpoint,
+    storage: storage.bucketName
+  });
 });
 ```
 
@@ -1094,6 +845,273 @@ await app.run(async () => {
 
 ---
 
+
+## Core Architecture
+
+TypeKro's architecture enables compile-time type safety with runtime intelligence through three key systems:
+
+```mermaid
+graph TD
+    A[TypeScript Code] --> B[Magic Proxy System]
+    B --> C[Schema References]
+    B --> D[Static Values]
+    C --> E[CEL Expressions]
+    D --> F[Direct Values]
+    E --> G[Runtime Resolution]
+    F --> G
+    G --> H{Deployment Strategy}
+    
+    H --> I[YAML Generation]
+    H --> J[Direct Deployment]
+    H --> K[KRO Deployment]
+    
+    I --> L[GitOps Tools<br/>ArgoCD, Flux, kubectl]
+    J --> M[Kubernetes API<br/>Immediate Deployment]
+    K --> N[KRO Controller<br/>Runtime Dependencies]
+    
+    L --> O[Kubernetes Cluster]
+    M --> O
+    N --> O
+    
+    subgraph "Compile Time"
+        A
+        B
+        C
+        D
+        P[IDE Support<br/>Autocomplete<br/>Type Safety]
+    end
+    
+    subgraph "Runtime"
+        E
+        G
+        Q[CEL Evaluation<br/>Cross-Resource Refs<br/>Status Propagation]
+    end
+    
+    A -.-> P
+    N -.-> Q
+    
+    style A fill:#e1f5fe
+    style B fill:#f3e5f5
+    style O fill:#e8f5e8
+    style P fill:#fff3e0
+    style Q fill:#fff3e0
+```
+
+### Magic Proxy System
+
+TypeKro's "magic" comes from its **proxy system** that creates different behaviors for execution-time vs runtime values:
+
+#### Static Values (Known at Execution Time)
+```typescript
+const deployment = simple.Deployment({
+  name: 'my-app',        // Static string
+  replicas: 3,           // Static number
+});
+
+// Accessing static values returns the actual value
+console.log(deployment.spec.replicas); // Returns: 3
+```
+
+#### Dynamic References (Unknown at Execution Time)
+```typescript
+const deployment = simple.Deployment({
+  name: schema.spec.name,  // Schema reference - unknown until runtime
+});
+
+// Accessing schema or status fields creates KubernetesRef objects
+const nameRef = schema.spec.name;        // Creates: KubernetesRef<string>
+const statusRef = deployment.status.readyReplicas; // Creates: KubernetesRef<number>
+```
+
+#### The `$` Prefix for Explicit References
+```typescript
+const configMap = simple.ConfigMap({
+  name: 'config',
+  data: { key: 'value' }  // Static value
+});
+
+const deployment = simple.Deployment({
+  name: 'app',
+  env: {
+    // Static behavior: Uses the known value "value" at execution time
+    STATIC_VALUE: configMap.data.key,
+    
+    // Dynamic behavior: Creates reference resolved by Kro at runtime
+    DYNAMIC_VALUE: configMap.data.$key,
+  }
+});
+```
+
+**Key Rule**: Schema references (`schema.spec.*`) and status references (`resource.status.*`) are automatically converted to CEL expressions. For explicit runtime references to other resource properties, use the `$` prefix.
+
+### Enhanced Types (RefOrValue Pattern)
+
+Every factory function accepts `RefOrValue<T>`, which means any parameter can be:
+
+```typescript
+// 1. Direct value
+name: "my-app"
+
+// 2. Schema reference (becomes CEL)
+name: schema.spec.name
+
+// 3. CEL expression 
+name: Cel.template("%s-service", schema.spec.name)
+
+// 4. Reference to another resource
+env: {
+  DB_HOST: database.service.spec.clusterIP  // Runtime resolution
+}
+```
+
+This pattern provides **compile-time type safety** while enabling **runtime flexibility**.
+
+### CRD Installation Intelligence
+
+TypeKro's direct deployer automatically handles Custom Resource Definition timing:
+
+```typescript
+// TypeKro automatically detects CRD dependencies
+const kroResources = [
+  kroDefinition,           // CRD must be installed first
+  kroInstance             // Instance depends on CRD
+];
+
+const factory = graph.factory('direct', { namespace: 'default' });
+await factory.deploy(spec);  // ✅ Automatically waits for CRD readiness
+```
+
+**Benefits:**
+- **No "CRD not found" errors** - Automatic timing coordination
+- **Zero manual ordering** - Intelligent dependency detection  
+- **Production reliability** - Handles CRD establishment properly
+
+### Runtime vs Compile-time Behavior
+
+| **Aspect** | **Compile-time** | **Runtime** |
+|------------|------------------|-------------|
+| **Type checking** | Full TypeScript validation | N/A |
+| **IDE support** | Autocomplete, refactoring | N/A |
+| **Schema references** | Appear as typed properties | Resolve to CEL expressions |
+| **Resource references** | Type-safe property access | Runtime cluster state lookup |
+| **Validation** | TypeScript + arktype schemas | Kubernetes validation + CEL |
+
+---
+
+
+## Enhanced Type System
+
+TypeKro provides **enhanced types** through its magic proxy system, eliminating the need for optional chaining (`?.`) when working with schema and resource references.
+
+### Schema References - Always Present
+
+When you access schema fields in the resource builder, TypeScript treats them as always present:
+
+```typescript
+const graph = toResourceGraph(
+  {
+    name: 'my-app',
+    spec: type({
+      name: 'string',
+      image: 'string',
+      replicas: 'number',
+      environment: 'string',
+    }),
+    status: type({
+      ready: 'boolean',
+      url: 'string',
+    }),
+  },
+  (schema) => ({
+    deployment: simple.Deployment({
+      // ✅ No optional chaining needed - TypeScript knows these exist
+      name: schema.spec.name,           // Type: string (not string | undefined)
+      image: schema.spec.image,         // Type: string (not string | undefined)
+      replicas: schema.spec.replicas,   // Type: number (not number | undefined)
+      
+      env: {
+        NODE_ENV: schema.spec.environment,  // Type: string
+      },
+    }),
+  }),
+  (schema, resources) => ({
+    // ✅ Status fields are also enhanced - no optional chaining needed
+    ready: Cel.expr(resources.deployment.status.readyReplicas, ' > 0'),
+    url: Cel.template('https://%s.example.com', schema.spec.name),
+  })
+);
+```
+
+### Resource Status References - Enhanced Types
+
+Resource status fields are enhanced to be non-optional within the builders:
+
+```typescript
+// Without TypeKro (regular Kubernetes types)
+const regularK8s = {
+  // These would require optional chaining
+  replicas: deployment.status?.readyReplicas,        // number | undefined
+  conditions: deployment.status?.conditions?.[0],   // Condition | undefined
+};
+
+// With TypeKro (enhanced types)
+const graph = toResourceGraph(
+  // ... schema definition
+  (schema, resources) => ({
+    // ✅ No optional chaining needed - enhanced types guarantee presence
+    replicas: resources.deployment.status.readyReplicas,     // Type: number
+    phase: resources.deployment.status.phase,                // Type: string
+    conditions: resources.deployment.status.conditions[0],   // Type: Condition
+    
+    // Complex expressions work naturally
+    healthy: Cel.expr(
+      resources.deployment.status.readyReplicas, ' == ',
+      resources.deployment.spec.replicas
+    ),
+  })
+);
+```
+
+### How Enhanced Types Work
+
+The magic proxy system provides type enhancement while respecting the static/dynamic value distinction:
+
+1. **Enhanced Type Safety**: Schema and resource references appear as non-optional TypeScript types
+2. **Dynamic Reference Creation**: Schema and status field access creates `KubernetesRef<T>` objects
+3. **Static Value Preservation**: Known values at execution time remain as actual values
+
+```typescript
+// Schema references (always dynamic - unknown until runtime)
+const nameRef = schema.spec.name;                    // Creates: KubernetesRef<string>
+const imageRef = schema.spec.image;                  // Creates: KubernetesRef<string>
+
+// Resource status references (always dynamic - runtime cluster state)
+const replicasRef = resources.deployment.status.readyReplicas;  // Creates: KubernetesRef<number>
+
+// Static values (known at execution time)
+const staticName = 'my-app';                         // Remains: string
+const staticReplicas = 3;                            // Remains: number
+
+// Mixed usage in factory functions
+const deployment = simple.Deployment({
+  name: schema.spec.name,        // Dynamic: KubernetesRef<string> → CEL expression
+  replicas: 3,                   // Static: number → direct value
+  image: 'nginx:latest'          // Static: string → direct value
+});
+```
+
+### Benefits of Enhanced Types
+
+- **No Optional Chaining**: Write cleaner code without `?.` operators
+- **Better IntelliSense**: Full autocomplete for all schema and status fields
+- **Execution-Time Safety**: Catch typos and missing fields when building resources
+- **Runtime Flexibility**: References are resolved dynamically by Kro
+- **Natural Syntax**: Write code that looks like direct property access
+
+This enhanced type system makes TypeKro feel natural to use while maintaining the powerful reference resolution capabilities needed for complex Kubernetes deployments.
+
+---
+
 ## Contributing
 
 We welcome contributions to TypeKro! Whether you're fixing bugs, adding features, or improving documentation, your help makes TypeKro better for everyone.
@@ -1134,4 +1152,4 @@ The contributing guide includes:
 
 ## License
 
-Apache 2.0 - see [LICENSE](LICENSE) for details.
+Apache 2.0 - see [LICENSE](LICENSE) for details.