docs(schema): document builder cache mode

documentation-metadata.json

@@ -123,6 +123,13 @@
         "helm-charts": "6aff91c22411e641964774bcbb09e5265ac1250c"
       },
       "notes": "Sites soft delete, restore, Recently deleted view, deleted-site retention setting, MCP hosted site write tools, and creator-or-admin Environment teardown merged and deployed. Live-verified: delete then restore through UI, CLI 0.6.0, and MCP; deleted public sites return 404; cleanup purges after retention."
+    },
+    "2026-10-21-build-cache-mode-released": {
+      "verifiedOn": "2026-10-21",
+      "sources": {
+        "lifecycle": "bc9dc7dfb5511161e2bf744580815551ebf28561"
+      },
+      "notes": "Lifecycle 0.2.3-alpha.45 (merge of docker.builder.cache.mode). Verified the schema enum (max, min, off, no other cache keys), BuildKit export and import flags per mode, Kaniko cache flags removed only for off, and no effect for the ci engine. Other claims on these pages carry over from 2026-07-24-comprehensive-audit."
     }
   }
 }

documentation-style-baseline.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 3,
-  "updatedOn": "2026-10-12",
+  "updatedOn": "2026-10-21",
   "references": {
     "canonical": "ASD-STE100 Issue 9",
     "canonicalRules": [
@@ -351,14 +351,14 @@
     "/docs/schema/github": {
       "file": "src/pages/docs/schema/github.mdx",
       "profile": "asd-ste100",
-      "reviewedOn": "2026-07-25",
-      "sha256": "6d90c58a426518bc34d557468d91c80088ad64a6784c16eb692bd91c292fd6f3"
+      "reviewedOn": "2026-10-21",
+      "sha256": "41da652e5fbfbbcd3fc9613ae40d38f45ee6eed658b5702453678a0c5983f26b"
     },
     "/docs/schema/helm": {
       "file": "src/pages/docs/schema/helm.mdx",
       "profile": "asd-ste100",
-      "reviewedOn": "2026-07-25",
-      "sha256": "8e15742511246d8df0a91df004ccbd5b376fa9add9ec5bf1f8123cf0832e9a1d"
+      "reviewedOn": "2026-10-21",
+      "sha256": "5d91ca9765e848ccdc3a03909de73c418eba175ecbc7dba7fe01911f08920566"
     },
     "/docs/schema/overview": {
       "file": "src/pages/docs/schema/overview.mdx",

public/llms.txt

@@ -58,9 +58,9 @@ This index is generated from the human documentation. Follow the linked page for
 - [Schema overview](https://uselifecycle.com/docs/schema/overview.md): Understand the lifecycle.yaml configuration file and its structure. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
 - [Environment configuration](https://uselifecycle.com/docs/schema/environment.md): Configure deployment behavior, Service groups, and automation for ephemeral Environments. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
 - [Webhook configuration](https://uselifecycle.com/docs/schema/webhooks.md): Configure webhooks that start automated actions after Environment events. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
-- [GitHub Service](https://uselifecycle.com/docs/schema/github.md): Build and deploy Services from GitHub repositories with Docker. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [GitHub Service](https://uselifecycle.com/docs/schema/github.md): Build and deploy Services from GitHub repositories with Docker. _(audience: application-developer; last verified: 2026-10-21; baseline: 2026-10-21-build-cache-mode-released)_
 - [Docker Service](https://uselifecycle.com/docs/schema/docker.md): Deploy pre-built Docker images for databases, caches, and other infrastructure components. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
-- [Helm Service](https://uselifecycle.com/docs/schema/helm.md): Deploy Services with local, OCI, or public Helm charts. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
+- [Helm Service](https://uselifecycle.com/docs/schema/helm.md): Deploy Services with local, OCI, or public Helm charts. _(audience: application-developer; last verified: 2026-10-21; baseline: 2026-10-21-build-cache-mode-released)_
 - [Codefresh Service](https://uselifecycle.com/docs/schema/codefresh.md): Trigger external Codefresh pipelines for deployment and teardown. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
 - [Aurora Restore Service](https://uselifecycle.com/docs/schema/aurora-restore.md): Make an AWS Aurora point-in-time copy for an ephemeral Environment. _(audience: application-developer; last verified: 2026-07-24; baseline: 2026-07-24-comprehensive-audit)_
 - [Configuration Service](https://uselifecycle.com/docs/schema/configuration.md): Deploy configuration-only Services for feature flags and shared configuration. _(audience: application-developer; last verified: 2026-08-01; baseline: 2026-08-01-configuration-schema-fix)_

src/pages/docs/schema/github.mdx

@@ -3,8 +3,8 @@ title: GitHub Service
 description: Build and deploy Services from GitHub repositories with Docker.
 audience:
   - application-developer
-lastVerified: "2026-07-24"
-verificationBaseline: "2026-07-24-comprehensive-audit"
+lastVerified: "2026-10-21"
+verificationBaseline: "2026-10-21-build-cache-mode-released"
 contentProfile: asd-ste100
 tags:
   - schema
@@ -96,6 +96,8 @@ services:
         defaultTag: "main"
         builder:
           engine: "buildkit" # Options: buildkit, kaniko, ci
+          cache: # Optional - build cache behavior
+            mode: "max" # Options: max, min, off
           resources: # Optional - custom CPU/memory for the build job
             requests:
               cpu: "1"
@@ -180,6 +182,7 @@ Configuration for the Docker build operation.
 | Field                | Type                    | Description                                          |
 | -------------------- | ----------------------- | ---------------------------------------------------- |
 | `engine`             | string                  | Build engine: `buildkit`, `kaniko`, or `ci`          |
+| `cache.mode`         | string                  | Build cache mode: `max`, `min`, or `off`             |
 | `resources.requests` | object                  | Minimum CPU/memory guaranteed for the build job      |
 | `resources.limits`   | object                  | Maximum CPU/memory allowed for the build job         |
 | `podAnnotations`     | `Record<string,string>` | Custom annotations applied to the build pod template |
@@ -229,6 +232,42 @@ services:
           dockerfilePath: "Dockerfile"
 ```
 
+### docker.builder.cache
+
+The `cache.mode` field sets how BuildKit uses the build cache:
+
+- `max` - BuildKit exports the cache for all build steps.
+- `min` - BuildKit exports the cache only for the layers of the final image.
+- `off` - BuildKit does not export or import a cache.
+
+With `max` or `min`, BuildKit also imports the cache that it exported before.
+
+If you do not set `mode`, Lifecycle uses the installation default. This default
+is `max` if an administrator did not change it.
+
+If the image is large, BuildKit can be slow when it exports the cache for all
+build steps. If the next builds use only a small part of that cache, set `mode`
+to `min`. If the cache does not make builds faster, set `mode` to `off`.
+
+For the `kaniko` engine, only `off` has an effect. With `off`, Kaniko does not
+use a cache. The `ci` engine does not use `cache.mode`.
+
+```yaml filename="lifecycle.yaml"
+services:
+  - name: "api"
+    github:
+      repository: "myorg/api"
+      branchName: "main"
+      docker:
+        defaultTag: "main"
+        builder:
+          engine: "buildkit"
+          cache:
+            mode: "min" # Options: max, min, off
+        app:
+          dockerfilePath: "Dockerfile"
+```
+
 ### docker.app (required)
 
 Configuration for the main application container:

src/pages/docs/schema/helm.mdx

@@ -3,8 +3,8 @@ title: Helm Service
 description: Deploy Services with local, OCI, or public Helm charts.
 audience:
   - application-developer
-lastVerified: "2026-07-24"
-verificationBaseline: "2026-07-24-comprehensive-audit"
+lastVerified: "2026-10-21"
+verificationBaseline: "2026-10-21-build-cache-mode-released"
 contentProfile: asd-ste100
 tags:
   - schema
@@ -245,10 +245,13 @@ The default Docker image tag, typically matching the branch name.
 Configuration for the Docker build operation. See [GitHub Service
 docker.builder](/docs/schema/github#dockerbuilder) for the full field list. That
 section includes the `resources` field and the `safe-to-evict` pod annotation.
+For the cache modes, see [GitHub Service
+docker.builder.cache](/docs/schema/github#dockerbuildercache).
 
 | Field                | Type                    | Description                                          |
 | -------------------- | ----------------------- | ---------------------------------------------------- |
 | `engine`             | string                  | Build engine: `buildkit`, `kaniko`, or `ci`          |
+| `cache.mode`         | string                  | Build cache mode: `max`, `min`, or `off`             |
 | `resources.requests` | object                  | Minimum CPU/memory guaranteed for the build job      |
 | `resources.limits`   | object                  | Maximum CPU/memory allowed for the build job         |
 | `podAnnotations`     | `Record<string,string>` | Custom annotations applied to the build pod template |