@intentius/chant-lexicon-gcp 0.0.15 → 0.0.16

package/README.md

@@ -0,0 +1,23 @@
+# @intentius/chant-lexicon-gcp
+
+GCP Deployment Manager lexicon for [chant](https://intentius.io/chant/) — declare infrastructure as typed TypeScript that serializes to Deployment Manager YAML templates.
+
+This package provides generated constructors for GCP resource types, type-safe template properties, pseudo-parameters, composites for grouping related resources, and GCP-specific lint rules. It also includes LSP and MCP server support for editor completions and hover.
+
+```bash
+npm install --save-dev @intentius/chant @intentius/chant-lexicon-gcp
+```
+
+**[Documentation →](https://intentius.io/chant/lexicons/gcp/)**
+
+## Related Packages
+
+| Package | Role |
+|---------|------|
+| [@intentius/chant](https://www.npmjs.com/package/@intentius/chant) | Core type system, CLI, build pipeline |
+| [@intentius/chant-lexicon-aws](https://www.npmjs.com/package/@intentius/chant-lexicon-aws) | AWS CloudFormation lexicon |
+| [@intentius/chant-lexicon-azure](https://www.npmjs.com/package/@intentius/chant-lexicon-azure) | Azure ARM lexicon |
+
+## License
+
+See the main project LICENSE file.

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "xxhash64",
   "artifacts": {
-    "manifest.json": "6cdf79b2aac2297c",
+    "manifest.json": "ad77fb29e1f765b8",
     "meta.json": "5c5359c023b36835",
     "types/index.d.ts": "c7cc45a739cefe9d",
     "rules/hardcoded-region.ts": "d230565c5cc6b600",
@@ -30,7 +30,8 @@
     "rules/wgc113.ts": "677724b28a9dbd5c",
     "skills/chant-gcp.md": "3c35bcda9067ed01",
     "skills/chant-gcp-security.md": "e93c103ba16b6d87",
-    "skills/chant-gcp-patterns.md": "ab5dea252128c7d2"
+    "skills/chant-gcp-patterns.md": "ab5dea252128c7d2",
+    "skills/chant-gke.md": "15b6fd248379f66"
   },
-  "composite": "83d2f9601b807e71"
+  "composite": "ffdc5245f6535b62"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "gcp",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "chantVersion": ">=0.1.0",
   "namespace": "GCP",
   "intrinsics": [],

package/dist/skills/chant-gke.md

@@ -0,0 +1,194 @@
+---
+skill: chant-gke
+description: End-to-end GKE workflow bridging GCP infrastructure and Kubernetes workloads
+user-invocable: true
+---
+
+# GKE End-to-End Workflow
+
+## Overview
+
+This skill bridges two lexicons:
+- **`@intentius/chant-lexicon-gcp`** — GKE cluster, node pool, service accounts, IAM bindings, Cloud DNS (Config Connector)
+- **`@intentius/chant-lexicon-k8s`** — Kubernetes workloads, Workload Identity, GCE Ingress, storage, observability (K8s YAML)
+
+## Architecture
+
+```
+GCP Lexicon (Config Connector)           K8s Lexicon (kubectl apply)
+┌─────────────────────────────┐         ┌─────────────────────────────────┐
+│ VPC + Subnets + Cloud NAT   │         │ NamespaceEnv (quotas)           │
+│ GKE Cluster + Node Pool     │         │ AutoscaledService (app)         │
+│ GCP Service Accounts        │──GSA──→ │ WorkloadIdentityServiceAccount  │
+│ IAM Policy Members          │         │ GCE Ingress + GkeExternalDns    │
+│ Cloud DNS Managed Zone      │         │ GcePdStorageClass               │
+└─────────────────────────────┘         │ GkeFluentBitAgent (logs)        │
+                                        │ GkeOtelCollector (traces)       │
+                                        └─────────────────────────────────┘
+```
+
+## Step 1: Bootstrap (one-time)
+
+Creates a GKE cluster with Config Connector enabled and configures Workload Identity:
+
+```bash
+export GCP_PROJECT_ID=<your-project>
+npm run bootstrap
+```
+
+This enables required APIs, creates the cluster, sets up a Config Connector service account with editor/IAM/DNS roles, and waits for the controller to be ready.
+
+## Step 2: Build
+
+```bash
+# Build Config Connector YAML
+chant build src --lexicon gcp -o config.yaml
+
+# Build K8s workload YAML
+chant build src --lexicon k8s -o k8s.yaml
+```
+
+Or use the combined script:
+
+```bash
+npm run build
+```
+
+## Step 3: Deploy Config Connector Resources
+
+```bash
+npm run deploy-infra
+# Applies config.yaml — Config Connector reconciles GCP resources
+```
+
+Key GCP resources created:
+- **GKE Cluster** — control plane with Workload Identity enabled
+- **Node Pool** — worker nodes
+- **GCP Service Accounts** — app SA, ExternalDNS SA, logging SA, monitoring SA
+- **IAM Policy Members** — Workload Identity bindings + role grants
+- **Cloud DNS Managed Zone** — for ExternalDNS
+
+## Step 4: Load Outputs
+
+```bash
+npm run load-outputs
+```
+
+Populates `.env` with GCP service account emails and DNS zone info from the live cluster. These values flow into K8s composite props via `config.ts`.
+
+## Step 5: Deploy K8s Workloads
+
+```bash
+npm run build:k8s    # Rebuild with real values from .env
+npm run apply        # kubectl apply -f k8s.yaml
+```
+
+### Key K8s composites for GKE
+
+```typescript
+import {
+  NamespaceEnv,
+  AutoscaledService,
+  WorkloadIdentityServiceAccount,
+  GkeExternalDnsAgent,
+  GcePdStorageClass,
+  GkeFluentBitAgent,
+  GkeOtelCollector,
+} from "@intentius/chant-lexicon-k8s";
+
+// 1. Namespace with quotas and network isolation
+const ns = NamespaceEnv({
+  name: "prod",
+  cpuQuota: "16",
+  memoryQuota: "32Gi",
+  defaultCpuRequest: "100m",
+  defaultMemoryRequest: "128Mi",
+  defaultDenyIngress: true,
+});
+
+// 2. Workload Identity ServiceAccount (use GSA email from Config Connector outputs)
+const wi = WorkloadIdentityServiceAccount({
+  name: "app-sa",
+  gcpServiceAccountEmail: "app@my-project.iam.gserviceaccount.com",  // from .env
+  namespace: "prod",
+});
+
+// 3. Application with autoscaling
+const app = AutoscaledService({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  maxReplicas: 10,
+  cpuRequest: "200m",
+  memoryRequest: "256Mi",
+  namespace: "prod",
+});
+
+// 4. ExternalDNS for Cloud DNS
+const dns = GkeExternalDnsAgent({
+  gcpServiceAccountEmail: "dns@my-project.iam.gserviceaccount.com",
+  gcpProjectId: "my-project",
+  domainFilters: ["example.com"],
+});
+
+// 5. Storage
+const storage = GcePdStorageClass({ name: "pd-balanced", type: "pd-balanced" });
+
+// 6. Observability
+const logging = GkeFluentBitAgent({
+  clusterName: "my-cluster",
+  projectId: "my-project",
+});
+
+const tracing = GkeOtelCollector({
+  clusterName: "my-cluster",
+  projectId: "my-project",
+});
+```
+
+## Step 6: Verify
+
+```bash
+npm run status
+kubectl get pods -n prod
+kubectl get ingress -n prod
+kubectl logs -n gke-logging -l app.kubernetes.io/name=fluent-bit
+```
+
+## Cleanup
+
+```bash
+npm run teardown
+```
+
+Delete order matters:
+1. **K8s workloads** — drains load balancers
+2. **Config Connector resources** — deletes GCP infra (SAs, IAM, DNS)
+3. **Config Connector SA** — the CC controller's own SA
+4. **GKE cluster** — the bootstrap cluster itself
+
+## Cross-Lexicon Value Flow
+
+Config Connector outputs flow into K8s composite props via `.env`:
+
+| Config Connector Output | K8s Composite Prop |
+|------------------------|-------------------|
+| App GSA email | `WorkloadIdentityServiceAccount.gcpServiceAccountEmail` |
+| ExternalDNS GSA email | `GkeExternalDnsAgent.gcpServiceAccountEmail` |
+| Logging GSA email | `GkeFluentBitAgent.gcpServiceAccountEmail` |
+| Monitoring GSA email | `GkeOtelCollector.gcpServiceAccountEmail` |
+| GCP Project ID | `GkeExternalDnsAgent.gcpProjectId`, `GkeFluentBitAgent.projectId`, `GkeOtelCollector.projectId` |
+| Cluster name | `GkeFluentBitAgent.clusterName`, `GkeOtelCollector.clusterName` |
+
+## GKE Init Template
+
+Scaffold a dual-lexicon GKE project:
+
+```bash
+chant init --lexicon gcp --template gke
+```
+
+This creates:
+- `src/infra/` — GKE cluster, node pool, service accounts, IAM (GCP lexicon)
+- `src/k8s/` — namespace, app, ingress, storage (K8s lexicon)
+- `package.json` with both `@intentius/chant-lexicon-gcp` and `@intentius/chant-lexicon-k8s`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gcp",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "license": "Apache-2.0",
   "type": "module",
   "files": [

package/src/codegen/naming.ts

@@ -109,7 +109,52 @@ const serviceAbbreviations: Record<string, string> = {
 const gcpNamingConfig: NamingConfig = {
   priorityNames,
   priorityAliases,
-  priorityPropertyAliases: {},
+  priorityPropertyAliases: {
+    "GCP::Compute::Instance": {
+      NetworkInterface: "InstanceNetworkInterface",
+      AccessConfig: "InstanceAccessConfig",
+      AttachedDisk: "InstanceAttachedDisk",
+      Metadata: "InstanceMetadata",
+      Scheduling: "InstanceScheduling",
+      ServiceAccount: "InstanceServiceAccount",
+      ShieldedInstanceConfig: "InstanceShieldedConfig",
+    },
+    "GCP::Container::Cluster": {
+      NetworkConfig: "ClusterNetworkConfig",
+      NodeConfig: "ClusterNodeConfig",
+      IpAllocationPolicy: "ClusterIpAllocationPolicy",
+      MasterAuth: "ClusterMasterAuth",
+      PrivateClusterConfig: "ClusterPrivateConfig",
+      AddonsConfig: "ClusterAddonsConfig",
+    },
+    "GCP::Container::NodePool": {
+      NodeConfig: "NodePoolNodeConfig",
+      AutoScaling: "NodePoolAutoScaling",
+      Management: "NodePoolManagement",
+      UpgradeSettings: "NodePoolUpgradeSettings",
+    },
+    "GCP::Sql::Instance": {
+      IpConfiguration: "SqlIpConfiguration",
+      BackupConfiguration: "SqlBackupConfiguration",
+      DatabaseFlags: "SqlDatabaseFlags",
+      Settings: "SqlSettings",
+    },
+    "GCP::Storage::Bucket": {
+      Encryption: "BucketEncryption",
+      Versioning: "BucketVersioning",
+      Lifecycle: "BucketLifecycle",
+      LifecycleRule: "BucketLifecycleRule",
+      Logging: "BucketLogging",
+      RetentionPolicy: "BucketRetentionPolicy",
+    },
+    "GCP::Compute::Network": {
+      RoutingConfig: "NetworkRoutingConfig",
+    },
+    "GCP::Compute::Subnetwork": {
+      LogConfig: "SubnetworkLogConfig",
+      SecondaryIpRange: "SubnetworkSecondaryIpRange",
+    },
+  },
   serviceAbbreviations,
   shortName: gcpShortName,
   serviceName: (typeName: string) => {

package/src/lint/post-synth/post-synth.test.ts

@@ -40,6 +40,7 @@ spec:
     const diags = wgc101.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC101");
+    expect(diags[0].severity).toBe("warning");
   });
 
   test("no diagnostic when encryption present", () => {
@@ -73,6 +74,7 @@ spec:
     const diags = wgc102.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC102");
+    expect(diags[0].severity).toBe("warning");
   });
 
   test("no diagnostic when no public members", () => {
@@ -103,6 +105,7 @@ spec:
     const diags = wgc103.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC103");
+    expect(diags[0].severity).toBe("info");
   });
 
   test("no diagnostic when project annotation present", () => {
@@ -134,6 +137,7 @@ spec:
     const diags = wgc104.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC104");
+    expect(diags[0].severity).toBe("warning");
   });
 
   test("no diagnostic when uniformBucketLevelAccess is true", () => {
@@ -169,6 +173,7 @@ spec:
     const diags = wgc105.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC105");
+    expect(diags[0].severity).toBe("warning");
   });
 
   test("no diagnostic with private networks only", () => {
@@ -203,6 +208,7 @@ spec:
     const diags = wgc106.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC106");
+    expect(diags[0].severity).toBe("info");
   });
 
   test("no diagnostic when deletion policy present", () => {
@@ -234,6 +240,7 @@ spec:
     const diags = wgc107.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC107");
+    expect(diags[0].severity).toBe("info");
   });
 
   test("no diagnostic when versioning enabled", () => {
@@ -267,6 +274,7 @@ spec:
     const diags = wgc108.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC108");
+    expect(diags[0].severity).toBe("warning");
   });
 
   test("no diagnostic when backup enabled", () => {
@@ -305,6 +313,7 @@ spec:
     const diags = wgc109.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC109");
+    expect(diags[0].severity).toBe("warning");
   });
 
   test("no diagnostic with specific source range", () => {
@@ -339,6 +348,7 @@ spec:
     const diags = wgc110.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC110");
+    expect(diags[0].severity).toBe("warning");
   });
 
   test("no diagnostic when rotation period set", () => {
@@ -369,6 +379,7 @@ spec:
     const diags = wgc201.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC201");
+    expect(diags[0].severity).toBe("info");
   });
 
   test("no diagnostic when managed-by label present", () => {
@@ -400,6 +411,7 @@ spec:
     const diags = wgc202.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC202");
+    expect(diags[0].severity).toBe("warning");
   });
 
   test("no diagnostic when workload identity configured", () => {
@@ -435,6 +447,7 @@ spec:
     const diags = wgc203.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC203");
+    expect(diags[0].severity).toBe("warning");
   });
 
   test("no diagnostic with specific scopes", () => {
@@ -470,6 +483,7 @@ spec:
     const diags = wgc204.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC204");
+    expect(diags[0].severity).toBe("info");
   });
 
   test("no diagnostic when shielded VM configured", () => {
@@ -504,6 +518,7 @@ spec:
     const diags = wgc301.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC301");
+    expect(diags[0].severity).toBe("info");
   });
 
   test("no diagnostic when IAMAuditConfig present", () => {
@@ -536,6 +551,7 @@ spec:
     const diags = wgc302.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC302");
+    expect(diags[0].severity).toBe("info");
   });
 
   test("no diagnostic when Service resource present", () => {
@@ -565,6 +581,7 @@ spec:
     const diags = wgc303.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC303");
+    expect(diags[0].severity).toBe("info");
   });
 
   test("no diagnostic when service perimeter present", () => {
@@ -596,6 +613,7 @@ spec:
     const diags = wgc111.check(makeCtx(yaml));
     expect(diags.length).toBeGreaterThanOrEqual(1);
     expect(diags[0].checkId).toBe("WGC111");
+    expect(diags[0].severity).toBe("warning");
   });
 
   test("no diagnostic when referenced resource exists", () => {

package/src/plugin.ts

@@ -322,6 +322,24 @@ export const bucket = new StorageBucket({
           },
         ],
       },
+      {
+        file: "chant-gke.md",
+        name: "chant-gke",
+        description: "GKE end-to-end workflow — bootstrap cluster, deploy Config Connector resources, deploy K8s workloads",
+        triggers: [
+          { type: "context" as const, value: "gke" },
+          { type: "context" as const, value: "gcp kubernetes" },
+          { type: "context" as const, value: "config connector" },
+        ],
+        parameters: [],
+        examples: [
+          {
+            title: "Deploy GKE microservice",
+            input: "Deploy a GKE project end-to-end",
+            output: "npm run bootstrap && npm run deploy",
+          },
+        ],
+      },
     ];
 
     for (const skill of skillFiles) {

package/src/serializer.test.ts

@@ -7,6 +7,7 @@ import {
   DEFAULT_LABELS_MARKER,
   DEFAULT_ANNOTATIONS_MARKER,
 } from "./default-labels";
+import { GCP } from "./pseudo";
 
 // ── Mock helpers ────────────────────────────────────────────────────
 
@@ -160,6 +161,50 @@ describe("gcpSerializer", () => {
     expect(result).toContain("cnrm.cloud.google.com/project-id: my-project");
   });
 
+  test("PseudoParameter in default annotations resolves to env var string", () => {
+    const prev = process.env.GCP_PROJECT_ID;
+    process.env.GCP_PROJECT_ID = "test-project-123";
+    try {
+      const entities = new Map<string, any>();
+      entities.set("annot", defaultAnnotations({ "cnrm.cloud.google.com/project-id": GCP.ProjectId }));
+      entities.set(
+        "bucket",
+        mockResource("GCP::Storage::Bucket", {
+          location: "US",
+        }),
+      );
+
+      const result = gcpSerializer.serialize(entities);
+      expect(result).toContain("cnrm.cloud.google.com/project-id: test-project-123");
+      expect(result).not.toContain("refName");
+      expect(result).not.toContain("Ref");
+    } finally {
+      if (prev === undefined) delete process.env.GCP_PROJECT_ID;
+      else process.env.GCP_PROJECT_ID = prev;
+    }
+  });
+
+  test("PseudoParameter in default annotations falls back when env var unset", () => {
+    const prev = process.env.GCP_PROJECT_ID;
+    delete process.env.GCP_PROJECT_ID;
+    try {
+      const entities = new Map<string, any>();
+      entities.set("annot", defaultAnnotations({ "cnrm.cloud.google.com/project-id": GCP.ProjectId }));
+      entities.set(
+        "bucket",
+        mockResource("GCP::Storage::Bucket", {
+          location: "US",
+        }),
+      );
+
+      const result = gcpSerializer.serialize(entities);
+      expect(result).toContain("cnrm.cloud.google.com/project-id: PROJECT_ID");
+    } finally {
+      if (prev === undefined) delete process.env.GCP_PROJECT_ID;
+      else process.env.GCP_PROJECT_ID = prev;
+    }
+  });
+
   test("explicit labels override default labels", () => {
     const entities = new Map<string, any>();
     entities.set("labels", defaultLabels({ env: "dev" }));

package/src/serializer.ts

@@ -12,6 +12,7 @@ import type { Serializer, SerializerResult } from "@intentius/chant/serializer";
 import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { emitYAML } from "@intentius/chant/yaml";
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
 import { isDefaultLabels, isDefaultAnnotations, type DefaultLabels, type DefaultAnnotations } from "./default-labels";
 
 const require = createRequire(import.meta.url);
@@ -170,10 +171,14 @@ export const gcpSerializer: Serializer = {
         metadata.labels = { ...defaultLabelEntries, ...existingLabels };
       }
 
-      // Merge default annotations
+      // Merge default annotations (resolve PseudoParameters to env-var strings)
       if (Object.keys(defaultAnnotationEntries).length > 0) {
+        const resolvedAnnotations: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(defaultAnnotationEntries)) {
+          resolvedAnnotations[k] = resolveAnnotationValue(v);
+        }
         const existingAnnotations = (metadata.annotations ?? {}) as Record<string, unknown>;
-        metadata.annotations = { ...defaultAnnotationEntries, ...existingAnnotations };
+        metadata.annotations = { ...resolvedAnnotations, ...existingAnnotations };
       }
 
       manifest.metadata = metadata;
@@ -197,6 +202,38 @@ export const gcpSerializer: Serializer = {
   },
 };
 
+/**
+ * Pseudo-parameter → environment variable mapping.
+ * Config Connector annotations must be plain strings, so PseudoParameters
+ * are resolved from environment variables at build time.
+ */
+const PSEUDO_ENV_MAP: Record<string, { envVar: string; fallback: string }> = {
+  "GCP::ProjectId": { envVar: "GCP_PROJECT_ID", fallback: "PROJECT_ID" },
+  "GCP::Region": { envVar: "GCP_REGION", fallback: "us-central1" },
+  "GCP::Zone": { envVar: "GCP_ZONE", fallback: "us-central1-a" },
+};
+
+/**
+ * Resolve an annotation value to a plain string.
+ * PseudoParameter intrinsics are resolved from environment variables;
+ * other values pass through unchanged.
+ */
+function resolveAnnotationValue(value: unknown): unknown {
+  if (typeof value === "object" && value !== null && INTRINSIC_MARKER in value) {
+    if ("toJSON" in value && typeof value.toJSON === "function") {
+      const json = value.toJSON() as Record<string, unknown>;
+      if (json && typeof json === "object" && "Ref" in json && typeof json.Ref === "string") {
+        const mapping = PSEUDO_ENV_MAP[json.Ref];
+        if (mapping) {
+          return process.env[mapping.envVar] ?? mapping.fallback;
+        }
+      }
+    }
+    return String(value);
+  }
+  return value;
+}
+
 /**
  * Emit a key-value pair as YAML.
  */

package/src/skills/chant-gke.md

@@ -0,0 +1,194 @@
+---
+skill: chant-gke
+description: End-to-end GKE workflow bridging GCP infrastructure and Kubernetes workloads
+user-invocable: true
+---
+
+# GKE End-to-End Workflow
+
+## Overview
+
+This skill bridges two lexicons:
+- **`@intentius/chant-lexicon-gcp`** — GKE cluster, node pool, service accounts, IAM bindings, Cloud DNS (Config Connector)
+- **`@intentius/chant-lexicon-k8s`** — Kubernetes workloads, Workload Identity, GCE Ingress, storage, observability (K8s YAML)
+
+## Architecture
+
+```
+GCP Lexicon (Config Connector)           K8s Lexicon (kubectl apply)
+┌─────────────────────────────┐         ┌─────────────────────────────────┐
+│ VPC + Subnets + Cloud NAT   │         │ NamespaceEnv (quotas)           │
+│ GKE Cluster + Node Pool     │         │ AutoscaledService (app)         │
+│ GCP Service Accounts        │──GSA──→ │ WorkloadIdentityServiceAccount  │
+│ IAM Policy Members          │         │ GCE Ingress + GkeExternalDns    │
+│ Cloud DNS Managed Zone      │         │ GcePdStorageClass               │
+└─────────────────────────────┘         │ GkeFluentBitAgent (logs)        │
+                                        │ GkeOtelCollector (traces)       │
+                                        └─────────────────────────────────┘
+```
+
+## Step 1: Bootstrap (one-time)
+
+Creates a GKE cluster with Config Connector enabled and configures Workload Identity:
+
+```bash
+export GCP_PROJECT_ID=<your-project>
+npm run bootstrap
+```
+
+This enables required APIs, creates the cluster, sets up a Config Connector service account with editor/IAM/DNS roles, and waits for the controller to be ready.
+
+## Step 2: Build
+
+```bash
+# Build Config Connector YAML
+chant build src --lexicon gcp -o config.yaml
+
+# Build K8s workload YAML
+chant build src --lexicon k8s -o k8s.yaml
+```
+
+Or use the combined script:
+
+```bash
+npm run build
+```
+
+## Step 3: Deploy Config Connector Resources
+
+```bash
+npm run deploy-infra
+# Applies config.yaml — Config Connector reconciles GCP resources
+```
+
+Key GCP resources created:
+- **GKE Cluster** — control plane with Workload Identity enabled
+- **Node Pool** — worker nodes
+- **GCP Service Accounts** — app SA, ExternalDNS SA, logging SA, monitoring SA
+- **IAM Policy Members** — Workload Identity bindings + role grants
+- **Cloud DNS Managed Zone** — for ExternalDNS
+
+## Step 4: Load Outputs
+
+```bash
+npm run load-outputs
+```
+
+Populates `.env` with GCP service account emails and DNS zone info from the live cluster. These values flow into K8s composite props via `config.ts`.
+
+## Step 5: Deploy K8s Workloads
+
+```bash
+npm run build:k8s    # Rebuild with real values from .env
+npm run apply        # kubectl apply -f k8s.yaml
+```
+
+### Key K8s composites for GKE
+
+```typescript
+import {
+  NamespaceEnv,
+  AutoscaledService,
+  WorkloadIdentityServiceAccount,
+  GkeExternalDnsAgent,
+  GcePdStorageClass,
+  GkeFluentBitAgent,
+  GkeOtelCollector,
+} from "@intentius/chant-lexicon-k8s";
+
+// 1. Namespace with quotas and network isolation
+const ns = NamespaceEnv({
+  name: "prod",
+  cpuQuota: "16",
+  memoryQuota: "32Gi",
+  defaultCpuRequest: "100m",
+  defaultMemoryRequest: "128Mi",
+  defaultDenyIngress: true,
+});
+
+// 2. Workload Identity ServiceAccount (use GSA email from Config Connector outputs)
+const wi = WorkloadIdentityServiceAccount({
+  name: "app-sa",
+  gcpServiceAccountEmail: "app@my-project.iam.gserviceaccount.com",  // from .env
+  namespace: "prod",
+});
+
+// 3. Application with autoscaling
+const app = AutoscaledService({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  maxReplicas: 10,
+  cpuRequest: "200m",
+  memoryRequest: "256Mi",
+  namespace: "prod",
+});
+
+// 4. ExternalDNS for Cloud DNS
+const dns = GkeExternalDnsAgent({
+  gcpServiceAccountEmail: "dns@my-project.iam.gserviceaccount.com",
+  gcpProjectId: "my-project",
+  domainFilters: ["example.com"],
+});
+
+// 5. Storage
+const storage = GcePdStorageClass({ name: "pd-balanced", type: "pd-balanced" });
+
+// 6. Observability
+const logging = GkeFluentBitAgent({
+  clusterName: "my-cluster",
+  projectId: "my-project",
+});
+
+const tracing = GkeOtelCollector({
+  clusterName: "my-cluster",
+  projectId: "my-project",
+});
+```
+
+## Step 6: Verify
+
+```bash
+npm run status
+kubectl get pods -n prod
+kubectl get ingress -n prod
+kubectl logs -n gke-logging -l app.kubernetes.io/name=fluent-bit
+```
+
+## Cleanup
+
+```bash
+npm run teardown
+```
+
+Delete order matters:
+1. **K8s workloads** — drains load balancers
+2. **Config Connector resources** — deletes GCP infra (SAs, IAM, DNS)
+3. **Config Connector SA** — the CC controller's own SA
+4. **GKE cluster** — the bootstrap cluster itself
+
+## Cross-Lexicon Value Flow
+
+Config Connector outputs flow into K8s composite props via `.env`:
+
+| Config Connector Output | K8s Composite Prop |
+|------------------------|-------------------|
+| App GSA email | `WorkloadIdentityServiceAccount.gcpServiceAccountEmail` |
+| ExternalDNS GSA email | `GkeExternalDnsAgent.gcpServiceAccountEmail` |
+| Logging GSA email | `GkeFluentBitAgent.gcpServiceAccountEmail` |
+| Monitoring GSA email | `GkeOtelCollector.gcpServiceAccountEmail` |
+| GCP Project ID | `GkeExternalDnsAgent.gcpProjectId`, `GkeFluentBitAgent.projectId`, `GkeOtelCollector.projectId` |
+| Cluster name | `GkeFluentBitAgent.clusterName`, `GkeOtelCollector.clusterName` |
+
+## GKE Init Template
+
+Scaffold a dual-lexicon GKE project:
+
+```bash
+chant init --lexicon gcp --template gke
+```
+
+This creates:
+- `src/infra/` — GKE cluster, node pool, service accounts, IAM (GCP lexicon)
+- `src/k8s/` — namespace, app, ingress, storage (K8s lexicon)
+- `package.json` with both `@intentius/chant-lexicon-gcp` and `@intentius/chant-lexicon-k8s`