From ad46084e46874d5be183518e5e4363559b3511a4 Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Fri, 25 Mar 2022 14:37:42 -0400
Subject: [PATCH 01/31] Add terminology section to the buildpack spec

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 buildpack.md | 61 +++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 46 insertions(+), 15 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index 9f8b6e72..a4f332e7 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -2,17 +2,6 @@
 
 This document specifies the interface between a lifecycle program and one or more buildpacks.
 
-The lifecycle program uses buildpacks to build software artifacts from source code and pack the result into an OCI image.
-
-This is accomplished in four phases:
-
-1. **Detection,** where an optimal selection of compatible buildpacks is chosen.
-2. **Analysis,** where metadata about OCI layers generated during a previous build are made available to buildpacks.
-3. **Build,** where buildpacks use that metadata to generate only the OCI layers that need to be replaced.
-4. **Export,** where the remote layers are replaced by the generated layers.
-
-The `ENTRYPOINT` of the OCI image contains logic implemented by the lifecycle that executes during the **Launch** phase.
-
 ## Table of Contents
 
 <!-- Using https://github.com/yzhang-gh/vscode-markdown to manage toc -->
@@ -91,6 +80,50 @@ Buildpack API versions:
  - `<major>` and `<minor>` MUST only contain numbers (unsigned 64 bit integer)
  - When `<major>` is greater than `0` increments to `<minor>` SHALL exclusively indicate additive changes
 
+## Terminology
+
+### CNB Terminology
+
+A **buildpack** is a directory containing a `buildpack.toml`.
+
+A **buildpack group**, or **group**, is a list of one or more buildpacks that are designed to work together - for example, a buildpack that provides `node` and a buildpack that provides `npm`.
+
+An **order** is a list of one or more groups to be tested against application source code, so that the appropriate group for a build can be determined. 
+
+An **executable buildpack** is a buildpack containing `/bin/detect` and `/bin/build` executables.
+
+An **order buildpack** is a buildpack containing an order definition in `buildpack.toml`. Order buildpacks do not contain `/bin/detect` or `/bin/build` executables.
+
+**Resolving an order** is the process by which an order (which may contain order buildpacks) is evaluated together with application source code to produce a group of executable buildpacks that can be used to build the application. This process is known as **detection**. During detection, the `/bin/detect` executable for each executable buildpack is invoked, and the group that is returned is the first group where `/bin/detect` returns true for all non-optional executable buildpacks.
+
+A **lifecycle** is software that orchestrates a build. It executes in a series of phases that each have a distinct responsibility:
+  1. **Detection,** where an optimal selection of compatible buildpacks is chosen by resolving the provided order.
+  2. **Analysis,** where metadata about OCI layers generated during a previous build are made available to executable buildpacks in the selected group.
+  3. **Build,** where the `bin/build` for each executable buildpack in the selected group is invoked, in order, to build the application.
+  4. **Export,** where filesystem changes from the build phase are packaged into layers in an OCI image.
+
+A **launcher** is software contributed by the lifecycle as the `ENTRYPOINT` of the exported OCI image that is used to start processes at runtime.
+
+**Launch** describes the process of running an application by creating a container from the exported OCI image.
+
+A **platform** is a system or software that orchestrates the lifecycle by invoking each lifecycle phase in order.
+
+A **process type** is a definition, provided by executable buildpacks during the build phase, of a process to launch at runtime.
+
+A **build plan** is a file used during detection, in which each executable buildpack may express the dependencies that it requires and the dependencies that it provides. A group of executable buildpacks will only pass detection if a valid build plan can be produced from the dependencies that all executable buildpacks in the group require and provide. A valid build plan is a plan where all required dependencies are provided in the necessary order, meaning that during the build phase, each executable buildpack will have its required dependencies provided by an executable buildpack that runs before it.
+
+A **buildpack plan** is a file unique to each executable buildpack, used during the build phase to communicate the dependencies that the executable buildpack is expected to provide.
+
+An **application directory** is a directory containing application source code. Executable buildpacks may make changes to the application directory during the build phase.
+
+A **layer** is a set of filesystem changes packaged according to the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/layer.md).
+
+A **layer directory** is a directory created by an executable buildpack that contains build and/or runtime dependencies, or is used to configure the build and/or runtime environment. If designated for launch, the layer directory will be added as a layer in the exported OCI image.
+
+A **stack** is a contract, implemented by a **build image** and **run image**, that guarantees properties of the **build environment** and **app image**. The provided stack is communicated to executable buildpacks through the `CNB_STACK_ID` environment variable, enabling each executable buildpack to modify its behavior when executed on different stacks.
+
+A **mixin** is a named set of additions to a stack that can be used to make additive changes to the contract. Buildpacks can express their required mixins in `buildpack.toml`.
+
 ## Buildpack Interface
 
 The following specifies the interface implemented by executables in each buildpack.
@@ -99,7 +132,7 @@ The lifecycle MUST invoke these executables as described in the Phase sections.
 ### Buildpack API Compatibility
 Given a buildpack declaring `<buildpack API Version>` in its [`buildpack.toml`](#buildpacktoml-toml), the lifecycle:
 - MUST either conform to the matching version of this specification when interfacing with the buildpack or
-- return an error to the platform if it does not support `<buildpack API Version>`
+- MUST return an error to the platform if it does not support `<buildpack API Version>`
 
 The lifecycle MAY return an error to the platform if two or more buildpacks within a group declare buildpack API versions that the lifecycle cannot support together within a single build, even if both are supported independently.
 
@@ -132,7 +165,6 @@ Executable: `/bin/detect <platform[AR]> <plan[E]>`, Working Dir: `<app[AR]>`
 | Standard error     | Logs (warnings, errors)
 | `<plan>`           | Contributions to the the Build Plan (TOML)
 
-
 ###  Build
 
 Executable: `/bin/build <layers[EIC]> <platform[AR]> <plan[ER]>`, Working Dir: `<app[AI]>`
@@ -462,7 +494,7 @@ After analysis, the lifecycle MUST proceed to the build phase.
 
 ### Purpose
 
-The purpose of build is to transform application source code into runnable artifacts that can be packaged into a container.
+The purpose of build is to transform application source code into runnable artifacts that can be packaged into a container image.
 
 During the build phase, typical buildpacks might:
 
@@ -1020,7 +1052,6 @@ For a given layer, the buildpack MAY specify:
 - Whether the layer is cached, intended for build, and/or intended for launch.
 - Metadata that describes the layer contents.
 
-
 ### buildpack.toml (TOML)
 This section describes the 'Buildpack descriptor'.
 

From 7578a07e1f4012ff98377e9077bf5dbbda30e5ec Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Fri, 25 Mar 2022 14:59:48 -0400
Subject: [PATCH 02/31] Add information about layer types

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 buildpack.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/buildpack.md b/buildpack.md
index a4f332e7..a826c27e 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -118,7 +118,11 @@ An **application directory** is a directory containing application source code.
 
 A **layer** is a set of filesystem changes packaged according to the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/layer.md).
 
-A **layer directory** is a directory created by an executable buildpack that contains build and/or runtime dependencies, or is used to configure the build and/or runtime environment. If designated for launch, the layer directory will be added as a layer in the exported OCI image.
+A **layer directory** is a directory created by an executable buildpack that contains build and/or runtime dependencies, and can be used to configure the build and/or runtime environment. There are three **layer types**:
+  * a **launch layer** is added as a layer in the exported OCI image; it can be re-used on the next build (the lifecycle can avoid re-uploading it) if the executable buildpack that created the layer has the same requirements on the next build
+  * a **cache layer** is saved to the cache and its contents are restored on the next build
+  * a **build layer** contains child directories with paths that are added to the environment (e.g., `PATH`, `LD_LIBRARY_PATH`, etc.) for subsequent buildpacks in the same build
+Any combination of the three layer types are valid for a particular layer directory.
 
 A **stack** is a contract, implemented by a **build image** and **run image**, that guarantees properties of the **build environment** and **app image**. The provided stack is communicated to executable buildpacks through the `CNB_STACK_ID` environment variable, enabling each executable buildpack to modify its behavior when executed on different stacks.
 

From ff54426f2f5502907be748d2417c5834e56f3686 Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Fri, 15 Apr 2022 10:54:57 -0400
Subject: [PATCH 03/31] Updates per PR feedback

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 buildpack.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index a826c27e..7bcd7a70 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -84,7 +84,7 @@ Buildpack API versions:
 
 ### CNB Terminology
 
-A **buildpack** is a directory containing a `buildpack.toml`.
+A **buildpack** is a directory containing a `buildpack.toml`. A buildpack analyzes application source code and determines the best way to build it.
 
 A **buildpack group**, or **group**, is a list of one or more buildpacks that are designed to work together - for example, a buildpack that provides `node` and a buildpack that provides `npm`.
 
@@ -102,7 +102,7 @@ A **lifecycle** is software that orchestrates a build. It executes in a series o
   3. **Build,** where the `bin/build` for each executable buildpack in the selected group is invoked, in order, to build the application.
   4. **Export,** where filesystem changes from the build phase are packaged into layers in an OCI image.
 
-A **launcher** is software contributed by the lifecycle as the `ENTRYPOINT` of the exported OCI image that is used to start processes at runtime.
+A **launcher** is an executable that is the `ENTRYPOINT` of the exported OCI image. It is used to start processes at runtime. Having a launcher enables multiple process types to be defined on an image, with process-specific environment variables and other functionality.
 
 **Launch** describes the process of running an application by creating a container from the exported OCI image.
 
@@ -120,7 +120,7 @@ A **layer** is a set of filesystem changes packaged according to the [OCI Image
 
 A **layer directory** is a directory created by an executable buildpack that contains build and/or runtime dependencies, and can be used to configure the build and/or runtime environment. There are three **layer types**:
   * a **launch layer** is added as a layer in the exported OCI image; it can be re-used on the next build (the lifecycle can avoid re-uploading it) if the executable buildpack that created the layer has the same requirements on the next build
-  * a **cache layer** is saved to the cache and its contents are restored on the next build
+  * a **cache layer** is saved to the cache and its contents may be restored on the next build
   * a **build layer** contains child directories with paths that are added to the environment (e.g., `PATH`, `LD_LIBRARY_PATH`, etc.) for subsequent buildpacks in the same build
 Any combination of the three layer types are valid for a particular layer directory.
 

From 9a5955f464926d9d1bf79cc12d2fb5ce3e2428f2 Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Fri, 15 Apr 2022 15:48:33 -0400
Subject: [PATCH 04/31] Buildpack api changes to support phase 1 of Dockerfiles
 implementation

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 buildpack.md       | 111 +++++++++++++++++++++++----------------
 image_extension.md | 126 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 193 insertions(+), 44 deletions(-)
 create mode 100644 image_extension.md

diff --git a/buildpack.md b/buildpack.md
index 38cfef17..b37fe8fc 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -4,12 +4,13 @@ This document specifies the interface between a lifecycle program and one or mor
 
 The lifecycle program uses buildpacks to build software artifacts from source code and pack the result into an OCI image.
 
-This is accomplished in four phases:
+This is accomplished in five phases:
 
-1. **Detection,** where an optimal selection of compatible buildpacks is chosen.
-2. **Analysis,** where metadata about OCI layers generated during a previous build are made available to buildpacks.
-3. **Build,** where buildpacks use that metadata to generate only the OCI layers that need to be replaced.
-4. **Export,** where the remote layers are replaced by the generated layers.
+1. **Detection**, where an optimal selection of compatible buildpacks is chosen.
+1. **Analysis**, where metadata about OCI layers generated during a previous build are made available to buildpacks.
+1. **Generation** (optional, see the [Image Extension Interface](image-extension.md)), where image extensions generate Dockerfiles that can be used to select the runtime base image.
+1. **Build**, where buildpacks use analyzed metadata to generate only the OCI layers that need to be replaced.
+1. **Export**, where the remote layers are replaced by the generated layers.
 
 The `ENTRYPOINT` of the OCI image contains logic implemented by the lifecycle that executes during the **Launch** phase.
 
@@ -34,25 +35,29 @@ The `ENTRYPOINT` of the OCI image contains logic implemented by the lifecycle th
   - [Phase #1: Detection](#phase-1-detection)
     - [Purpose](#purpose)
     - [Process](#process)
+      - [Mixin Satisfaction](#mixin-satisfaction)
       - [Order Resolution](#order-resolution)
   - [Phase #2: Analysis](#phase-2-analysis)
     - [Purpose](#purpose-1)
     - [Process](#process-1)
-  - [Phase #3: Build](#phase-3-build)
+  - [Phase #3: Generation (optional)](#phase-3-generation-optional)
     - [Purpose](#purpose-2)
     - [Process](#process-2)
+  - [Phase #4: Build](#phase-4-build)
+    - [Purpose](#purpose-3)
+    - [Process](#process-3)
       - [Unmet Buildpack Plan Entries](#unmet-buildpack-plan-entries)
-      - [Software Bill of Materials](#software-bill-of-materials)
+      - [Software-Bill-of-Materials](#software-bill-of-materials)
       - [Layers](#layers)
         - [Providing Layers](#providing-layers)
         - [Reusing Layers](#reusing-layers)
         - [Slice Layers](#slice-layers)
-  - [Phase #4: Export](#phase-4-export)
-    - [Purpose](#purpose-3)
-    - [Process](#process-3)
-  - [Launch](#launch)
+  - [Phase #5: Export](#phase-5-export)
     - [Purpose](#purpose-4)
     - [Process](#process-4)
+  - [Launch](#launch)
+    - [Purpose](#purpose-5)
+    - [Process](#process-5)
   - [Environment](#environment)
     - [Provided by the Lifecycle](#provided-by-the-lifecycle)
       - [Layer Paths](#layer-paths)
@@ -79,8 +84,10 @@ The `ENTRYPOINT` of the OCI image contains logic implemented by the lifecycle th
       - [Order Buildpacks](#order-buildpacks)
     - [Exec.d Output (TOML)](#execd-output-toml)
   - [Deprecations](#deprecations)
-    - [`0.3`](#03)
-      - [Build Plan (TOML) `requires.version` Key](#build-plan-toml-requiresversion-key)
+    - [Positional Arguments to `detect` and `build` Executables](#positional-arguments-to-detect-and-build-executables)
+    - [launch.toml (TOML) `bom` Array](#launchtoml-toml-bom-array)
+    - [build.toml (TOML) `bom` Array](#buildtoml-toml-bom-array)
+    - [Build Plan (TOML) `requires.version` Key](#build-plan-toml-requiresversion-key)
 
 ## Buildpack API Version
 This document specifies Buildpack API version `0.8`
@@ -134,7 +141,6 @@ Executable: `/bin/detect`, Working Dir: `<app[AR]>`
 | Standard error         | Logs (warnings, errors)                     |
 | `$CNB_BUILD_PLAN_PATH` | Contributions to the the Build Plan (TOML)  |
 
-
 ###  Build
 
 Executable: `/bin/build`, Working Dir: `<app[AI]>`
@@ -306,36 +312,37 @@ At the end of each individual buildpack's build phase:
 
 ### Purpose
 
-The purpose of detection is to find an ordered group of buildpacks to use during the build phase.
-These buildpacks must be compatible with the app.
+The purpose of detection is to find an ordered group of image extensions and executable buildpacks to use during the generation and build phases.
+
+For detect requirements that are specific to image extensions, see the [Image Extension Interface](image-extension.md).
 
 ### Process
 
 **GIVEN:**
-- An ordered list of buildpack groups resolved into buildpack implementations as described in [Order Resolution](#order-resolution)
+- An ordered list of resolved groups as described in [Order Resolution](#order-resolution)
 - A directory containing application source code
 - A shell, if needed,
 
-For each buildpack in each group in order, the lifecycle MUST execute `/bin/detect`.
+For each image extension ("extension") or executable buildpack ("buildpack") in each group in order, the lifecycle MUST execute `/bin/detect`. Image extensions MUST always be optional during detection.
 
-1. **If** the exit status of `/bin/detect` is non-zero and the buildpack is not marked optional, \
+1. **If** the exit status of a buildpack `/bin/detect` is non-zero and the buildpack is not marked optional, \
    **Then** the lifecycle MUST proceed to the next group or fail detection completely if no more groups are present.
 
-2. **If** the exit status of `/bin/detect` is zero or the buildpack is marked optional,
-   1. **If** the buildpack is not the last buildpack in the group, \
-      **Then** the lifecycle MUST proceed to the next buildpack in the group.
+2. **If** the exit status of `/bin/detect` is zero or the extension or buildpack is marked optional,
+   1. **If** the extension or buildpack is not the last in the group, \
+      **Then** the lifecycle MUST proceed to the next extension or buildpack in the group.
 
-   2. **If** the buildpack is the last buildpack in the group,
-      1. **If** no exit statuses from `/bin/detect` in the group are zero \
+   2. **If** the extension or buildpack is the last in the group,
+      1. **If** no exit statuses from buildpack `/bin/detect` in the group are zero \
          **Then** the lifecycle MUST proceed to the next group or fail detection completely if no more groups are present.
 
-      2. **If** at least one exit status from `/bin/detect` in the group is zero \
-         **Then** the lifecycle MUST select this group and proceed to the analysis phase.
+      2. **If** at least one exit status from a buildpack `/bin/detect` in the group is zero \
+         **Then** the lifecycle MUST select this group and MAY proceed to the generation phase.
 
-The selected group MUST be filtered to only include buildpacks with exit status zero.
-The order of the buildpacks in the group MUST otherwise be preserved.
+The selected group MUST be filtered to only include extensions and buildpacks with exit status zero.
+The order of the extensions and buildpacks in the group MUST otherwise be preserved.
 
-The `/bin/detect` executable in each buildpack, when executed:
+The `/bin/detect` executable in each extension or buildpack, when executed:
 
 - MAY read the app directory.
 - MAY read the detect environment as described in the [Environment](#environment) section.
@@ -349,23 +356,26 @@ Each `requires` and `provides` section MUST be a list of entries formatted as de
 
 Each pairing of `requires` and `provides` sections (at the top level, or inside of an `or` array) is a potential Build Plan.
 
-For a given buildpack group, a sequence of trials is generated by selecting a single potential Build Plan from each buildpack in a left-to-right, depth-first order.
+For a given group, a sequence of trials is generated by selecting a single potential Build Plan from each extension or buildpack in a left-to-right, depth-first order.
 The group fails to detect if all trials fail to detect.
 
 For each trial,
 - If a required buildpack provides a dependency that is not required by the same buildpack or a subsequent buildpack, the trial MUST fail to detect.
 - If a required buildpack requires a dependency that is not provided by the same buildpack or a previous buildpack, the trial MUST fail to detect.
 - If an optional buildpack provides a dependency that is not required by the same buildpack or a subsequent buildpack, the optional buildpack MUST be excluded from the build phase and its requires and provides MUST be excluded from the Build Plan.
+- If an extension provides a dependency that is not required by a subsequent buildpack, the extension MUST be excluded from the build phase and its provides MUST be excluded from the Build Plan.
 - If an optional buildpack requires a dependency that is not provided by the same buildpack or a previous buildpack, the optional buildpack MUST be excluded from the build phase and its requires and provides MUST be excluded from the Build Plan.
 - Multiple buildpacks MAY require or provide the same dependency.
+- Multiple extensions MAY provide the same dependency.
 
 The lifecycle MAY execute each `/bin/detect` within a group in parallel.
 
-The lifecycle MUST run `/bin/detect` for all buildpacks in a group in a container using common stack with a common set of mixins.
-The lifecycle MUST fail detection if any of those buildpacks does not list that stack in `buildpack.toml`.
-The lifecycle MUST fail detection if any of those buildpacks specifies a mixin associated with that stack in `buildpack.toml` that is not satisfied, see [Mixin Satisfaction](#mixin-satisfaction) below.
+The lifecycle MUST run `/bin/detect` for all extensions and buildpacks in a group in a container using common stack with a common set of mixins.
+The lifecycle MUST fail detection if any of the buildpacks does not list that stack in `buildpack.toml`.
+The lifecycle MUST fail detection if any of the buildpacks specifies a mixin associated with that stack in `buildpack.toml` that is not satisfied, see [Mixin Satisfaction](#mixin-satisfaction) below.
 
 #### Mixin Satisfaction
+
 A buildpack's mixin requirements must be satisfied by the stack in one of the following scenarios.
 
 1) the stack provides the mixin `run:<mixin>` and the buildpack requires `run:<mixin>`
@@ -378,13 +388,17 @@ A buildpack's mixin requirements must be satisfied by the stack in one of the fo
 
 #### Order Resolution
 
-During detection, an order definition MUST be resolved into individual buildpack implementations.
+During detection, an order definition for image extensions (if present) and an order definition for buildpacks MUST be resolved into a group of image extensions and executable buildpacks.
+
+Order definitions for image extensions MUST NOT contain nested orders.
+
+If an order definition for image extensions is present, it MUST be prepended to the order definition for buildpacks before the resolution process occurs.
 
 The resolution process MUST follow this pattern:
 
 Where:
-- O and P are buildpack orders.
-- A through H are buildpack implementations.
+- O and P are image extension or buildpack orders.
+- A through H are image extensions or executable buildpacks.
 
 Given:
 
@@ -461,7 +475,17 @@ For each buildpack in the group, the lifecycle
 
 After analysis, the lifecycle MUST proceed to the build phase.
 
-## Phase #3: Build
+## Phase #3: Generation (optional)
+
+### Purpose
+
+The purpose of the generation phase is to generate Dockerfiles that can be used to select the runtime base image.
+
+### Process
+
+See the [Image Extension Specification](#image-extension.md).
+
+## Phase #4: Build
 
 ![Build](img/build.svg)
 
@@ -549,14 +573,14 @@ Correspondingly, each `/bin/build` executable:
 
 #### Unmet Buildpack Plan Entries
 
-A buildpack SHOULD designate a Buildpack Plan entry as unmet if the buildpack did not satisfy the requirement described by the entry.
+An image extension or executable buildpack SHOULD designate a Buildpack Plan entry as unmet if it did not satisfy the requirement described by the entry.
 The lifecycle SHALL assume that all entries in the Buildpack Plan were satisfied by the buildpack unless the buildpack writes an entry with the given name to the `unmet` section of `build.toml`.
 
 For each entry in `<plan>`:
   - **If** there is an unmet entry in `build.toml` with a matching `name`, the lifecycle
-    - MUST include the entry in the `<plan>` of the next buildpack that provided an entry with that name during the detection phase.
+    - MUST include the entry in the `<plan>` of the next image extension or executable buildpack that provided an entry with that name during the detection phase.
   - **Else**, the lifecycle
-    - MUST NOT include entries with matching names in the `<plan>` provided to subsequent buildpacks.
+    - MUST NOT include entries with matching names in the `<plan>` provided to subsequent image extensions or executable buildpacks.
 
 #### Software-Bill-of-Materials
 
@@ -612,7 +636,7 @@ Additionally, a buildpack MAY specify sub-paths within `<app>` as `slices` in `l
 Separate layers MUST be created during the export phase for each slice with one or more files or directories.
 This minimizes data transfer when the app directory contains a known set of files.
 
-## Phase #4: Export
+## Phase #5: Export
 
 ![Export](img/export.svg)
 
@@ -877,7 +901,7 @@ Prohibited:
 
 ### Requirements
 
-The lifecycle MUST be implemented so that the detection and build phases do not have access to OCI image store credentials used in the analysis and export phases.
+The lifecycle MUST be implemented so that the detection, generation, and build phases do not have access to OCI image store credentials used in the analysis and export phases.
 The lifecycle SHOULD be implemented so that each phase may run in a different container.
 
 ## Data Format
@@ -1099,7 +1123,7 @@ Each stack in `stacks` either:
 
 #### Order Buildpacks
 
-A buildpack descriptor that specifies `order` MUST be [resolvable](#order-resolution) into an ordering of buildpacks that implement the [Buildpack Interface](#buildpack-interface).
+A buildpack that specifies `order` in its `buildpack.toml` MUST be [resolvable](#order-resolution) into an ordering of executable buildpacks that implement the [Buildpack Interface](#buildpack-interface). The `order` MUST include only executable buildpacks and MUST NOT include image extensions.
 
 A buildpack reference inside of a `group` MUST contain an `id` and `version`.
 
@@ -1120,7 +1144,6 @@ Each `key`:
 ## Deprecations
 This section describes all the features that are deprecated.
 
-
 ### Positional Arguments to `detect` and `build` Executables
 
 _Deprecated in Buildpack API 0.8._
diff --git a/image_extension.md b/image_extension.md
new file mode 100644
index 00000000..0ce4f0a4
--- /dev/null
+++ b/image_extension.md
@@ -0,0 +1,126 @@
+# Image Extension Interface Specification
+
+This document specifies the interface between a lifecycle program and one or more image extensions.
+
+The lifecycle program uses image extensions to generate Dockerfiles that can be used to select the runtime base image prior to buildpack builds.
+
+## Table of Contents
+
+<!-- Using https://github.com/yzhang-gh/vscode-markdown to manage toc -->
+- [Image Extension Interface Specification](#image-extension-interface-specification)
+  - [Table of Contents](#table-of-contents)
+  - [Image Extension API Version](#image-extension-api-version)
+  - [Image Extension Interface](#image-extension-interface)
+    - [Detection](#detection)
+    - [Generation](#generation)
+  - [Phase: Generation](#phase-generation)
+    - [Purpose](#purpose)
+    - [Process](#process)
+      - [Dockerfile Requirements](#dockerfile-requirements)
+  - [Data Format](#data-format)
+    - [Files](#files)
+    - [extension.toml (TOML)](#extensiontoml-toml)
+
+## Image Extension API Version
+
+This document accompanies Buildpack API version `0.9`.
+
+## Image Extension Interface
+
+Unless otherwise noted, image extensions are expected to conform to the [Buildpack Interface Specification](buildpack.md).
+
+### Detection
+
+Executable: `/bin/detect`, Working Dir: `<app[AR]>`
+
+Image extensions participate in the buildpack [detection](buildpack.md#detection) process, with the same interface for `/bin/detect`. However:
+- Detection is optional for image extensions, and they are assumed to pass detection when `/bin/detect` is not present.
+- Image extensions MUST only output `provides` entries to the build plan. They MUST NOT output `requires`.
+
+### Generation
+
+Executable: `/bin/generate`, Working Dir: `<app[AR]>`
+
+Image extensions participate in a generation process that is similar to the buildpack [build](buildpack.md#build) process, with an interface that is similar to `/bin/build`. However:
+- Image extensions' `/bin/generate` MUST NOT write to the app directory.
+- Instead of the `CNB_LAYERS_DIR`, image extensions receive a `CNB_OUTPUT_DIR` which MUST be the absolute path of an `<output>` directory and MUST NOT be the path of the buildpack layers directory.
+- If an image extension is missing `/bin/generate`, the image extension root MUST be treated as a pre-populated `<output>` directory.
+
+## Phase: Generation
+
+### Purpose
+
+The purpose of the generation phase is to generate Dockerfiles that can be used to select the runtime base image.
+
+### Process
+
+**GIVEN:**
+- The final ordered group of image extensions determined during the detection phase,
+- A directory containing application source code,
+- The Buildpack Plan,
+- An `<output>` directory used to store generated artifacts,
+- A shell, if needed,
+
+For each image extension in the group in order, the lifecycle MUST execute `/bin/generate`.
+
+1. **If** the exit status of `/bin/generate` is non-zero, \
+   **Then** the lifecycle MUST fail the build.
+
+2. **If** the exit status of `/bin/generate` is zero,
+    1. **If** there are additional image extensions in the group, \
+       **Then** the lifecycle MUST proceed to the next image extension's `/bin/generate`.
+
+    2. **If** there are no additional image extensions in the group, \
+       **Then** the lifecycle MUST proceed to the build phase.
+
+For each `/bin/generate` executable in each image extension, the lifecycle:
+
+- MUST provide path arguments to `/bin/generate` as described in the [generation](#generation) section.
+- MUST configure the build environment as described in the [Environment](buildpack.md#environment) section.
+- MUST provide all `<plan>` entries that were required by any buildpack in the group during the detection phase with names matching the names that the image extension provided.
+
+Correspondingly, each `/bin/generate` executable:
+
+- MAY read from the `<app>` directory.
+- MUST NOT write to the `<app>` directory.
+- MAY read the build environment as described in the [Environment](buildpack.md#environment) section.
+- MAY read the Buildpack Plan.
+- MAY log output from the build process to `stdout`.
+- MAY emit error, warning, or debug messages to `stderr`.
+- MAY write a run.Dockerfile to the `<output>` directory. This file MUST adhere to the requirements listed below.
+- MUST NOT write SBOM (Software-Bill-of-Materials) files as described in the [Software-Bill-of-Materials](#software-bill-of-materials) section.
+
+#### Dockerfile Requirements
+
+run.Dockerfiles:
+
+- MAY contain a single `FROM` instruction
+- MUST NOT contain any other instructions
+
+## Data Format
+
+### Files
+
+### extension.toml (TOML)
+
+This section describes the 'Extension descriptor'.
+
+```toml
+api = "<buildpack API version>"
+
+[extension]
+id = "<extension ID>"
+name = "<extension name>"
+version = "<extension version>"
+homepage = "<extension homepage>"
+description = "<extension description>"
+keywords = [ "<string>" ]
+
+[[extension.licenses]]
+type = "<string>"
+uri = "<uri>"
+```
+
+Image extension authors MUST choose a globally unique ID, for example: "io.buildpacks.apt".
+
+The image extension `id`, `version`, `api`, `licenses`, and `sbom-formats` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md).

From 505b7d54729833c5d495fae8daeb1bba6d05d46b Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Wed, 15 Jun 2022 17:27:21 -0400
Subject: [PATCH 05/31] Updates from implementation

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 image_extension.md | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/image_extension.md b/image_extension.md
index 0ce4f0a4..350a899a 100644
--- a/image_extension.md
+++ b/image_extension.md
@@ -1,4 +1,4 @@
-# Image Extension Interface Specification
+# Image Extension Interface Specification (**experimental**)
 
 This document specifies the interface between a lifecycle program and one or more image extensions.
 
@@ -35,6 +35,7 @@ Executable: `/bin/detect`, Working Dir: `<app[AR]>`
 
 Image extensions participate in the buildpack [detection](buildpack.md#detection) process, with the same interface for `/bin/detect`. However:
 - Detection is optional for image extensions, and they are assumed to pass detection when `/bin/detect` is not present.
+- If an image extension is missing `/bin/detect`, the image extension root MUST be treated as a pre-populated `<output>` directory.
 - Image extensions MUST only output `provides` entries to the build plan. They MUST NOT output `requires`.
 
 ### Generation
@@ -124,3 +125,14 @@ uri = "<uri>"
 Image extension authors MUST choose a globally unique ID, for example: "io.buildpacks.apt".
 
 The image extension `id`, `version`, `api`, `licenses`, and `sbom-formats` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md).
+
+### build.toml (TOML)
+
+This section describes the `build.toml` output by image extensions; for buildpacks see the [Buildpack Interface Specification](buildpack.md).
+
+```toml
+[[unmet]]
+name = "<dependency name>"
+```
+
+The image extension `unmet` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md).

From 6f4a4084ff642e71e5d57aa6d6d963b49f575cbd Mon Sep 17 00:00:00 2001
From: BarDweller <bardweller@gmail.com>
Date: Thu, 16 Jun 2022 10:40:41 -0400
Subject: [PATCH 06/31] cache svgs and set svg bg to white (helps with github
 darkmode)

Signed-off-by: BarDweller <bardweller@gmail.com>
---
 buildpack.md     | 18 +++++++++---------
 img/genmatrix.sh | 15 +++++++++++++++
 img/matrix1.svg  |  1 +
 img/matrix2.svg  |  1 +
 img/matrix3.svg  |  1 +
 img/matrix4.svg  |  1 +
 6 files changed, 28 insertions(+), 9 deletions(-)
 create mode 100644 img/genmatrix.sh
 create mode 100644 img/matrix1.svg
 create mode 100644 img/matrix2.svg
 create mode 100644 img/matrix3.svg
 create mode 100644 img/matrix4.svg

diff --git a/buildpack.md b/buildpack.md
index b37fe8fc..6146438e 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -402,25 +402,25 @@ Where:
 
 Given:
 
-<img src="http://tex.s2cms.ru/svg/%0AO%20%3D%0A%5Cbegin%7Bbmatrix%7D%0AA%2C%20%26%20B%20%5C%5C%0AC%2C%20%26%20D%0A%5Cend%7Bbmatrix%7D%0A" alt="
-O =
+![
+  O =
 \begin{bmatrix}
 A, &amp; B \\
 C, &amp; D
 \end{bmatrix}
-" />
+](img/matrix1.svg)
 
-<img src="http://tex.s2cms.ru/svg/%0AP%20%3D%0A%5Cbegin%7Bbmatrix%7D%0AE%2C%20%26%20F%20%5C%5C%0AG%2C%20%26%20H%0A%5Cend%7Bbmatrix%7D%0A" alt="
+![
 P =
 \begin{bmatrix}
 E, &amp; F \\
 G, &amp; H
 \end{bmatrix}
-" />
+"](img/matrix2.svg)
 
 It MUST follow that:
 
-<img src="http://tex.s2cms.ru/svg/%0A%5Cbegin%7Bbmatrix%7D%0AE%2C%20%26%20O%2C%20%26%20F%0A%5Cend%7Bbmatrix%7D%20%3D%20%0A%5Cbegin%7Bbmatrix%7D%0AE%2C%20%26%20A%2C%20%26%20B%2C%20%26%20F%20%5C%5C%0AE%2C%20%26%20C%2C%20%26%20D%2C%20%26%20F%20%5C%5C%0A%5Cend%7Bbmatrix%7D%0A" alt="
+![
 \begin{bmatrix}
 E, &amp; O, &amp; F
 \end{bmatrix} =
@@ -428,9 +428,9 @@ E, &amp; O, &amp; F
 E, &amp; A, &amp; B, &amp; F \\
 E, &amp; C, &amp; D, &amp; F \\
 \end{bmatrix}
-" />
+](img/matrix3.svg)
 
-<img src="http://tex.s2cms.ru/svg/%0A%5Cbegin%7Bbmatrix%7D%0AO%2C%20%26%20P%0A%5Cend%7Bbmatrix%7D%20%3D%20%0A%5Cbegin%7Bbmatrix%7D%0AA%2C%20%26%20B%2C%20%26%20E%2C%20%26%20F%20%5C%5C%0AA%2C%20%26%20B%2C%20%26%20G%2C%20%26%20H%20%5C%5C%0AC%2C%20%26%20D%2C%20%26%20E%2C%20%26%20F%20%5C%5C%0AC%2C%20%26%20D%2C%20%26%20G%2C%20%26%20H%20%5C%5C%0A%5Cend%7Bbmatrix%7D%0A" alt="
+![
 \begin{bmatrix}
 O, &amp; P
 \end{bmatrix} =
@@ -440,7 +440,7 @@ A, &amp; B, &amp; G, &amp; H \\
 C, &amp; D, &amp; E, &amp; F \\
 C, &amp; D, &amp; G, &amp; H \\
 \end{bmatrix}
-" />
+](img/matrix4.svg)
 
 Note that buildpack IDs are expanded depth-first in left-to-right order.
 
diff --git a/img/genmatrix.sh b/img/genmatrix.sh
new file mode 100644
index 00000000..80ca21b5
--- /dev/null
+++ b/img/genmatrix.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+
+# A quick script to use tex.s2cms.ru to generate various matrix svgs.
+# (requests were previously inlined directly from buildpack.md, this allows the doc to be read if the remote side is down)
+
+wget -O matrix1.svg http://tex.s2cms.ru/svg/%0AO%20%3D%0A%5Cbegin%7Bbmatrix%7D%0AA%2C%20%26%20B%20%5C%5C%0AC%2C%20%26%20D%0A%5Cend%7Bbmatrix%7D%0A
+wget -O matrix2.svg http://tex.s2cms.ru/svg/%0AP%20%3D%0A%5Cbegin%7Bbmatrix%7D%0AE%2C%20%26%20F%20%5C%5C%0AG%2C%20%26%20H%0A%5Cend%7Bbmatrix%7D%0A
+wget -O matrix3.svg http://tex.s2cms.ru/svg/%0A%5Cbegin%7Bbmatrix%7D%0AE%2C%20%26%20O%2C%20%26%20F%0A%5Cend%7Bbmatrix%7D%20%3D%20%0A%5Cbegin%7Bbmatrix%7D%0AE%2C%20%26%20A%2C%20%26%20B%2C%20%26%20F%20%5C%5C%0AE%2C%20%26%20C%2C%20%26%20D%2C%20%26%20F%20%5C%5C%0A%5Cend%7Bbmatrix%7D%0A
+wget -O matrix4.svg http://tex.s2cms.ru/svg/%0A%5Cbegin%7Bbmatrix%7D%0AO%2C%20%26%20P%0A%5Cend%7Bbmatrix%7D%20%3D%20%0A%5Cbegin%7Bbmatrix%7D%0AA%2C%20%26%20B%2C%20%26%20E%2C%20%26%20F%20%5C%5C%0AA%2C%20%26%20B%2C%20%26%20G%2C%20%26%20H%20%5C%5C%0AC%2C%20%26%20D%2C%20%26%20E%2C%20%26%20F%20%5C%5C%0AC%2C%20%26%20D%2C%20%26%20G%2C%20%26%20H%20%5C%5C%0A%5Cend%7Bbmatrix%7D%0A
+
+# add background color.. (helps with github darkmode)
+sed -i -e's/<svg/<svg style="background-color:white"/' matrix1.svg
+sed -i -e's/<svg/<svg style="background-color:white"/' matrix2.svg
+sed -i -e's/<svg/<svg style="background-color:white"/' matrix3.svg
+sed -i -e's/<svg/<svg style="background-color:white"/' matrix4.svg
\ No newline at end of file
diff --git a/img/matrix1.svg b/img/matrix1.svg
new file mode 100644
index 00000000..d2158e50
--- /dev/null
+++ b/img/matrix1.svg
@@ -0,0 +1 @@
+<svg style="background-color:white" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="105" height="44" viewBox="1872.02 1483.609 62.765 26.301"><defs><path id="g0-20" d="M2.727 25.735h2.87v-.6h-2.27V.164h2.27v-.6h-2.87v26.17z"/><path id="g0-21" d="M2.422 25.135H.152v.6h2.87V-.436H.152v.6h2.27v24.97z"/><path id="g2-61" d="M7.495-3.567c.163 0 .37 0 .37-.218s-.207-.219-.36-.219H.971c-.153 0-.36 0-.36.219s.207.218.37.218h6.514zm.01 2.116c.153 0 .36 0 .36-.218s-.207-.218-.37-.218H.982c-.164 0-.371 0-.371.218s.207.218.36.218h6.534z"/><path id="g1-59" d="M2.215-.01c0-.72-.273-1.146-.699-1.146a.561.561 0 00-.578.578c0 .294.218.578.578.578.131 0 .273-.044.382-.142.033-.022.044-.033.055-.033s.022.011.022.164c0 .807-.382 1.462-.742 1.822-.12.12-.12.142-.12.174 0 .077.054.12.109.12.12 0 .993-.84.993-2.116z"/><path id="g1-65" d="M1.953-1.255C1.516-.524 1.09-.37.61-.338c-.131.01-.23.01-.23.218 0 .065.055.12.143.12.294 0 .632-.033.938-.033.36 0 .742.033 1.09.033.066 0 .208 0 .208-.207 0-.12-.098-.131-.175-.131-.25-.022-.512-.11-.512-.382 0-.13.065-.25.152-.404l.83-1.396h2.738c.022.23.174 1.713.174 1.822 0 .327-.567.36-.785.36-.153 0-.262 0-.262.218 0 .12.13.12.153.12.447 0 .916-.033 1.363-.033.273 0 .96.033 1.233.033.066 0 .196 0 .196-.218 0-.12-.109-.12-.25-.12-.677 0-.677-.077-.71-.393L6.24-7.549c-.022-.218-.022-.262-.207-.262-.175 0-.218.076-.284.186l-3.796 6.37zm1.309-1.603l2.149-3.6.349 3.6H3.262z"/><path id="g1-66" d="M1.745-.85c-.109.425-.13.512-.992.512-.186 0-.295 0-.295.218 0 .12.098.12.295.12h3.894c1.724 0 3.011-1.287 3.011-2.356 0-.786-.633-1.419-1.69-1.539 1.134-.207 2.28-1.014 2.28-2.05 0-.808-.72-1.506-2.03-1.506H2.553c-.208 0-.317 0-.317.218 0 .12.099.12.306.12.022 0 .229 0 .414.022.197.022.295.033.295.175 0 .043-.011.076-.044.207L1.745-.851zm1.648-3.143l.676-2.705c.098-.382.12-.415.59-.415h1.406c.96 0 1.19.644 1.19 1.124 0 .96-.939 1.996-2.27 1.996H3.393zM2.902-.338c-.153 0-.175 0-.24-.011-.11-.011-.142-.022-.142-.11 0-.032 0-.054.055-.25l.752-3.044H5.39c1.047 0 1.255.808 1.255 1.277 0 1.08-.971 2.138-2.259 2.138H2.902z"/><path id="g1-67" d="M8.29-7.582a.11.11 0 00-.12-.109c-.032 0-.043.011-.163.131l-.763.84c-.099-.153-.6-.97-1.811-.97C3-7.69.545-5.28.545-2.75.545-.95 1.833.24 3.502.24c.949 0 1.778-.436 2.356-.938 1.015-.895 1.2-1.887 1.2-1.92 0-.11-.109-.11-.13-.11-.066 0-.12.023-.143.11-.098.316-.349 1.09-1.101 1.723-.753.611-1.44.797-2.008.797-.981 0-2.138-.567-2.138-2.27 0-.621.23-2.388 1.32-3.665.666-.774 1.691-1.32 2.662-1.32 1.113 0 1.756.84 1.756 2.106 0 .436-.032.447-.032.556s.12.11.163.11c.142 0 .142-.023.197-.219l.687-2.782z"/><path id="g1-68" d="M1.735-.85c-.11.425-.131.512-.993.512-.186 0-.306 0-.306.207C.436 0 .535 0 .742 0h3.61c2.27 0 4.419-2.302 4.419-4.69 0-1.54-.927-2.76-2.564-2.76H2.542c-.207 0-.327 0-.327.206 0 .131.098.131.316.131.142 0 .338.011.469.022.175.022.24.055.24.175 0 .043-.01.076-.044.207L1.735-.851zM4.09-6.699c.098-.382.12-.415.589-.415h1.167c1.07 0 1.975.578 1.975 2.018 0 .535-.218 2.324-1.146 3.524-.316.404-1.178 1.233-2.52 1.233H2.924c-.153 0-.175 0-.24-.011-.11-.011-.142-.022-.142-.11 0-.032 0-.054.054-.25L4.091-6.7z"/><path id="g1-79" d="M8.073-4.756c0-1.757-1.157-2.935-2.782-2.935C2.935-7.69.535-5.215.535-2.673.535-.862 1.756.24 3.327.24c2.313 0 4.746-2.39 4.746-4.996zM3.393-.044c-1.08 0-1.844-.883-1.844-2.323 0-.48.153-2.073.993-3.35.753-1.134 1.822-1.701 2.683-1.701.895 0 1.877.61 1.877 2.236 0 .786-.295 2.487-1.375 3.83C5.204-.688 4.31-.045 3.393-.045z"/></defs><g id="page1"><use x="1872.02" y="1499.492" xlink:href="#g1-79"/><use x="1883.674" y="1499.492" xlink:href="#g2-61"/><use x="1895.189" y="1484.11" xlink:href="#g0-20"/><use x="1900.947" y="1492.7" xlink:href="#g1-65"/><use x="1909.129" y="1492.7" xlink:href="#g1-59"/><use x="1922.378" y="1492.7" xlink:href="#g1-66"/><use x="1901.052" y="1506.249" xlink:href="#g1-67"/><use x="1909.024" y="1506.249" xlink:href="#g1-59"/><use x="1922.122" y="1506.249" xlink:href="#g1-68"/><use x="1931.457" y="1484.11" xlink:href="#g0-21"/></g><script type="text/ecmascript">if(window.parent.postMessage)window.parent.postMessage(&quot;13.07112|78.75|33|&quot;+window.location,&quot;*&quot;);</script></svg>
\ No newline at end of file
diff --git a/img/matrix2.svg b/img/matrix2.svg
new file mode 100644
index 00000000..67c45f58
--- /dev/null
+++ b/img/matrix2.svg
@@ -0,0 +1 @@
+<svg style="background-color:white" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="107" height="44" viewBox="1872.02 1483.609 63.96 26.301"><defs><path id="g0-20" d="M2.727 25.735h2.87v-.6h-2.27V.164h2.27v-.6h-2.87v26.17z"/><path id="g0-21" d="M2.422 25.135H.152v.6h2.87V-.436H.152v.6h2.27v24.97z"/><path id="g2-61" d="M7.495-3.567c.163 0 .37 0 .37-.218s-.207-.219-.36-.219H.971c-.153 0-.36 0-.36.219s.207.218.37.218h6.514zm.01 2.116c.153 0 .36 0 .36-.218s-.207-.218-.37-.218H.982c-.164 0-.371 0-.371.218s.207.218.36.218h6.534z"/><path id="g1-59" d="M2.215-.01c0-.72-.273-1.146-.699-1.146a.561.561 0 00-.578.578c0 .294.218.578.578.578.131 0 .273-.044.382-.142.033-.022.044-.033.055-.033s.022.011.022.164c0 .807-.382 1.462-.742 1.822-.12.12-.12.142-.12.174 0 .077.054.12.109.12.12 0 .993-.84.993-2.116z"/><path id="g1-69" d="M7.724-2.542c.021-.054.054-.13.054-.153 0-.01 0-.12-.13-.12-.099 0-.12.066-.143.131C6.796-1.069 6.393-.338 4.527-.338H2.935c-.153 0-.175 0-.24-.011-.11-.011-.142-.022-.142-.11 0-.032 0-.054.054-.25l.742-2.978h1.08c.927 0 .927.229.927.502 0 .076 0 .207-.076.534a.331.331 0 00-.033.12c0 .055.044.12.142.12.087 0 .12-.054.164-.218l.622-2.553c0-.065-.055-.12-.131-.12-.099 0-.12.066-.153.197-.23.829-.426 1.08-1.43 1.08H3.437l.655-2.63c.098-.381.109-.425.589-.425h1.538c1.331 0 1.658.316 1.658 1.21 0 .263 0 .285-.043.58 0 .065-.011.14-.011.195s.033.131.13.131c.12 0 .132-.065.153-.272l.219-1.888c.032-.294-.022-.294-.295-.294H2.52c-.218 0-.327 0-.327.218 0 .12.098.12.305.12.404 0 .71 0 .71.196 0 .044 0 .066-.055.262L1.713-.85c-.11.426-.131.513-.993.513-.185 0-.305 0-.305.207C.415 0 .513 0 .72 0h5.662c.25 0 .262-.01.338-.185l1.004-2.357z"/><path id="g1-70" d="M3.305-3.545h1.059c.818 0 .905.174.905.49 0 .077 0 .208-.076.535a.396.396 0 00-.033.12c0 .087.065.13.13.13.11 0 .11-.032.165-.228l.6-2.367c.032-.12.032-.142.032-.175 0-.022-.022-.12-.13-.12s-.12.055-.164.23c-.23.85-.48 1.046-1.408 1.046h-.992l.698-2.77c.098-.382.109-.426.589-.426h1.44c1.342 0 1.593.36 1.593 1.2 0 .25 0 .295-.033.59-.022.14-.022.163-.022.195 0 .055.033.131.131.131.12 0 .131-.065.153-.272l.218-1.888c.033-.294-.022-.294-.295-.294H2.52c-.218 0-.327 0-.327.218 0 .12.098.12.305.12.404 0 .71 0 .71.196 0 .044 0 .066-.055.262L1.713-.85c-.11.426-.131.513-.993.513-.185 0-.305 0-.305.207C.415 0 .545 0 .578 0c.317 0 1.124-.033 1.44-.033.36 0 1.266.033 1.626.033.098 0 .229 0 .229-.207 0-.088-.066-.11-.066-.12-.032-.011-.054-.011-.305-.011-.24 0-.295 0-.567-.022-.317-.033-.35-.076-.35-.218 0-.022 0-.087.044-.251l.676-2.716z"/><path id="g1-71" d="M8.29-7.582a.11.11 0 00-.12-.109c-.032 0-.043.011-.163.131l-.763.84c-.099-.153-.6-.97-1.811-.97C3-7.69.545-5.28.545-2.75.545-1.014 1.756.24 3.524.24c.48 0 .97-.098 1.363-.262.546-.218.753-.447.95-.665.098.272.381.676.49.676.055 0 .077-.033.077-.044.021-.021.13-.436.185-.665l.207-.84c.044-.185.099-.37.142-.556.12-.491.131-.513.753-.524.054 0 .174-.01.174-.218 0-.077-.054-.12-.141-.12-.251 0-.895.033-1.146.033-.338 0-1.189-.033-1.527-.033-.098 0-.23 0-.23.218 0 .12.088.12.328.12.011 0 .327 0 .578.022.284.033.338.065.338.207 0 .098-.12.59-.229.993-.305 1.2-1.723 1.32-2.105 1.32-1.047 0-2.193-.622-2.193-2.291 0-.338.11-2.138 1.255-3.556.589-.742 1.647-1.408 2.727-1.408 1.113 0 1.756.84 1.756 2.106 0 .436-.032.447-.032.556s.12.11.163.11c.142 0 .142-.023.197-.219l.687-2.782z"/><path id="g1-72" d="M8.324-6.61c.098-.394.12-.503.916-.503.284 0 .37 0 .37-.218 0-.12-.12-.12-.152-.12-.305 0-1.09.033-1.396.033-.317 0-1.091-.033-1.407-.033-.088 0-.208 0-.208.218 0 .12.098.12.306.12.022 0 .229 0 .414.022.197.022.295.033.295.175 0 .043-.011.065-.044.207l-.654 2.662H3.436l.644-2.564c.098-.393.13-.502.916-.502.284 0 .371 0 .371-.218 0-.12-.12-.12-.152-.12-.306 0-1.091.033-1.397.033-.316 0-1.09-.033-1.407-.033-.087 0-.207 0-.207.218 0 .12.098.12.305.12.022 0 .23 0 .415.022.196.022.294.033.294.175 0 .043-.01.076-.043.207L1.713-.851c-.11.426-.131.513-.993.513-.196 0-.295 0-.295.218 0 .12.131.12.153.12.306 0 1.08-.033 1.386-.033.229 0 .469.011.698.011.24 0 .48.022.709.022.087 0 .218 0 .218-.218 0-.12-.098-.12-.305-.12-.404 0-.71 0-.71-.197 0-.065.022-.12.033-.185l.742-2.99h3.327c-.458 1.812-.709 2.848-.752 3.012-.11.349-.317.36-.993.36-.164 0-.262 0-.262.218 0 .12.131.12.153.12.305 0 1.08-.033 1.385-.033.23 0 .47.011.698.011.24 0 .48.022.71.022.087 0 .218 0 .218-.218 0-.12-.098-.12-.306-.12-.403 0-.709 0-.709-.197 0-.065.022-.12.033-.185l1.473-5.89z"/><path id="g1-80" d="M3.305-3.447H5.16c1.55 0 3.065-1.135 3.065-2.357 0-.84-.72-1.647-2.149-1.647H2.542c-.207 0-.327 0-.327.207 0 .131.098.131.316.131.142 0 .338.011.469.022.175.022.24.055.24.175 0 .043-.01.076-.044.207L1.735-.851c-.11.426-.131.513-.993.513-.186 0-.306 0-.306.207C.436 0 .567 0 .6 0c.305 0 1.08-.033 1.385-.033.23 0 .47.011.699.011.24 0 .48.022.709.022.076 0 .218 0 .218-.218 0-.12-.098-.12-.306-.12-.403 0-.709 0-.709-.197 0-.065.022-.12.033-.185l.676-2.727zm.786-3.251c.098-.382.12-.415.589-.415h1.047c.906 0 1.484.295 1.484 1.048 0 .425-.218 1.363-.644 1.756-.545.49-1.2.578-1.68.578H3.35l.742-2.967z"/></defs><g id="page1"><use x="1872.02" y="1499.492" xlink:href="#g1-80"/><use x="1883.569" y="1499.492" xlink:href="#g2-61"/><use x="1895.084" y="1484.11" xlink:href="#g0-20"/><use x="1900.842" y="1492.7" xlink:href="#g1-69"/><use x="1909.524" y="1492.7" xlink:href="#g1-59"/><use x="1923.229" y="1492.7" xlink:href="#g1-70"/><use x="1900.894" y="1506.249" xlink:href="#g1-71"/><use x="1909.471" y="1506.249" xlink:href="#g1-59"/><use x="1922.516" y="1506.249" xlink:href="#g1-72"/><use x="1932.471" y="1484.11" xlink:href="#g0-21"/></g><script type="text/ecmascript">if(window.parent.postMessage)window.parent.postMessage(&quot;13.07112|80.25|33|&quot;+window.location,&quot;*&quot;);</script></svg>
\ No newline at end of file
diff --git a/img/matrix3.svg b/img/matrix3.svg
new file mode 100644
index 00000000..34874a30
--- /dev/null
+++ b/img/matrix3.svg
@@ -0,0 +1 @@
+<svg style="background-color:white" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="265" height="44" viewBox="1872.02 1483.609 158.406 26.301"><defs><path id="g2-61" d="M7.495-3.567c.163 0 .37 0 .37-.218s-.207-.219-.36-.219H.971c-.153 0-.36 0-.36.219s.207.218.37.218h6.514zm.01 2.116c.153 0 .36 0 .36-.218s-.207-.218-.37-.218H.982c-.164 0-.371 0-.371.218s.207.218.36.218h6.534z"/><path id="g1-59" d="M2.215-.01c0-.72-.273-1.146-.699-1.146a.561.561 0 00-.578.578c0 .294.218.578.578.578.131 0 .273-.044.382-.142.033-.022.044-.033.055-.033s.022.011.022.164c0 .807-.382 1.462-.742 1.822-.12.12-.12.142-.12.174 0 .077.054.12.109.12.12 0 .993-.84.993-2.116z"/><path id="g1-65" d="M1.953-1.255C1.516-.524 1.09-.37.61-.338c-.131.01-.23.01-.23.218 0 .065.055.12.143.12.294 0 .632-.033.938-.033.36 0 .742.033 1.09.033.066 0 .208 0 .208-.207 0-.12-.098-.131-.175-.131-.25-.022-.512-.11-.512-.382 0-.13.065-.25.152-.404l.83-1.396h2.738c.022.23.174 1.713.174 1.822 0 .327-.567.36-.785.36-.153 0-.262 0-.262.218 0 .12.13.12.153.12.447 0 .916-.033 1.363-.033.273 0 .96.033 1.233.033.066 0 .196 0 .196-.218 0-.12-.109-.12-.25-.12-.677 0-.677-.077-.71-.393L6.24-7.549c-.022-.218-.022-.262-.207-.262-.175 0-.218.076-.284.186l-3.796 6.37zm1.309-1.603l2.149-3.6.349 3.6H3.262z"/><path id="g1-66" d="M1.745-.85c-.109.425-.13.512-.992.512-.186 0-.295 0-.295.218 0 .12.098.12.295.12h3.894c1.724 0 3.011-1.287 3.011-2.356 0-.786-.633-1.419-1.69-1.539 1.134-.207 2.28-1.014 2.28-2.05 0-.808-.72-1.506-2.03-1.506H2.553c-.208 0-.317 0-.317.218 0 .12.099.12.306.12.022 0 .229 0 .414.022.197.022.295.033.295.175 0 .043-.011.076-.044.207L1.745-.851zm1.648-3.143l.676-2.705c.098-.382.12-.415.59-.415h1.406c.96 0 1.19.644 1.19 1.124 0 .96-.939 1.996-2.27 1.996H3.393zM2.902-.338c-.153 0-.175 0-.24-.011-.11-.011-.142-.022-.142-.11 0-.032 0-.054.055-.25l.752-3.044H5.39c1.047 0 1.255.808 1.255 1.277 0 1.08-.971 2.138-2.259 2.138H2.902z"/><path id="g1-67" d="M8.29-7.582a.11.11 0 00-.12-.109c-.032 0-.043.011-.163.131l-.763.84c-.099-.153-.6-.97-1.811-.97C3-7.69.545-5.28.545-2.75.545-.95 1.833.24 3.502.24c.949 0 1.778-.436 2.356-.938 1.015-.895 1.2-1.887 1.2-1.92 0-.11-.109-.11-.13-.11-.066 0-.12.023-.143.11-.098.316-.349 1.09-1.101 1.723-.753.611-1.44.797-2.008.797-.981 0-2.138-.567-2.138-2.27 0-.621.23-2.388 1.32-3.665.666-.774 1.691-1.32 2.662-1.32 1.113 0 1.756.84 1.756 2.106 0 .436-.032.447-.032.556s.12.11.163.11c.142 0 .142-.023.197-.219l.687-2.782z"/><path id="g1-68" d="M1.735-.85c-.11.425-.131.512-.993.512-.186 0-.306 0-.306.207C.436 0 .535 0 .742 0h3.61c2.27 0 4.419-2.302 4.419-4.69 0-1.54-.927-2.76-2.564-2.76H2.542c-.207 0-.327 0-.327.206 0 .131.098.131.316.131.142 0 .338.011.469.022.175.022.24.055.24.175 0 .043-.01.076-.044.207L1.735-.851zM4.09-6.699c.098-.382.12-.415.589-.415h1.167c1.07 0 1.975.578 1.975 2.018 0 .535-.218 2.324-1.146 3.524-.316.404-1.178 1.233-2.52 1.233H2.924c-.153 0-.175 0-.24-.011-.11-.011-.142-.022-.142-.11 0-.032 0-.054.054-.25L4.091-6.7z"/><path id="g1-69" d="M7.724-2.542c.021-.054.054-.13.054-.153 0-.01 0-.12-.13-.12-.099 0-.12.066-.143.131C6.796-1.069 6.393-.338 4.527-.338H2.935c-.153 0-.175 0-.24-.011-.11-.011-.142-.022-.142-.11 0-.032 0-.054.054-.25l.742-2.978h1.08c.927 0 .927.229.927.502 0 .076 0 .207-.076.534a.331.331 0 00-.033.12c0 .055.044.12.142.12.087 0 .12-.054.164-.218l.622-2.553c0-.065-.055-.12-.131-.12-.099 0-.12.066-.153.197-.23.829-.426 1.08-1.43 1.08H3.437l.655-2.63c.098-.381.109-.425.589-.425h1.538c1.331 0 1.658.316 1.658 1.21 0 .263 0 .285-.043.58 0 .065-.011.14-.011.195s.033.131.13.131c.12 0 .132-.065.153-.272l.219-1.888c.032-.294-.022-.294-.295-.294H2.52c-.218 0-.327 0-.327.218 0 .12.098.12.305.12.404 0 .71 0 .71.196 0 .044 0 .066-.055.262L1.713-.85c-.11.426-.131.513-.993.513-.185 0-.305 0-.305.207C.415 0 .513 0 .72 0h5.662c.25 0 .262-.01.338-.185l1.004-2.357z"/><path id="g1-70" d="M3.305-3.545h1.059c.818 0 .905.174.905.49 0 .077 0 .208-.076.535a.396.396 0 00-.033.12c0 .087.065.13.13.13.11 0 .11-.032.165-.228l.6-2.367c.032-.12.032-.142.032-.175 0-.022-.022-.12-.13-.12s-.12.055-.164.23c-.23.85-.48 1.046-1.408 1.046h-.992l.698-2.77c.098-.382.109-.426.589-.426h1.44c1.342 0 1.593.36 1.593 1.2 0 .25 0 .295-.033.59-.022.14-.022.163-.022.195 0 .055.033.131.131.131.12 0 .131-.065.153-.272l.218-1.888c.033-.294-.022-.294-.295-.294H2.52c-.218 0-.327 0-.327.218 0 .12.098.12.305.12.404 0 .71 0 .71.196 0 .044 0 .066-.055.262L1.713-.85c-.11.426-.131.513-.993.513-.185 0-.305 0-.305.207C.415 0 .545 0 .578 0c.317 0 1.124-.033 1.44-.033.36 0 1.266.033 1.626.033.098 0 .229 0 .229-.207 0-.088-.066-.11-.066-.12-.032-.011-.054-.011-.305-.011-.24 0-.295 0-.567-.022-.317-.033-.35-.076-.35-.218 0-.022 0-.087.044-.251l.676-2.716z"/><path id="g1-79" d="M8.073-4.756c0-1.757-1.157-2.935-2.782-2.935C2.935-7.69.535-5.215.535-2.673.535-.862 1.756.24 3.327.24c2.313 0 4.746-2.39 4.746-4.996zM3.393-.044c-1.08 0-1.844-.883-1.844-2.323 0-.48.153-2.073.993-3.35.753-1.134 1.822-1.701 2.683-1.701.895 0 1.877.61 1.877 2.236 0 .786-.295 2.487-1.375 3.83C5.204-.688 4.31-.045 3.393-.045z"/><path id="g0-2" d="M2.204 12.644h2.094v-.437H2.64V0h1.658v-.436H2.204v13.08z"/><path id="g0-3" d="M2.335 12.644V-.436H.24V0h1.658v12.207H.24v.437h2.095z"/><path id="g0-20" d="M2.727 25.735h2.87v-.6h-2.27V.164h2.27v-.6h-2.87v26.17z"/><path id="g0-21" d="M2.422 25.135H.152v.6h2.87V-.436H.152v.6h2.27v24.97z"/></defs><g id="page1"><use x="1872.02" y="1490.656" xlink:href="#g0-2"/><use x="1876.565" y="1499.475" xlink:href="#g1-69"/><use x="1885.247" y="1499.475" xlink:href="#g1-59"/><use x="1898.24" y="1499.475" xlink:href="#g1-79"/><use x="1906.864" y="1499.475" xlink:href="#g1-59"/><use x="1919.857" y="1499.475" xlink:href="#g1-70"/><use x="1928.387" y="1490.656" xlink:href="#g0-3"/><use x="1935.963" y="1499.492" xlink:href="#g2-61"/><use x="1947.478" y="1484.11" xlink:href="#g0-20"/><use x="1953.236" y="1492.7" xlink:href="#g1-69"/><use x="1961.918" y="1492.7" xlink:href="#g1-59"/><use x="1974.911" y="1492.7" xlink:href="#g1-65"/><use x="1983.093" y="1492.7" xlink:href="#g1-59"/><use x="1996.342" y="1492.7" xlink:href="#g1-66"/><use x="2005.164" y="1492.7" xlink:href="#g1-59"/><use x="2018.413" y="1492.7" xlink:href="#g1-70"/><use x="1953.236" y="1506.249" xlink:href="#g1-69"/><use x="1961.918" y="1506.249" xlink:href="#g1-59"/><use x="1975.016" y="1506.249" xlink:href="#g1-67"/><use x="1982.987" y="1506.249" xlink:href="#g1-59"/><use x="1996.085" y="1506.249" xlink:href="#g1-68"/><use x="2005.42" y="1506.249" xlink:href="#g1-59"/><use x="2018.413" y="1506.249" xlink:href="#g1-70"/><use x="2026.944" y="1484.11" xlink:href="#g0-21"/></g><script type="text/ecmascript">if(window.parent.postMessage)window.parent.postMessage(&quot;13.07112|198.75|33|&quot;+window.location,&quot;*&quot;);</script></svg>
\ No newline at end of file
diff --git a/img/matrix4.svg b/img/matrix4.svg
new file mode 100644
index 00000000..be219549
--- /dev/null
+++ b/img/matrix4.svg
@@ -0,0 +1 @@
+<svg style="background-color:white" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="235" height="88" viewBox="1872.02 1484.013 140.473 52.603"><defs><path id="g2-61" d="M7.495-3.567c.163 0 .37 0 .37-.218s-.207-.219-.36-.219H.971c-.153 0-.36 0-.36.219s.207.218.37.218h6.514zm.01 2.116c.153 0 .36 0 .36-.218s-.207-.218-.37-.218H.982c-.164 0-.371 0-.371.218s.207.218.36.218h6.534z"/><path id="g1-59" d="M2.215-.01c0-.72-.273-1.146-.699-1.146a.561.561 0 00-.578.578c0 .294.218.578.578.578.131 0 .273-.044.382-.142.033-.022.044-.033.055-.033s.022.011.022.164c0 .807-.382 1.462-.742 1.822-.12.12-.12.142-.12.174 0 .077.054.12.109.12.12 0 .993-.84.993-2.116z"/><path id="g1-65" d="M1.953-1.255C1.516-.524 1.09-.37.61-.338c-.131.01-.23.01-.23.218 0 .065.055.12.143.12.294 0 .632-.033.938-.033.36 0 .742.033 1.09.033.066 0 .208 0 .208-.207 0-.12-.098-.131-.175-.131-.25-.022-.512-.11-.512-.382 0-.13.065-.25.152-.404l.83-1.396h2.738c.022.23.174 1.713.174 1.822 0 .327-.567.36-.785.36-.153 0-.262 0-.262.218 0 .12.13.12.153.12.447 0 .916-.033 1.363-.033.273 0 .96.033 1.233.033.066 0 .196 0 .196-.218 0-.12-.109-.12-.25-.12-.677 0-.677-.077-.71-.393L6.24-7.549c-.022-.218-.022-.262-.207-.262-.175 0-.218.076-.284.186l-3.796 6.37zm1.309-1.603l2.149-3.6.349 3.6H3.262z"/><path id="g1-66" d="M1.745-.85c-.109.425-.13.512-.992.512-.186 0-.295 0-.295.218 0 .12.098.12.295.12h3.894c1.724 0 3.011-1.287 3.011-2.356 0-.786-.633-1.419-1.69-1.539 1.134-.207 2.28-1.014 2.28-2.05 0-.808-.72-1.506-2.03-1.506H2.553c-.208 0-.317 0-.317.218 0 .12.099.12.306.12.022 0 .229 0 .414.022.197.022.295.033.295.175 0 .043-.011.076-.044.207L1.745-.851zm1.648-3.143l.676-2.705c.098-.382.12-.415.59-.415h1.406c.96 0 1.19.644 1.19 1.124 0 .96-.939 1.996-2.27 1.996H3.393zM2.902-.338c-.153 0-.175 0-.24-.011-.11-.011-.142-.022-.142-.11 0-.032 0-.054.055-.25l.752-3.044H5.39c1.047 0 1.255.808 1.255 1.277 0 1.08-.971 2.138-2.259 2.138H2.902z"/><path id="g1-67" d="M8.29-7.582a.11.11 0 00-.12-.109c-.032 0-.043.011-.163.131l-.763.84c-.099-.153-.6-.97-1.811-.97C3-7.69.545-5.28.545-2.75.545-.95 1.833.24 3.502.24c.949 0 1.778-.436 2.356-.938 1.015-.895 1.2-1.887 1.2-1.92 0-.11-.109-.11-.13-.11-.066 0-.12.023-.143.11-.098.316-.349 1.09-1.101 1.723-.753.611-1.44.797-2.008.797-.981 0-2.138-.567-2.138-2.27 0-.621.23-2.388 1.32-3.665.666-.774 1.691-1.32 2.662-1.32 1.113 0 1.756.84 1.756 2.106 0 .436-.032.447-.032.556s.12.11.163.11c.142 0 .142-.023.197-.219l.687-2.782z"/><path id="g1-68" d="M1.735-.85c-.11.425-.131.512-.993.512-.186 0-.306 0-.306.207C.436 0 .535 0 .742 0h3.61c2.27 0 4.419-2.302 4.419-4.69 0-1.54-.927-2.76-2.564-2.76H2.542c-.207 0-.327 0-.327.206 0 .131.098.131.316.131.142 0 .338.011.469.022.175.022.24.055.24.175 0 .043-.01.076-.044.207L1.735-.851zM4.09-6.699c.098-.382.12-.415.589-.415h1.167c1.07 0 1.975.578 1.975 2.018 0 .535-.218 2.324-1.146 3.524-.316.404-1.178 1.233-2.52 1.233H2.924c-.153 0-.175 0-.24-.011-.11-.011-.142-.022-.142-.11 0-.032 0-.054.054-.25L4.091-6.7z"/><path id="g1-69" d="M7.724-2.542c.021-.054.054-.13.054-.153 0-.01 0-.12-.13-.12-.099 0-.12.066-.143.131C6.796-1.069 6.393-.338 4.527-.338H2.935c-.153 0-.175 0-.24-.011-.11-.011-.142-.022-.142-.11 0-.032 0-.054.054-.25l.742-2.978h1.08c.927 0 .927.229.927.502 0 .076 0 .207-.076.534a.331.331 0 00-.033.12c0 .055.044.12.142.12.087 0 .12-.054.164-.218l.622-2.553c0-.065-.055-.12-.131-.12-.099 0-.12.066-.153.197-.23.829-.426 1.08-1.43 1.08H3.437l.655-2.63c.098-.381.109-.425.589-.425h1.538c1.331 0 1.658.316 1.658 1.21 0 .263 0 .285-.043.58 0 .065-.011.14-.011.195s.033.131.13.131c.12 0 .132-.065.153-.272l.219-1.888c.032-.294-.022-.294-.295-.294H2.52c-.218 0-.327 0-.327.218 0 .12.098.12.305.12.404 0 .71 0 .71.196 0 .044 0 .066-.055.262L1.713-.85c-.11.426-.131.513-.993.513-.185 0-.305 0-.305.207C.415 0 .513 0 .72 0h5.662c.25 0 .262-.01.338-.185l1.004-2.357z"/><path id="g1-70" d="M3.305-3.545h1.059c.818 0 .905.174.905.49 0 .077 0 .208-.076.535a.396.396 0 00-.033.12c0 .087.065.13.13.13.11 0 .11-.032.165-.228l.6-2.367c.032-.12.032-.142.032-.175 0-.022-.022-.12-.13-.12s-.12.055-.164.23c-.23.85-.48 1.046-1.408 1.046h-.992l.698-2.77c.098-.382.109-.426.589-.426h1.44c1.342 0 1.593.36 1.593 1.2 0 .25 0 .295-.033.59-.022.14-.022.163-.022.195 0 .055.033.131.131.131.12 0 .131-.065.153-.272l.218-1.888c.033-.294-.022-.294-.295-.294H2.52c-.218 0-.327 0-.327.218 0 .12.098.12.305.12.404 0 .71 0 .71.196 0 .044 0 .066-.055.262L1.713-.85c-.11.426-.131.513-.993.513-.185 0-.305 0-.305.207C.415 0 .545 0 .578 0c.317 0 1.124-.033 1.44-.033.36 0 1.266.033 1.626.033.098 0 .229 0 .229-.207 0-.088-.066-.11-.066-.12-.032-.011-.054-.011-.305-.011-.24 0-.295 0-.567-.022-.317-.033-.35-.076-.35-.218 0-.022 0-.087.044-.251l.676-2.716z"/><path id="g1-71" d="M8.29-7.582a.11.11 0 00-.12-.109c-.032 0-.043.011-.163.131l-.763.84c-.099-.153-.6-.97-1.811-.97C3-7.69.545-5.28.545-2.75.545-1.014 1.756.24 3.524.24c.48 0 .97-.098 1.363-.262.546-.218.753-.447.95-.665.098.272.381.676.49.676.055 0 .077-.033.077-.044.021-.021.13-.436.185-.665l.207-.84c.044-.185.099-.37.142-.556.12-.491.131-.513.753-.524.054 0 .174-.01.174-.218 0-.077-.054-.12-.141-.12-.251 0-.895.033-1.146.033-.338 0-1.189-.033-1.527-.033-.098 0-.23 0-.23.218 0 .12.088.12.328.12.011 0 .327 0 .578.022.284.033.338.065.338.207 0 .098-.12.59-.229.993-.305 1.2-1.723 1.32-2.105 1.32-1.047 0-2.193-.622-2.193-2.291 0-.338.11-2.138 1.255-3.556.589-.742 1.647-1.408 2.727-1.408 1.113 0 1.756.84 1.756 2.106 0 .436-.032.447-.032.556s.12.11.163.11c.142 0 .142-.023.197-.219l.687-2.782z"/><path id="g1-72" d="M8.324-6.61c.098-.394.12-.503.916-.503.284 0 .37 0 .37-.218 0-.12-.12-.12-.152-.12-.305 0-1.09.033-1.396.033-.317 0-1.091-.033-1.407-.033-.088 0-.208 0-.208.218 0 .12.098.12.306.12.022 0 .229 0 .414.022.197.022.295.033.295.175 0 .043-.011.065-.044.207l-.654 2.662H3.436l.644-2.564c.098-.393.13-.502.916-.502.284 0 .371 0 .371-.218 0-.12-.12-.12-.152-.12-.306 0-1.091.033-1.397.033-.316 0-1.09-.033-1.407-.033-.087 0-.207 0-.207.218 0 .12.098.12.305.12.022 0 .23 0 .415.022.196.022.294.033.294.175 0 .043-.01.076-.043.207L1.713-.851c-.11.426-.131.513-.993.513-.196 0-.295 0-.295.218 0 .12.131.12.153.12.306 0 1.08-.033 1.386-.033.229 0 .469.011.698.011.24 0 .48.022.709.022.087 0 .218 0 .218-.218 0-.12-.098-.12-.305-.12-.404 0-.71 0-.71-.197 0-.065.022-.12.033-.185l.742-2.99h3.327c-.458 1.812-.709 2.848-.752 3.012-.11.349-.317.36-.993.36-.164 0-.262 0-.262.218 0 .12.131.12.153.12.305 0 1.08-.033 1.385-.033.23 0 .47.011.698.011.24 0 .48.022.71.022.087 0 .218 0 .218-.218 0-.12-.098-.12-.306-.12-.403 0-.709 0-.709-.197 0-.065.022-.12.033-.185l1.473-5.89z"/><path id="g1-79" d="M8.073-4.756c0-1.757-1.157-2.935-2.782-2.935C2.935-7.69.535-5.215.535-2.673.535-.862 1.756.24 3.327.24c2.313 0 4.746-2.39 4.746-4.996zM3.393-.044c-1.08 0-1.844-.883-1.844-2.323 0-.48.153-2.073.993-3.35.753-1.134 1.822-1.701 2.683-1.701.895 0 1.877.61 1.877 2.236 0 .786-.295 2.487-1.375 3.83C5.204-.688 4.31-.045 3.393-.045z"/><path id="g1-80" d="M3.305-3.447H5.16c1.55 0 3.065-1.135 3.065-2.357 0-.84-.72-1.647-2.149-1.647H2.542c-.207 0-.327 0-.327.207 0 .131.098.131.316.131.142 0 .338.011.469.022.175.022.24.055.24.175 0 .043-.01.076-.044.207L1.735-.851c-.11.426-.131.513-.993.513-.186 0-.306 0-.306.207C.436 0 .567 0 .6 0c.305 0 1.08-.033 1.385-.033.23 0 .47.011.699.011.24 0 .48.022.709.022.076 0 .218 0 .218-.218 0-.12-.098-.12-.306-.12-.403 0-.709 0-.709-.197 0-.065.022-.12.033-.185l.676-2.727zm.786-3.251c.098-.382.12-.415.589-.415h1.047c.906 0 1.484.295 1.484 1.048 0 .425-.218 1.363-.644 1.756-.545.49-1.2.578-1.68.578H3.35l.742-2.967z"/><path id="g0-2" d="M2.204 12.644h2.094v-.437H2.64V0h1.658v-.436H2.204v13.08z"/><path id="g0-3" d="M2.335 12.644V-.436H.24V0h1.658v12.207H.24v.437h2.095z"/><path id="g0-50" d="M3.556 19.2h.753V.327h2.88v-.752H3.556V19.2z"/><path id="g0-51" d="M2.956 19.2h.753V-.425H.076v.752h2.88V19.2z"/><path id="g0-52" d="M3.556 19.19H7.19v-.754H4.31V-.436h-.753v19.625z"/><path id="g0-53" d="M2.956 18.436H.076v.753H3.71V-.436h-.753v18.872z"/><path id="g0-54" d="M3.556 6.556h.753V-.01h-.753v6.567z"/><path id="g0-55" d="M2.956 6.556h.753V-.01h-.753v6.567z"/></defs><g id="page1"><use x="1872.02" y="1504.205" xlink:href="#g0-2"/><use x="1876.565" y="1513.024" xlink:href="#g1-79"/><use x="1885.189" y="1513.024" xlink:href="#g1-59"/><use x="1898.182" y="1513.024" xlink:href="#g1-80"/><use x="1906.701" y="1504.205" xlink:href="#g0-3"/><use x="1914.277" y="1513.041" xlink:href="#g2-61"/><use x="1925.792" y="1484.568" xlink:href="#g0-50"/><use x="1925.792" y="1503.769" xlink:href="#g0-54"/><use x="1925.792" y="1510.314" xlink:href="#g0-54"/><use x="1925.792" y="1517.296" xlink:href="#g0-52"/><use x="1933.065" y="1492.7" xlink:href="#g1-65"/><use x="1941.247" y="1492.7" xlink:href="#g1-59"/><use x="1954.496" y="1492.7" xlink:href="#g1-66"/><use x="1963.318" y="1492.7" xlink:href="#g1-59"/><use x="1976.568" y="1492.7" xlink:href="#g1-69"/><use x="1985.249" y="1492.7" xlink:href="#g1-59"/><use x="1998.954" y="1492.7" xlink:href="#g1-70"/><use x="1933.065" y="1506.249" xlink:href="#g1-65"/><use x="1941.247" y="1506.249" xlink:href="#g1-59"/><use x="1954.496" y="1506.249" xlink:href="#g1-66"/><use x="1963.318" y="1506.249" xlink:href="#g1-59"/><use x="1976.62" y="1506.249" xlink:href="#g1-71"/><use x="1985.197" y="1506.249" xlink:href="#g1-59"/><use x="1998.242" y="1506.249" xlink:href="#g1-72"/><use x="1933.17" y="1519.799" xlink:href="#g1-67"/><use x="1941.141" y="1519.799" xlink:href="#g1-59"/><use x="1954.24" y="1519.799" xlink:href="#g1-68"/><use x="1963.575" y="1519.799" xlink:href="#g1-59"/><use x="1976.568" y="1519.799" xlink:href="#g1-69"/><use x="1985.249" y="1519.799" xlink:href="#g1-59"/><use x="1998.954" y="1519.799" xlink:href="#g1-70"/><use x="1933.17" y="1533.348" xlink:href="#g1-67"/><use x="1941.141" y="1533.348" xlink:href="#g1-59"/><use x="1954.24" y="1533.348" xlink:href="#g1-68"/><use x="1963.575" y="1533.348" xlink:href="#g1-59"/><use x="1976.62" y="1533.348" xlink:href="#g1-71"/><use x="1985.197" y="1533.348" xlink:href="#g1-59"/><use x="1998.242" y="1533.348" xlink:href="#g1-72"/><use x="2008.197" y="1484.568" xlink:href="#g0-51"/><use x="2008.197" y="1503.769" xlink:href="#g0-55"/><use x="2008.197" y="1510.314" xlink:href="#g0-55"/><use x="2008.197" y="1517.296" xlink:href="#g0-53"/></g><script type="text/ecmascript">if(window.parent.postMessage)window.parent.postMessage(&quot;29.578|176.25|66|&quot;+window.location,&quot;*&quot;);</script></svg>
\ No newline at end of file

From 2af715083010751696e149d44a2075cd922646bb Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Thu, 16 Jun 2022 14:41:59 -0400
Subject: [PATCH 07/31] Updates from Working Group

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 buildpack.md | 34 ++++++++++++++++------------------
 1 file changed, 16 insertions(+), 18 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index 7bcd7a70..6cd61ecf 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -73,7 +73,7 @@ This document specifies the interface between a lifecycle program and one or mor
       - [Build Plan (TOML) `requires.version` Key](#build-plan-toml-requiresversion-key)
 
 ## Buildpack API Version
-This document specifies Buildpack API version `0.7`
+This document specifies Buildpack API version `0.9`
 
 Buildpack API versions:
  - MUST be in form `<major>.<minor>` or `<major>`, where `<major>` is equivalent to `<major>.0`
@@ -90,17 +90,19 @@ A **buildpack group**, or **group**, is a list of one or more buildpacks that ar
 
 An **order** is a list of one or more groups to be tested against application source code, so that the appropriate group for a build can be determined. 
 
-An **executable buildpack** is a buildpack containing `/bin/detect` and `/bin/build` executables.
+A **component buildpack** is a buildpack containing `/bin/detect` and `/bin/build` executables.
 
-An **order buildpack** is a buildpack containing an order definition in `buildpack.toml`. Order buildpacks do not contain `/bin/detect` or `/bin/build` executables.
+A **composite buildpack** is a buildpack containing an order definition in `buildpack.toml`. Composite buildpacks do not contain `/bin/detect` or `/bin/build` executables.
 
-**Resolving an order** is the process by which an order (which may contain order buildpacks) is evaluated together with application source code to produce a group of executable buildpacks that can be used to build the application. This process is known as **detection**. During detection, the `/bin/detect` executable for each executable buildpack is invoked, and the group that is returned is the first group where `/bin/detect` returns true for all non-optional executable buildpacks.
+**Resolving an order** is the process by which an order (which may contain composite buildpacks) is evaluated together with application source code to produce a group of component buildpacks that can be used to build the application. This process is known as **detection**. During detection, the `/bin/detect` executable for each component buildpack is invoked.
 
-A **lifecycle** is software that orchestrates a build. It executes in a series of phases that each have a distinct responsibility:
-  1. **Detection,** where an optimal selection of compatible buildpacks is chosen by resolving the provided order.
-  2. **Analysis,** where metadata about OCI layers generated during a previous build are made available to executable buildpacks in the selected group.
-  3. **Build,** where the `bin/build` for each executable buildpack in the selected group is invoked, in order, to build the application.
-  4. **Export,** where filesystem changes from the build phase are packaged into layers in an OCI image.
+An **optional buildpack** is a buildpack (either component or composite) that, when failing detection, will be excluded from the group without causing the entire group to fail.
+
+A **build plan** is a file used during detection, in which each component buildpack may express the dependencies that it requires and the dependencies that it provides. A group of component buildpacks will only pass detection if a valid build plan can be produced from the dependencies that all component buildpacks in the group require and provide. A valid build plan is a plan where all required dependencies are provided in the necessary order, meaning that during the build phase, each component buildpack will have its required dependencies provided by a component buildpack that runs before it.
+
+A **buildpack plan** is a file unique to each component buildpack, used during the build phase to communicate the dependencies that the component buildpack is expected to provide.
+
+A **lifecycle** is software that orchestrates a build. It executes in a series of phases that each have a distinct responsibility.
 
 A **launcher** is an executable that is the `ENTRYPOINT` of the exported OCI image. It is used to start processes at runtime. Having a launcher enables multiple process types to be defined on an image, with process-specific environment variables and other functionality.
 
@@ -108,23 +110,19 @@ A **launcher** is an executable that is the `ENTRYPOINT` of the exported OCI ima
 
 A **platform** is a system or software that orchestrates the lifecycle by invoking each lifecycle phase in order.
 
-A **process type** is a definition, provided by executable buildpacks during the build phase, of a process to launch at runtime.
-
-A **build plan** is a file used during detection, in which each executable buildpack may express the dependencies that it requires and the dependencies that it provides. A group of executable buildpacks will only pass detection if a valid build plan can be produced from the dependencies that all executable buildpacks in the group require and provide. A valid build plan is a plan where all required dependencies are provided in the necessary order, meaning that during the build phase, each executable buildpack will have its required dependencies provided by an executable buildpack that runs before it.
-
-A **buildpack plan** is a file unique to each executable buildpack, used during the build phase to communicate the dependencies that the executable buildpack is expected to provide.
+A **process definition** is a description, provided by component buildpacks during the build phase, of a process to launch at runtime.
 
-An **application directory** is a directory containing application source code. Executable buildpacks may make changes to the application directory during the build phase.
+An **application directory** is a directory containing application source code. Component buildpacks may make changes to the application directory during the build phase.
 
 A **layer** is a set of filesystem changes packaged according to the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/main/layer.md).
 
-A **layer directory** is a directory created by an executable buildpack that contains build and/or runtime dependencies, and can be used to configure the build and/or runtime environment. There are three **layer types**:
-  * a **launch layer** is added as a layer in the exported OCI image; it can be re-used on the next build (the lifecycle can avoid re-uploading it) if the executable buildpack that created the layer has the same requirements on the next build
+A **layer directory** is a directory created by a component buildpack that contains build and/or runtime dependencies, and can be used to configure the build and/or runtime environment. There are three **layer types**:
+  * a **launch layer** is added as a layer in the exported OCI image; it can be re-used on the next build (the lifecycle can avoid re-uploading it) if the component buildpack that created the layer has the same requirements on the next build
   * a **cache layer** is saved to the cache and its contents may be restored on the next build
   * a **build layer** contains child directories with paths that are added to the environment (e.g., `PATH`, `LD_LIBRARY_PATH`, etc.) for subsequent buildpacks in the same build
 Any combination of the three layer types are valid for a particular layer directory.
 
-A **stack** is a contract, implemented by a **build image** and **run image**, that guarantees properties of the **build environment** and **app image**. The provided stack is communicated to executable buildpacks through the `CNB_STACK_ID` environment variable, enabling each executable buildpack to modify its behavior when executed on different stacks.
+A **stack** is a contract, implemented by a **build image** and **run image**, that guarantees properties of the **build environment** and **app image**. The provided stack is communicated to component buildpacks through the `CNB_STACK_ID` environment variable, enabling each component buildpack to modify its behavior when executed on different stacks.
 
 A **mixin** is a named set of additions to a stack that can be used to make additive changes to the contract. Buildpacks can express their required mixins in `buildpack.toml`.
 

From 8e70e24e4a0cfa85d077021790c59ab948b87ea9 Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Thu, 16 Jun 2022 14:57:32 -0400
Subject: [PATCH 08/31] Update rest of buildpack.md with terminology

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 buildpack.md | 26 ++++++++++++--------------
 1 file changed, 12 insertions(+), 14 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index 75c9d474..c3c2ef2d 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -89,9 +89,9 @@ A **buildpack group**, or **group**, is a list of one or more buildpacks that ar
 
 An **order** is a list of one or more groups to be tested against application source code, so that the appropriate group for a build can be determined. 
 
-A **component buildpack** is a buildpack containing `/bin/detect` and `/bin/build` executables.
+A **component buildpack** is a buildpack containing `/bin/detect` and `/bin/build` executables. Component buildpacks implement the [Buildpack Interface](#buildpack-interface).
 
-A **composite buildpack** is a buildpack containing an order definition in `buildpack.toml`. Composite buildpacks do not contain `/bin/detect` or `/bin/build` executables.
+A **composite buildpack** is a buildpack containing an order definition in `buildpack.toml`. Composite buildpacks do not contain `/bin/detect` or `/bin/build` executables. They MUST be [resolvable](#order-resolution) into a collection of component buildpacks.
 
 **Resolving an order** is the process by which an order (which may contain composite buildpacks) is evaluated together with application source code to produce a group of component buildpacks that can be used to build the application. This process is known as **detection**. During detection, the `/bin/detect` executable for each component buildpack is invoked.
 
@@ -127,8 +127,8 @@ A **mixin** is a named set of additions to a stack that can be used to make addi
 
 ## Buildpack Interface
 
-The following specifies the interface implemented by executables in each buildpack.
-The lifecycle MUST invoke these executables as described in the Phase sections.
+The following specifies the interface implemented by component buildpacks.
+The lifecycle MUST invoke executables in component buildpacks as described in the Phase sections.
 
 ### Buildpack API Compatibility
 Given a buildpack declaring `<buildpack API Version>` in its [`buildpack.toml`](#buildpacktoml-toml), the lifecycle:
@@ -340,7 +340,7 @@ At the end of each individual buildpack's build phase:
 
 ### Purpose
 
-The purpose of detection is to find an ordered group of buildpacks to use during the build phase.
+The purpose of detection is to find an ordered group of component buildpacks to use during the build phase.
 These buildpacks must be compatible with the app.
 
 ### Process
@@ -472,7 +472,7 @@ If a buildpack order entry within a group has the parameter `optional = true`, t
 
 ### Purpose
 
-The purpose of analysis is to restore `<layers>/<layer>.toml`, `<layers>/<layer>.sbom.<ext>`, and `<layers>/store.toml` files that buildpacks may use to optimize the build and export phases.
+The purpose of analysis is to restore `<layers>/<layer>.toml`, `<layers>/<layer>.sbom.<ext>`, and `<layers>/store.toml` files that component buildpacks may use to optimize the build and export phases.
 
 ### Process
 
@@ -503,7 +503,7 @@ After analysis, the lifecycle MUST proceed to the build phase.
 
 The purpose of build is to transform application source code into runnable artifacts that can be packaged into a container image.
 
-During the build phase, typical buildpacks might:
+During the build phase, typical component buildpacks might:
 
 1. Read the Buildpack Plan in `<plan>` to determine what dependencies to provide.
 1. Provide the application with dependencies for launch in `<layers>/<layer>`.
@@ -935,7 +935,7 @@ working-dir = "<working directory>"
 paths = ["<app sub-path glob>"]
 ```
 
-The buildpack MAY specify any number of labels, processes, or slices.
+The component buildpack MAY specify any number of labels, processes, or slices.
 
 For each label, the buildpack:
 
@@ -984,7 +984,7 @@ The lifecycle MUST include all unmatched files in the app directory in any numbe
 name = "<dependency name>"
 ```
 
-For each unmet entry in the Buildpack Plan, the buildpack:
+For each unmet entry in the Buildpack Plan, the component buildpack:
 - SHOULD add an entry to `unmet`.
 
 For each entry in `unmet`:
@@ -1118,9 +1118,9 @@ The `[[buildpack.licenses]]` table is optional and MAY contain a list of buildpa
 *Key: `sbom-formats = [ "<string>" ]`*
  - MUST be supported SBOM media types as described in [Software-Bill-of-Materials](#software-bill-of-materials).
 
-#### Buildpack Implementations
+#### Stacks
 
-A buildpack descriptor that specifies `stacks` MUST describe a buildpack that implements the [Buildpack Interface](#buildpack-interface).
+A buildpack descriptor may specify `stacks`.
 
 Each stack in `stacks` either:
 - MUST identify a compatible stack:
@@ -1130,9 +1130,7 @@ Each stack in `stacks` either:
    - `id` MUST be set to the special value `"*"`.
    - `mixins` MUST be empty.
 
-#### Order Buildpacks
-
-A buildpack descriptor that specifies `order` MUST be [resolvable](#order-resolution) into an ordering of buildpacks that implement the [Buildpack Interface](#buildpack-interface).
+#### Order
 
 A buildpack reference inside of a `group` MUST contain an `id` and `version`.
 

From b75f220834a03c70d0199712d63051a4ad1a1411 Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Thu, 16 Jun 2022 15:01:37 -0400
Subject: [PATCH 09/31] More changes

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 buildpack.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index c3c2ef2d..d31a92a6 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -64,8 +64,8 @@ This document specifies the interface between a lifecycle program and one or mor
     - [Buildpack Plan (TOML)](#buildpack-plan-toml)
     - [Layer Content Metadata (TOML)](#layer-content-metadata-toml)
     - [buildpack.toml (TOML)](#buildpacktoml-toml)
-      - [Buildpack Implementations](#buildpack-implementations)
-      - [Order Buildpacks](#order-buildpacks)
+      - [Stacks](#stacks)
+      - [Order](#order)
     - [Exec.d Output (TOML)](#execd-output-toml)
   - [Deprecations](#deprecations)
     - [`0.3`](#03)
@@ -346,7 +346,7 @@ These buildpacks must be compatible with the app.
 ### Process
 
 **GIVEN:**
-- An ordered list of buildpack groups resolved into buildpack implementations as described in [Order Resolution](#order-resolution)
+- An ordered list of buildpack groups resolved into component buildpacks as described in [Order Resolution](#order-resolution)
 - A directory containing application source code
 - A shell, if needed,
 
@@ -412,13 +412,13 @@ A buildpack's mixin requirements must be satisfied by the stack in one of the fo
 
 #### Order Resolution
 
-During detection, an order definition MUST be resolved into individual buildpack implementations.
+During detection, an order definition MUST be resolved into individual component buildpacks.
 
 The resolution process MUST follow this pattern:
 
 Where:
 - O and P are buildpack orders.
-- A through H are buildpack implementations.
+- A through H are component buildpacks.
 
 Given:
 

From 02533133130e1fe72179a4e9c596bb6f78819b02 Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Mon, 27 Jun 2022 11:48:04 -0400
Subject: [PATCH 10/31] Updates from PR review

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 buildpack.md       | 2 +-
 image_extension.md | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index 64f7a032..0c2e9f68 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -514,7 +514,7 @@ After analysis, the lifecycle MUST proceed to the build phase.
 
 ### Purpose
 
-The purpose of the generation phase is to generate Dockerfiles that can be used to select the runtime base image.
+The purpose of the generation phase is to generate Dockerfiles that can be used to define the runtime base image.
 
 ### Process
 
diff --git a/image_extension.md b/image_extension.md
index 350a899a..eda36806 100644
--- a/image_extension.md
+++ b/image_extension.md
@@ -44,14 +44,14 @@ Executable: `/bin/generate`, Working Dir: `<app[AR]>`
 
 Image extensions participate in a generation process that is similar to the buildpack [build](buildpack.md#build) process, with an interface that is similar to `/bin/build`. However:
 - Image extensions' `/bin/generate` MUST NOT write to the app directory.
-- Instead of the `CNB_LAYERS_DIR`, image extensions receive a `CNB_OUTPUT_DIR` which MUST be the absolute path of an `<output>` directory and MUST NOT be the path of the buildpack layers directory.
+- Instead of the `CNB_LAYERS_DIR` input, image extensions MUST receive a `CNB_OUTPUT_DIR` which MUST be the absolute path of an `<output>` directory and MUST NOT be the path of the buildpack layers directory.
 - If an image extension is missing `/bin/generate`, the image extension root MUST be treated as a pre-populated `<output>` directory.
 
 ## Phase: Generation
 
 ### Purpose
 
-The purpose of the generation phase is to generate Dockerfiles that can be used to select the runtime base image.
+The purpose of the generation phase is to generate Dockerfiles that can be used to define the runtime base image.
 
 ### Process
 

From d6324b54885b3abf6b113db27f5ac0cc62b6dadc Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Mon, 27 Jun 2022 15:38:00 -0400
Subject: [PATCH 11/31] Update terminology section for image extensions

Also make clear that generation is for extensions and build is for buildpacks

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 buildpack.md       | 16 +++++++++-------
 image_extension.md |  2 --
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index 0c2e9f68..a4e69cea 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -89,7 +89,7 @@ Buildpack API versions:
 
 ### CNB Terminology
 
-A **buildpack** is a directory containing a `buildpack.toml`. A buildpack analyzes application source code and determines the best way to build it.
+A **buildpack** is a directory containing a `buildpack.toml`. Buildpacks analyze application source code and determine the best way to build it.
 
 A **buildpack group**, or **group**, is a list of one or more buildpacks that are designed to work together - for example, a buildpack that provides `node` and a buildpack that provides `npm`.
 
@@ -99,13 +99,15 @@ A **component buildpack** is a buildpack containing `/bin/detect` and `/bin/buil
 
 A **composite buildpack** is a buildpack containing an order definition in `buildpack.toml`. Composite buildpacks do not contain `/bin/detect` or `/bin/build` executables. They MUST be [resolvable](#order-resolution) into a collection of component buildpacks.
 
-**Resolving an order** is the process by which an order (which may contain composite buildpacks) is evaluated together with application source code to produce a group of component buildpacks that can be used to build the application. This process is known as **detection**. During detection, the `/bin/detect` executable for each component buildpack is invoked.
+An **image extension** (**experimental**) is a directory containing an `extension.toml`. Extensions generate Dockerfiles that can be used to define the runtime base image, prior to buildpack execution. Extensions implement the [Image Extension Interface](image-extension.md). Extensions are always "component": their `extension.toml` cannot contain an order definition.
 
-An **optional buildpack** is a buildpack (either component or composite) that, when failing detection, will be excluded from the group without causing the entire group to fail.
+**Resolving an order** is the process by which an order (which may contain image extensions, component buildpacks, or composite buildpacks) is evaluated together with application source code to produce an optional group of image extensions and a required group of component buildpacks that can be used to build the application. This process is known as **detection**. During detection, the `/bin/detect` executable for each image extension (if present) and the `/bin/detect` executable for each component buildpack is invoked.
 
-A **build plan** is a file used during detection, in which each component buildpack may express the dependencies that it requires and the dependencies that it provides. A group of component buildpacks will only pass detection if a valid build plan can be produced from the dependencies that all component buildpacks in the group require and provide. A valid build plan is a plan where all required dependencies are provided in the necessary order, meaning that during the build phase, each component buildpack will have its required dependencies provided by a component buildpack that runs before it.
+An **optional** buildpack or extension is a group element that, when failing detection, will be excluded from the group without causing the entire group to fail.
 
-A **buildpack plan** is a file unique to each component buildpack, used during the build phase to communicate the dependencies that the component buildpack is expected to provide.
+A **build plan** is a file used during detection, in which each image extension or component buildpack may express the dependencies that it requires and the dependencies that it provides. A group will only pass detection if a valid build plan can be produced from the dependencies that all elements in the group require and provide. A valid build plan is a plan where all required dependencies are provided in the necessary order, meaning that during the build phase, each component buildpack will have its required dependencies provided by an image extension or component buildpack that runs before it.
+
+A **buildpack plan** is a file unique to each image extension or component buildpack, used during the generation or build phase to communicate the dependencies that it is expected to provide.
 
 A **lifecycle** is software that orchestrates a build. It executes in a series of phases that each have a distinct responsibility.
 
@@ -510,7 +512,7 @@ For each buildpack in the group, the lifecycle
 
 After analysis, the lifecycle MUST proceed to the build phase.
 
-## Phase #3: Generation (optional)
+## Phase #3: Generation (image extensions only)
 
 ### Purpose
 
@@ -520,7 +522,7 @@ The purpose of the generation phase is to generate Dockerfiles that can be used
 
 See the [Image Extension Specification](#image-extension.md).
 
-## Phase #4: Build
+## Phase #4: Build (component buildpacks only)
 
 ![Build](img/build.svg)
 
diff --git a/image_extension.md b/image_extension.md
index eda36806..33a796ce 100644
--- a/image_extension.md
+++ b/image_extension.md
@@ -2,8 +2,6 @@
 
 This document specifies the interface between a lifecycle program and one or more image extensions.
 
-The lifecycle program uses image extensions to generate Dockerfiles that can be used to select the runtime base image prior to buildpack builds.
-
 ## Table of Contents
 
 <!-- Using https://github.com/yzhang-gh/vscode-markdown to manage toc -->

From ba59390341e096998f42f9dd104039b95adc8a45 Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Thu, 7 Jul 2022 11:40:56 -0400
Subject: [PATCH 12/31] Add nested output directories

A couple other small fixes.

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 buildpack.md       | 4 ++--
 image_extension.md | 6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index a4e69cea..d6328dec 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -103,7 +103,7 @@ An **image extension** (**experimental**) is a directory containing an `extensio
 
 **Resolving an order** is the process by which an order (which may contain image extensions, component buildpacks, or composite buildpacks) is evaluated together with application source code to produce an optional group of image extensions and a required group of component buildpacks that can be used to build the application. This process is known as **detection**. During detection, the `/bin/detect` executable for each image extension (if present) and the `/bin/detect` executable for each component buildpack is invoked.
 
-An **optional** buildpack or extension is a group element that, when failing detection, will be excluded from the group without causing the entire group to fail.
+An **optional** image extension or buildpack is a group element that, when failing detection, will be excluded from the group without causing the entire group to fail.
 
 A **build plan** is a file used during detection, in which each image extension or component buildpack may express the dependencies that it requires and the dependencies that it provides. A group will only pass detection if a valid build plan can be produced from the dependencies that all elements in the group require and provide. A valid build plan is a plan where all required dependencies are provided in the necessary order, meaning that during the build phase, each component buildpack will have its required dependencies provided by an image extension or component buildpack that runs before it.
 
@@ -425,7 +425,7 @@ A buildpack's mixin requirements must be satisfied by the stack in one of the fo
 
 #### Order Resolution
 
-During detection, an order definition for image extensions (if present) and an order definition for buildpacks MUST be resolved into a group of image extensions and component buildpacks.
+During detection, an order definition for image extensions (if present) and an order definition for buildpacks MUST be resolved into a group of image extensions and a group of component buildpacks.
 
 Order definitions for image extensions MUST NOT contain nested orders.
 
diff --git a/image_extension.md b/image_extension.md
index 33a796ce..d9551e86 100644
--- a/image_extension.md
+++ b/image_extension.md
@@ -33,7 +33,7 @@ Executable: `/bin/detect`, Working Dir: `<app[AR]>`
 
 Image extensions participate in the buildpack [detection](buildpack.md#detection) process, with the same interface for `/bin/detect`. However:
 - Detection is optional for image extensions, and they are assumed to pass detection when `/bin/detect` is not present.
-- If an image extension is missing `/bin/detect`, the image extension root MUST be treated as a pre-populated `<output>` directory.
+- If an image extension is missing `/bin/detect`, the image extension root `/detect` directory MUST be treated as a pre-populated `<output>` directory.
 - Image extensions MUST only output `provides` entries to the build plan. They MUST NOT output `requires`.
 
 ### Generation
@@ -43,7 +43,7 @@ Executable: `/bin/generate`, Working Dir: `<app[AR]>`
 Image extensions participate in a generation process that is similar to the buildpack [build](buildpack.md#build) process, with an interface that is similar to `/bin/build`. However:
 - Image extensions' `/bin/generate` MUST NOT write to the app directory.
 - Instead of the `CNB_LAYERS_DIR` input, image extensions MUST receive a `CNB_OUTPUT_DIR` which MUST be the absolute path of an `<output>` directory and MUST NOT be the path of the buildpack layers directory.
-- If an image extension is missing `/bin/generate`, the image extension root MUST be treated as a pre-populated `<output>` directory.
+- If an image extension is missing `/bin/generate`, the image extension root `/generate` directory MUST be treated as a pre-populated `<output>` directory.
 
 ## Phase: Generation
 
@@ -122,7 +122,7 @@ uri = "<uri>"
 
 Image extension authors MUST choose a globally unique ID, for example: "io.buildpacks.apt".
 
-The image extension `id`, `version`, `api`, `licenses`, and `sbom-formats` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md).
+The image extension `id`, `version`, `api`, and `licenses` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md).
 
 ### build.toml (TOML)
 

From a2a0e2d6ab7b051261e2824b3d4b6f10dca61302 Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Tue, 12 Jul 2022 13:44:25 -0400
Subject: [PATCH 13/31] Link to build plan

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 image_extension.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/image_extension.md b/image_extension.md
index d9551e86..bf7ef39c 100644
--- a/image_extension.md
+++ b/image_extension.md
@@ -134,3 +134,7 @@ name = "<dependency name>"
 ```
 
 The image extension `unmet` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md).
+
+### Build Plan (TOML)
+
+See the [Buildpack Interface Specification](buildpack.md).

From e403a02f3c5ce45d6232cf7711d8b5e39acb126e Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Thu, 14 Jul 2022 15:32:01 -0400
Subject: [PATCH 14/31] Updates per 7/14 Working Group

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 buildpack.md       |  6 ++++--
 image_extension.md | 13 ++++---------
 2 files changed, 8 insertions(+), 11 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index d6328dec..0349d784 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -610,12 +610,14 @@ Correspondingly, each `/bin/build` executable:
 
 #### Unmet Buildpack Plan Entries
 
-An image extension or component buildpack SHOULD designate a Buildpack Plan entry as unmet if it did not satisfy the requirement described by the entry.
+A component buildpack SHOULD designate a Buildpack Plan entry as unmet if it did not satisfy the requirement described by the entry.
 The lifecycle SHALL assume that all entries in the Buildpack Plan were satisfied by the buildpack unless the buildpack writes an entry with the given name to the `unmet` section of `build.toml`.
 
+Image extensions MUST satisfy all entries in the Buildpack Plan.
+
 For each entry in `<plan>`:
   - **If** there is an unmet entry in `build.toml` with a matching `name`, the lifecycle
-    - MUST include the entry in the `<plan>` of the next image extension or component buildpack that provided an entry with that name during the detection phase.
+    - MUST include the entry in the `<plan>` of the next component buildpack that provided an entry with that name during the detection phase.
   - **Else**, the lifecycle
     - MUST NOT include entries with matching names in the `<plan>` provided to subsequent image extensions or component buildpacks.
 
diff --git a/image_extension.md b/image_extension.md
index bf7ef39c..9fd14d9a 100644
--- a/image_extension.md
+++ b/image_extension.md
@@ -124,17 +124,12 @@ Image extension authors MUST choose a globally unique ID, for example: "io.build
 
 The image extension `id`, `version`, `api`, and `licenses` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md).
 
-### build.toml (TOML)
-
-This section describes the `build.toml` output by image extensions; for buildpacks see the [Buildpack Interface Specification](buildpack.md).
-
-```toml
-[[unmet]]
-name = "<dependency name>"
-```
-
 The image extension `unmet` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md).
 
 ### Build Plan (TOML)
 
 See the [Buildpack Interface Specification](buildpack.md).
+
+### Buildpack Plan (TOML)
+
+See the [Buildpack Interface Specification](buildpack.md). Image extensions MUST satisfy all entries in the Buildpack Plan.

From f9057980edd74012d51ca05e2ae6750705beb747 Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Thu, 14 Jul 2022 15:34:14 -0400
Subject: [PATCH 15/31] Remove line describing build.toml left in by mistake

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 image_extension.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/image_extension.md b/image_extension.md
index 9fd14d9a..0b83d6d5 100644
--- a/image_extension.md
+++ b/image_extension.md
@@ -124,8 +124,6 @@ Image extension authors MUST choose a globally unique ID, for example: "io.build
 
 The image extension `id`, `version`, `api`, and `licenses` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md).
 
-The image extension `unmet` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md).
-
 ### Build Plan (TOML)
 
 See the [Buildpack Interface Specification](buildpack.md).

From 4578d8ce4cc361299b82a2c197c40289cac6d9e1 Mon Sep 17 00:00:00 2001
From: Mikey Boldt <mboldt@vmware.com>
Date: Fri, 15 Apr 2022 13:19:56 -0500
Subject: [PATCH 16/31] Remove shell-specific logic

Closes #244

Signed-off-by: Mikey Boldt <mboldt@vmware.com>
---
 buildpack.md | 79 ++++++++++------------------------------------------
 1 file changed, 14 insertions(+), 65 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index 38cfef17..86f407a4 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -83,7 +83,7 @@ The `ENTRYPOINT` of the OCI image contains logic implemented by the lifecycle th
       - [Build Plan (TOML) `requires.version` Key](#build-plan-toml-requiresversion-key)
 
 ## Buildpack API Version
-This document specifies Buildpack API version `0.8`
+This document specifies Buildpack API version `0.9`
 
 Buildpack API versions:
  - MUST be in form `<major>.<minor>` or `<major>`, where `<major>` is equivalent to `<major>.0`
@@ -163,15 +163,13 @@ Executable: `/bin/build`, Working Dir: `<app[AI]>`
 | `$CNB_LAYERS_DIR/<layer>.sbom.<ext>`            | Layer Software Bill of Materials (see [Software-Bill-of-Materials](#software-bill-of-materials))                 |
 | `$CNB_LAYERS_DIR/<layer>/bin/`                  | Binaries for launch and/or subsequent buildpacks                                                                 |
 | `$CNB_LAYERS_DIR/<layer>/lib/`                  | Shared libraries for launch and/or subsequent buildpacks                                                         |
-| `$CNB_LAYERS_DIR/<layer>/profile.d/`            | Scripts sourced by Bash before launch                                                                            |
-| `$CNB_LAYERS_DIR/<layer>/profile.d/<process>/`  | Scripts sourced by Bash before launch for a particular process type                                              |
 | `$CNB_LAYERS_DIR/<layer>/exec.d/`               | Executables that provide env vars via the [Exec.d Interface](#execd) before launch                               |
 | `$CNB_LAYERS_DIR/<layer>/exec.d/<process>/`     | Executables that provide env vars for a particular process type via the [Exec.d Interface](#execd) before launch |
 | `$CNB_LAYERS_DIR/<layer>/include/`              | C/C++ headers for subsequent buildpacks                                                                          |
 | `$CNB_LAYERS_DIR/<layer>/pkgconfig/`            | Search path for pkg-config for subsequent buildpacks                                                             |
 | `$CNB_LAYERS_DIR/<layer>/env/`                  | Env vars for launch and/or subsequent buildpacks                                                                 |
-| `$CNB_LAYERS_DIR/<layer>/env.launch/`           | Env vars for launch (after `env`, before `profile.d`)                                                            |
-| `$CNB_LAYERS_DIR/<layer>/env.launch/<process>/` | Env vars for launch (after `env`, before `profile.d`) for the launched process                                   |
+| `$CNB_LAYERS_DIR/<layer>/env.launch/`           | Env vars for launch (after `env`, before `exec.d`)                                                               |
+| `$CNB_LAYERS_DIR/<layer>/env.launch/<process>/` | Env vars for launch (after `env`, before `exec.d`) for the launched process                                      |
 | `$CNB_LAYERS_DIR/<layer>/env.build/`            | Env vars for subsequent buildpacks (after `env`)                                                                 |
 | `$CNB_LAYERS_DIR/<layer>/*`                     | Other content for launch and/or subsequent buildpacks                                                            |
 
@@ -293,13 +291,6 @@ At the end of each individual buildpack's build phase:
 - The lifecycle:
   - MUST rename `<layers>/<layer>/` to `<layers>/<layer>.ignore/` for all layers where `launch = false`, `build = false`, and `cache = false`, in order to prevent subsequent buildpacks from accidentally depending on an ignored layer.
 
-## App Interface
-
-| Output                 | Description
-|------------------------|----------------------------------------------
-| `<app>/.profile`       | [†](README.md#linux-only) Bash-formatted script sourced by shell before launch
-| `<app>/.profile.bat`   | [‡](README.md#windows-only) BAT-formatted script sourced by shell before launch
-
 ## Phase #1: Detection
 
 ![Detection](img/detection.svg)
@@ -314,7 +305,6 @@ These buildpacks must be compatible with the app.
 **GIVEN:**
 - An ordered list of buildpack groups resolved into buildpack implementations as described in [Order Resolution](#order-resolution)
 - A directory containing application source code
-- A shell, if needed,
 
 For each buildpack in each group in order, the lifecycle MUST execute `/bin/detect`.
 
@@ -501,9 +491,8 @@ This is achieved by:
 - The final ordered group of buildpacks determined during the detection phase,
 - A directory containing application source code,
 - The Buildpack Plan,
-- Any `<layers>/<layer>.toml` files placed on the filesystem during the analysis phase,
-- Any locally cached `<layers>/<layer>` directories, and
-- A shell, if needed,
+- Any `<layers>/<layer>.toml` files placed on the filesystem during the analysis phase, and
+- Any locally cached `<layers>/<layer>` directories,
 
 For each buildpack in the group in order, the lifecycle MUST execute `/bin/build`.
 
@@ -684,28 +673,6 @@ The purpose of launch is to modify the running app environment using app-provide
 
 **GIVEN:**
 - An OCI image exported by the lifecycle,
-- A shell, if needed,
-
-First, the lifecycle MUST locate a start command and choose an execution strategy.
-
-To locate a start command, the lifecycle MUST follow the process outlined in the [Platform Interface Specification](platform.md).
-
-To choose an execution strategy,
-
-1. **If** a buildpack-provided process type is chosen as the start command,
-   1. **If** the process type has `direct` set to `false`,
-      1. **If** the process has one or more `args`
-         **Then** the lifecycle MUST invoke a command using the shell, where `command` and each entry in `args` are shell-parsed tokens in the command.
-      2. **If** the process has zero `args`
-         **Then** the lifecycle MUST invoke the value of `command` as a command using the shell.
-
-   2. **If** the process type does have `direct` set to `true`,
-      **Then** the lifecycle MUST invoke the value of `command` using the `execve` syscall with values of `args` provided as arguments.
-
-2. **If** a user-defined process type is chosen as the start command,
-   **Then** the lifecycle MUST select an execution strategy as described in the [Platform Interface Specification](platform.md).
-
-Given the start command and execution strategy,
 
 1. The lifecycle MUST set all buildpack-provided launch environment variables as described in the [Environment](#environment) section.
 
@@ -719,26 +686,9 @@ Given the start command and execution strategy,
       2. Secondly, in alphabetically ascending order by layer directory name.
       3. Thirdly, in alphabetically ascending order by file name.
 
-1. If using an execution strategy involving a shell, the lifecycle MUST use a single shell process, with working directory `<app>`, to
-   1. source each file in each `<layers>/<layer>/profile.d` directory,
-      1. Firstly, in order of `/bin/build` execution used to construct the OCI image.
-      2. Secondly, in alphabetically ascending order by layer directory name.
-      3. Thirdly, in alphabetically ascending order by file name.
-   2. source each file in each `<layers>/<layer>/profile.d/<process>` directory,
-      1. Firstly, in order of `/bin/build` execution used to construct the OCI image.
-      2. Secondly, in alphabetically ascending order by layer directory name.
-      3. Thirdly, in alphabetically ascending order by file name.
-   3. source [†](README.md#linux-only)`<app>/.profile` or [‡](README.md#windows-only)`<app>/.profile.bat` if it is present.
-
-1. The lifecycle MUST set the working directory for the start command to `<working-dir>`, or to `<app>` if `<working-dir>` is not specified.
-
-1. The lifecycle MUST invoke the start command with the decided execution strategy.
-
-[†](README.md#linux-only)When executing a process using any execution strategy, the lifecycle SHOULD replace the lifecycle process in memory without forking it.
-
-[†](README.md#linux-only)When executing a process with Bash, the lifecycle SHOULD additionally replace the Bash process in memory without forking it.
+1. The lifecycle MUST use the `execve` syscall to invoke the command with its arguments, environment, and working directory following the process outlined in the [Platform Interface Specification](platform.md).
 
-[‡](README.md#windows-only)When executing a process with Command Prompt, the lifecycle SHOULD start a new process with the same security context, terminal, working directory, STDIN/STDOUT/STDERR handles and environment variables as the Command Prompt process.
+[†](README.md#linux-only)When executing a process, the lifecycle SHOULD replace the lifecycle process in memory without forking it.
 
 ## Environment
 
@@ -775,7 +725,7 @@ The following additional environment variables MUST NOT be overridden by the lif
 |-----------------|------------------------------------------------|--------|-------|--------
 | `CNB_STACK_ID`  | Chosen stack ID                                | [x]    | [x]   |
 | `BP_*`          | User-provided variable for buildpack           | [x]    | [x]   |
-| `BPL_*`         | User-provided variable for profile.d or exec.d |        |       | [x]
+| `BPL_*`         | User-provided variable for or exec.d           |        |       | [x]
 | `HOME`          | Current user's home directory                  | [x]    | [x]   | [x]
 
 During the detection and build phases, the lifecycle MUST provide any user-provided environment variables as files in `<platform>/env/` with file names and contents matching the environment variable names and contents.
@@ -891,9 +841,8 @@ value = "<label valu>"
 
 [[processes]]
 type = "<process type>"
-command = "<command>"
+command = ["<command>"]
 args = ["<arguments>"]
-direct = false
 default = false
 working-dir = "<working directory>"
 
@@ -917,11 +866,11 @@ For each process, the buildpack:
 - MUST specify a `type`, which:
   - MUST NOT be identical to other process types provided by the same buildpack.
   - MUST only contain numbers, letters, and the characters ., _, and -.
-- MUST specify a `command` that is either:
-  - A command sequence that is valid when executed using the shell, if `args` is not specified.
-  - A path to an executable or the file name of an executable in `$PATH`, if `args` is a list with zero or more elements.
-- MAY specify an `args` list to be passed directly to the specified executable.
-- MAY specify a `direct` boolean that bypasses the shell.
+- MUST specify a `command` list such that:
+  - The first element of `command` is a path to an executable or the file name of an executable in `$PATH`.
+  - Any remaining elements of `command` are arguments that are always passed directly to the executable.
+- MAY specify an `args` list to be passed directly to the specified executable, after arguments specified in `command`.
+  - The `args` list is a default list of arguments that may be overridden by the user.
 - MAY specify a `default` boolean that indicates that the process type should be selected as the [buildpack-provided default](https://github.com/buildpacks/spec/blob/main/platform.md#outputs-4) during the export phase.
 - MAY specify a `working-dir` for the process. The `working-dir` defaults to the application directory if not specified.
 

From 31d63c95d878da575b257ad5130c692ac22226e0 Mon Sep 17 00:00:00 2001
From: Mikey Boldt <mboldt@vmware.com>
Date: Mon, 18 Apr 2022 16:04:37 -0500
Subject: [PATCH 17/31] Fix grammar

Signed-off-by: Mikey Boldt <mboldt@vmware.com>
---
 buildpack.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/buildpack.md b/buildpack.md
index 86f407a4..48d8a089 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -725,7 +725,7 @@ The following additional environment variables MUST NOT be overridden by the lif
 |-----------------|------------------------------------------------|--------|-------|--------
 | `CNB_STACK_ID`  | Chosen stack ID                                | [x]    | [x]   |
 | `BP_*`          | User-provided variable for buildpack           | [x]    | [x]   |
-| `BPL_*`         | User-provided variable for or exec.d           |        |       | [x]
+| `BPL_*`         | User-provided variable for exec.d              |        |       | [x]
 | `HOME`          | Current user's home directory                  | [x]    | [x]   | [x]
 
 During the detection and build phases, the lifecycle MUST provide any user-provided environment variables as files in `<platform>/env/` with file names and contents matching the environment variable names and contents.

From 67a95b1ca6e3232a35848932ab4ad43c8eaf6612 Mon Sep 17 00:00:00 2001
From: Mikey Boldt <mboldt@vmware.com>
Date: Fri, 3 Jun 2022 16:23:31 -0500
Subject: [PATCH 18/31] Add process definition section and table

Signed-off-by: Mikey Boldt <mboldt@vmware.com>
---
 buildpack.md | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/buildpack.md b/buildpack.md
index 48d8a089..1b9c6214 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -195,6 +195,21 @@ Executable: `<layers>/<layer>/exec.d/<process>/<executable>`, Working Dir: `<app
 | Standard error     | Logs (warnings, errors)
 | [†](README.md#linux-only)FD 3 or [‡](README.md#windows-only)`<handle>` | Launch time environment variables (see [Exec.d Output](#execd-output-toml))
 
+### Process Definition
+
+In the [launch.toml](#launchtoml-toml) file, buildpacks define processes that the launcher can run on the app image.
+
+| Field         | Type            | Definition                                                                                   |
+|---------------|-----------------|----------------------------------------------------------------------------------------------|
+| `type`        | String          | An identifier for this process type                                                          |
+| `command`     | Array of string | The command to execute, followed by arguments that should always be provided [^command-args] |
+| `args`        | Array of string | Default arguments to the command that can be overridden by the user                          |
+| `default`     | Boolean         | If `true`, use this as the default process for the app image                                 |
+| `working-dir` | Path            | Working directory for this process in the app image                                          |
+
+[^command-args]: For versions of the Platform API that use a string for the `command` in process definitions in `metadata.toml`, the arguments from `command` move to `args` and the default `args` are ignored.
+In general, check the [Platform Interface Specification](platform.md) for details on process execution.
+
 ### Layer Types
 
 Using the [Layer Content Metadata](#layer-content-metadata-toml) provided by a buildpack in the `[types]` table of a `<layers>/<layer>.toml` file, the lifecycle MUST determine:
@@ -686,7 +701,7 @@ The purpose of launch is to modify the running app environment using app-provide
       2. Secondly, in alphabetically ascending order by layer directory name.
       3. Thirdly, in alphabetically ascending order by file name.
 
-1. The lifecycle MUST use the `execve` syscall to invoke the command with its arguments, environment, and working directory following the process outlined in the [Platform Interface Specification](platform.md).
+1. The lifecycle MUST invoke the command with its arguments, environment, and working directory following the process outlined in the [Platform Interface Specification](platform.md).
 
 [†](README.md#linux-only)When executing a process, the lifecycle SHOULD replace the lifecycle process in memory without forking it.
 

From e64c2620c21f770cb7454946bf66c3ca218bd3fb Mon Sep 17 00:00:00 2001
From: Mikey Boldt <mike.boldt@gmail.com>
Date: Thu, 9 Jun 2022 13:42:42 -0500
Subject: [PATCH 19/31] Update buildpack.md

Co-authored-by: Natalie Arellano <narellano@vmware.com>
Signed-off-by: Mikey Boldt <mboldt@vmware.com>
---
 buildpack.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/buildpack.md b/buildpack.md
index 1b9c6214..4a14724c 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -197,7 +197,7 @@ Executable: `<layers>/<layer>/exec.d/<process>/<executable>`, Working Dir: `<app
 
 ### Process Definition
 
-In the [launch.toml](#launchtoml-toml) file, buildpacks define processes that the launcher can run on the app image.
+Each buildpack may write a [launch.toml](#launchtoml-toml) file in order to define processes that the launcher can run on the app image.
 
 | Field         | Type            | Definition                                                                                   |
 |---------------|-----------------|----------------------------------------------------------------------------------------------|

From 6a746a0da93afe4d32737333909289d7a2f6c59d Mon Sep 17 00:00:00 2001
From: Mikey Boldt <mike.boldt@gmail.com>
Date: Thu, 9 Jun 2022 13:42:57 -0500
Subject: [PATCH 20/31] Update buildpack.md

Co-authored-by: Natalie Arellano <narellano@vmware.com>
Signed-off-by: Mikey Boldt <mboldt@vmware.com>
---
 buildpack.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/buildpack.md b/buildpack.md
index 4a14724c..92f73f81 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -201,7 +201,7 @@ Each buildpack may write a [launch.toml](#launchtoml-toml) file in order to defi
 
 | Field         | Type            | Definition                                                                                   |
 |---------------|-----------------|----------------------------------------------------------------------------------------------|
-| `type`        | String          | An identifier for this process type                                                          |
+| `type`        | String          | An identifier for the process                                                          |
 | `command`     | Array of string | The command to execute, followed by arguments that should always be provided [^command-args] |
 | `args`        | Array of string | Default arguments to the command that can be overridden by the user                          |
 | `default`     | Boolean         | If `true`, use this as the default process for the app image                                 |

From 4d57c56354790c5ddcedbfa619a7cc7dd595cfde Mon Sep 17 00:00:00 2001
From: Mikey Boldt <mike.boldt@gmail.com>
Date: Thu, 9 Jun 2022 13:57:16 -0500
Subject: [PATCH 21/31] Update buildpack.md

Co-authored-by: Natalie Arellano <narellano@vmware.com>
Signed-off-by: Mikey Boldt <mboldt@vmware.com>
---
 buildpack.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/buildpack.md b/buildpack.md
index 92f73f81..deedd750 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -207,7 +207,7 @@ Each buildpack may write a [launch.toml](#launchtoml-toml) file in order to defi
 | `default`     | Boolean         | If `true`, use this as the default process for the app image                                 |
 | `working-dir` | Path            | Working directory for this process in the app image                                          |
 
-[^command-args]: For versions of the Platform API that use a string for the `command` in process definitions in `metadata.toml`, the arguments from `command` move to `args` and the default `args` are ignored.
+[^command-args]: For versions of the Platform API that do not support overridable arguments, `args` are always applied.
 In general, check the [Platform Interface Specification](platform.md) for details on process execution.
 
 ### Layer Types

From 46244c32f2623fc7b33b6c46c3e55445e22c24a1 Mon Sep 17 00:00:00 2001
From: Mikey Boldt <mboldt@vmware.com>
Date: Thu, 9 Jun 2022 14:11:12 -0500
Subject: [PATCH 22/31] Add pointer to Platform spec for launch details

Signed-off-by: Mikey Boldt <mboldt@vmware.com>
---
 buildpack.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/buildpack.md b/buildpack.md
index deedd750..995ad808 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -889,6 +889,8 @@ For each process, the buildpack:
 - MAY specify a `default` boolean that indicates that the process type should be selected as the [buildpack-provided default](https://github.com/buildpacks/spec/blob/main/platform.md#outputs-4) during the export phase.
 - MAY specify a `working-dir` for the process. The `working-dir` defaults to the application directory if not specified.
 
+Note that the [Platform Interface Specification](platform.md) is ultimately responsible for launching processes; consult that specification for details.
+
 An individual buildpack may only specify one process type with `default = true`. The lifecycle MUST select, from all buildpack-provided process types, the last process type with `default = true` as the buildpack-provided default. If multiple buildpacks define processes of the same type, the lifecycle MUST use the last process type definition ordered by buildpack execution for the combined process list (a non-default process type definition may override a default process type definition, leaving the app image with no default).
 
 For each slice, buildpacks MUST specify zero or more path globs such that each path is either:

From 7d23c690755d524c84ebea7aa989d4b1b1d7ea60 Mon Sep 17 00:00:00 2001
From: Mikey Boldt <mboldt@vmware.com>
Date: Fri, 8 Jul 2022 10:36:08 -0500
Subject: [PATCH 23/31] Move launcher execution details to platform spec.

Signed-off-by: Mikey Boldt <mboldt@vmware.com>
---
 buildpack.md | 10 ++--------
 platform.md  | 38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+), 8 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index 995ad808..f563c6bd 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -692,14 +692,8 @@ The purpose of launch is to modify the running app environment using app-provide
 1. The lifecycle MUST set all buildpack-provided launch environment variables as described in the [Environment](#environment) section.
 
 1. The lifecycle MUST
-   1. [execute](#execd) each file in each `<layers>/<layer>/exec.d` directory in the launch environment, with working directory `<app>`, and set the [returned variables](#execd-output-toml) in the launch environment before continuing,
-      1. Firstly, in order of `/bin/build` execution used to construct the OCI image.
-      2. Secondly, in alphabetically ascending order by layer directory name.
-      3. Thirdly, in alphabetically ascending order by file name.
-   2. [execute](#execd) each file in each `<layers>/<layer>/exec.d/<process>` directory in the launch environment, with working directory `<app>`, and set the [returned variables](#execd-output-toml) in the launch environment before continuing,
-      1. Firstly, in order of `/bin/build` execution used to construct the OCI image.
-      2. Secondly, in alphabetically ascending order by layer directory name.
-      3. Thirdly, in alphabetically ascending order by file name.
+   1. [execute](#execd) each file in each `<layers>/<layer>/exec.d` as described in the [Platform Interface Specification](platform.md).
+   1. [execute](#execd) each file in each `<layers>/<layer>/exec.d/<process>` as described in the [Platform Interface Specification](platform.md).
 
 1. The lifecycle MUST invoke the command with its arguments, environment, and working directory following the process outlined in the [Platform Interface Specification](platform.md).
 
diff --git a/platform.md b/platform.md
index 4cbf40cf..f04c5353 100644
--- a/platform.md
+++ b/platform.md
@@ -754,6 +754,7 @@ Usage:
 A command (`<cmd>`), arguments to that command (`<args>`), a working directory (`<working-dir>`), and an execution strategy (`<direct>`) comprise a process definition. Processes MAY be buildpack-defined or user-defined.
 
 The launcher:
+
 - MUST derive the values of `<cmd>`, `<args>`, `<working-dir>`, and `<direct>` as follows:
 - **If** the final path element in `$0`, matches the type of any buildpack-provided process type
     - `<process-type>` SHALL be the final path element in `$0`
@@ -773,6 +774,43 @@ The launcher:
         - `<args>` SHALL be `${@2:}`
         - `<working-dir` SHALL be `<app>`
 
+##### Execution
+
+Given the start command and execution strategy,
+
+1. The launcher MUST set all buildpack-provided launch environment variables as described in the [Environment](#environment) section.
+
+1. The launcher MUST
+   1. [execute](#execd) each file in each `<layers>/<layer>/exec.d` directory in the launch environment, with working directory `<app>`, and set the [returned variables](#execd-output-toml) in the launch environment before continuing,
+      1. Firstly, in order of `/bin/build` execution used to construct the OCI image.
+      2. Secondly, in alphabetically ascending order by layer directory name.
+      3. Thirdly, in alphabetically ascending order by file name.
+   2. [execute](#execd) each file in each `<layers>/<layer>/exec.d/<process>` directory in the launch environment, with working directory `<app>`, and set the [returned variables](#execd-output-toml) in the launch environment before continuing,
+      1. Firstly, in order of `/bin/build` execution used to construct the OCI image.
+      2. Secondly, in alphabetically ascending order by layer directory name.
+      3. Thirdly, in alphabetically ascending order by file name.
+
+1. If using an execution strategy involving a shell, the launcher MUST use a single shell process, with working directory `<app>`, to
+   1. source each file in each `<layers>/<layer>/profile.d` directory,
+      1. Firstly, in order of `/bin/build` execution used to construct the OCI image.
+      2. Secondly, in alphabetically ascending order by layer directory name.
+      3. Thirdly, in alphabetically ascending order by file name.
+   2. source each file in each `<layers>/<layer>/profile.d/<process>` directory,
+      1. Firstly, in order of `/bin/build` execution used to construct the OCI image.
+      2. Secondly, in alphabetically ascending order by layer directory name.
+      3. Thirdly, in alphabetically ascending order by file name.
+   3. source [†](README.md#linux-only)`<app>/.profile` or [‡](README.md#windows-only)`<app>/.profile.bat` if it is present.
+
+1. The launcher MUST set the working directory for the start command to `<working-dir>`, or to `<app>` if `<working-dir>` is not specified.
+
+1. The launcher MUST invoke the start command with the decided execution strategy.
+
+[†](README.md#linux-only)When executing a process using any execution strategy, the launcher SHOULD replace the launcher process in memory without forking it.
+
+[†](README.md#linux-only)When executing a process with Bash, the launcher SHOULD additionally replace the Bash process in memory without forking it.
+
+[‡](README.md#windows-only)When executing a process with Command Prompt, the launcher SHOULD start a new process with the same security context, terminal, working directory, STDIN/STDOUT/STDERR handles and environment variables as the Command Prompt process.
+
 ##### Outputs
 If the launcher errors before executing the process it will have one of the following error codes:
 

From 32a191ae0039e137e0ce8b4096032bce243142bf Mon Sep 17 00:00:00 2001
From: Mikey Boldt <mboldt@vmware.com>
Date: Fri, 15 Jul 2022 14:24:17 -0500
Subject: [PATCH 24/31] Consolidate process definition details in launch.toml
 description

Signed-off-by: Mikey Boldt <mboldt@vmware.com>
---
 buildpack.md | 24 +++++-------------------
 1 file changed, 5 insertions(+), 19 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index f563c6bd..ed1d1f20 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -195,21 +195,6 @@ Executable: `<layers>/<layer>/exec.d/<process>/<executable>`, Working Dir: `<app
 | Standard error     | Logs (warnings, errors)
 | [†](README.md#linux-only)FD 3 or [‡](README.md#windows-only)`<handle>` | Launch time environment variables (see [Exec.d Output](#execd-output-toml))
 
-### Process Definition
-
-Each buildpack may write a [launch.toml](#launchtoml-toml) file in order to define processes that the launcher can run on the app image.
-
-| Field         | Type            | Definition                                                                                   |
-|---------------|-----------------|----------------------------------------------------------------------------------------------|
-| `type`        | String          | An identifier for the process                                                          |
-| `command`     | Array of string | The command to execute, followed by arguments that should always be provided [^command-args] |
-| `args`        | Array of string | Default arguments to the command that can be overridden by the user                          |
-| `default`     | Boolean         | If `true`, use this as the default process for the app image                                 |
-| `working-dir` | Path            | Working directory for this process in the app image                                          |
-
-[^command-args]: For versions of the Platform API that do not support overridable arguments, `args` are always applied.
-In general, check the [Platform Interface Specification](platform.md) for details on process execution.
-
 ### Layer Types
 
 Using the [Layer Content Metadata](#layer-content-metadata-toml) provided by a buildpack in the `[types]` table of a `<layers>/<layer>.toml` file, the lifecycle MUST determine:
@@ -872,18 +857,19 @@ If multiple buildpacks define labels with the same key, the lifecycle MUST use t
 
 For each process, the buildpack:
 
-- MUST specify a `type`, which:
+- MUST specify a `type`, an identifier for the process, which:
   - MUST NOT be identical to other process types provided by the same buildpack.
   - MUST only contain numbers, letters, and the characters ., _, and -.
 - MUST specify a `command` list such that:
   - The first element of `command` is a path to an executable or the file name of an executable in `$PATH`.
-  - Any remaining elements of `command` are arguments that are always passed directly to the executable.
+  - Any remaining elements of `command` are arguments that should always passed directly to the executable [^command-args].
 - MAY specify an `args` list to be passed directly to the specified executable, after arguments specified in `command`.
-  - The `args` list is a default list of arguments that may be overridden by the user.
+  - The `args` list is a default list of arguments that may be overridden by the user [^command-args].
 - MAY specify a `default` boolean that indicates that the process type should be selected as the [buildpack-provided default](https://github.com/buildpacks/spec/blob/main/platform.md#outputs-4) during the export phase.
 - MAY specify a `working-dir` for the process. The `working-dir` defaults to the application directory if not specified.
 
-Note that the [Platform Interface Specification](platform.md) is ultimately responsible for launching processes; consult that specification for details.
+[^command-args]: For versions of the Platform API that do not support overridable arguments, the arguments in `command` and `args` are always applied.
+In general, the [Platform Interface Specification](platform.md) is ultimately responsible for launching processes; consult that specification for details.
 
 An individual buildpack may only specify one process type with `default = true`. The lifecycle MUST select, from all buildpack-provided process types, the last process type with `default = true` as the buildpack-provided default. If multiple buildpacks define processes of the same type, the lifecycle MUST use the last process type definition ordered by buildpack execution for the combined process list (a non-default process type definition may override a default process type definition, leaving the app image with no default).
 

From 322221a83afcc0a9f018f770619c0f2e56c1d241 Mon Sep 17 00:00:00 2001
From: Mikey Boldt <mike.boldt@gmail.com>
Date: Fri, 15 Jul 2022 15:48:37 -0500
Subject: [PATCH 25/31] Apply suggestions from code review

Co-authored-by: Natalie Arellano <narellano@vmware.com>
Signed-off-by: Mikey Boldt <mboldt@vmware.com>
---
 buildpack.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index ed1d1f20..48b47705 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -862,13 +862,13 @@ For each process, the buildpack:
   - MUST only contain numbers, letters, and the characters ., _, and -.
 - MUST specify a `command` list such that:
   - The first element of `command` is a path to an executable or the file name of an executable in `$PATH`.
-  - Any remaining elements of `command` are arguments that should always passed directly to the executable [^command-args].
+  - Any remaining elements of `command` are arguments that are always passed directly to the executable [^command-args].
 - MAY specify an `args` list to be passed directly to the specified executable, after arguments specified in `command`.
   - The `args` list is a default list of arguments that may be overridden by the user [^command-args].
 - MAY specify a `default` boolean that indicates that the process type should be selected as the [buildpack-provided default](https://github.com/buildpacks/spec/blob/main/platform.md#outputs-4) during the export phase.
 - MAY specify a `working-dir` for the process. The `working-dir` defaults to the application directory if not specified.
 
-[^command-args]: For versions of the Platform API that do not support overridable arguments, the arguments in `command` and `args` are always applied.
+[^command-args]: For versions of the Platform API that do not support overridable arguments, the arguments in `command` and `args` are always applied together with any user-provided arguments.
 In general, the [Platform Interface Specification](platform.md) is ultimately responsible for launching processes; consult that specification for details.
 
 An individual buildpack may only specify one process type with `default = true`. The lifecycle MUST select, from all buildpack-provided process types, the last process type with `default = true` as the buildpack-provided default. If multiple buildpacks define processes of the same type, the lifecycle MUST use the last process type definition ordered by buildpack execution for the combined process list (a non-default process type definition may override a default process type definition, leaving the app image with no default).

From 297b8e00674aec060ac0e6b1d7c1a991a93f5436 Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Wed, 24 Aug 2022 15:17:30 -0400
Subject: [PATCH 26/31] Buildpack changes to support "phase 2" (build image
 extension) of Dockerfiles

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 buildpack.md       | 31 ++++++++++++++++----------
 image_extension.md | 55 +++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 72 insertions(+), 14 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index e7be4d90..ad14c512 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -8,6 +8,8 @@ This document specifies the interface between a lifecycle program and one or mor
 - [Buildpack Interface Specification](#buildpack-interface-specification)
   - [Table of Contents](#table-of-contents)
   - [Buildpack API Version](#buildpack-api-version)
+  - [Terminology](#terminology)
+    - [CNB Terminology](#cnb-terminology)
   - [Buildpack Interface](#buildpack-interface)
     - [Buildpack API Compatibility](#buildpack-api-compatibility)
     - [Key](#key)
@@ -19,7 +21,6 @@ This document specifies the interface between a lifecycle program and one or mor
       - [Build Layers](#build-layers)
       - [Cached Layers](#cached-layers)
       - [Ignored Layers](#ignored-layers)
-  - [App Interface](#app-interface)
   - [Phase #1: Detection](#phase-1-detection)
     - [Purpose](#purpose)
     - [Process](#process)
@@ -28,11 +29,13 @@ This document specifies the interface between a lifecycle program and one or mor
   - [Phase #2: Analysis](#phase-2-analysis)
     - [Purpose](#purpose-1)
     - [Process](#process-1)
-  - [Phase #3: Generation (optional)](#phase-3-generation-optional)
+  - [Phase #3: Generation (image extensions only)](#phase-3-generation-image-extensions-only)
     - [Purpose](#purpose-2)
     - [Process](#process-2)
-  - [Phase #4: Build](#phase-4-build)
+  - [Phase #4: Extension (image extensions only)](#phase-4-extension-image-extensions-only)
     - [Purpose](#purpose-3)
+  - [Phase #5: Build (component buildpacks only)](#phase-5-build-component-buildpacks-only)
+    - [Purpose](#purpose-4)
     - [Process](#process-3)
       - [Unmet Buildpack Plan Entries](#unmet-buildpack-plan-entries)
       - [Software-Bill-of-Materials](#software-bill-of-materials)
@@ -40,11 +43,11 @@ This document specifies the interface between a lifecycle program and one or mor
         - [Providing Layers](#providing-layers)
         - [Reusing Layers](#reusing-layers)
         - [Slice Layers](#slice-layers)
-  - [Phase #5: Export](#phase-5-export)
-    - [Purpose](#purpose-4)
+  - [Phase #6: Export](#phase-6-export)
+    - [Purpose](#purpose-5)
     - [Process](#process-4)
   - [Launch](#launch)
-    - [Purpose](#purpose-5)
+    - [Purpose](#purpose-6)
     - [Process](#process-5)
   - [Environment](#environment)
     - [Provided by the Lifecycle](#provided-by-the-lifecycle)
@@ -506,13 +509,19 @@ After analysis, the lifecycle MUST proceed to the build phase.
 
 ### Purpose
 
-The purpose of the generation phase is to generate Dockerfiles that can be used to define the runtime base image.
+The purpose of the generation phase is to generate Dockerfiles that can be used to define the build and/or runtime base image.
 
 ### Process
 
 See the [Image Extension Specification](#image-extension.md).
 
-## Phase #4: Build (component buildpacks only)
+## Phase #4: Extension (image extensions only)
+
+### Purpose
+
+The purpose of the extension phase is to apply the Dockerfiles generated in the generation phase to the appropriate base image. The extension phase MUST NOT be run for Windows builds.
+
+## Phase #5: Build (component buildpacks only)
 
 ![Build](img/build.svg)
 
@@ -664,7 +673,7 @@ Additionally, a buildpack MAY specify sub-paths within `<app>` as `slices` in `l
 Separate layers MUST be created during the export phase for each slice with one or more files or directories.
 This minimizes data transfer when the app directory contains a known set of files.
 
-## Phase #5: Export
+## Phase #6: Export
 
 ![Export](img/export.svg)
 
@@ -884,7 +893,7 @@ Prohibited:
 
 ### Requirements
 
-The lifecycle MUST be implemented so that the detection, generation, and build phases do not have access to OCI image store credentials used in the analysis and export phases.
+The lifecycle MUST be implemented so that the detection, generation, extension, and build phases do not have access to OCI image store credentials used in the analysis and export phases.
 The lifecycle SHOULD be implemented so that each phase may run in a different container.
 
 ## Data Format
@@ -1064,7 +1073,7 @@ Buildpack authors MUST choose a globally unique ID, for example: "io.buildpacks.
 
 *Key: `id = "<buildpack ID>"`*
 - MUST only contain numbers, letters, and the characters `.`, `/`, and `-`.
-- MUST NOT be `config`, `app`, or `sbom`.
+- MUST NOT be `app`, `config`, `generated`, or `sbom`.
 - MUST NOT be identical to any other buildpack ID when using a case-insensitive comparison.
 
 **The buildpack version:**
diff --git a/image_extension.md b/image_extension.md
index 0b83d6d5..f49ea6ea 100644
--- a/image_extension.md
+++ b/image_extension.md
@@ -49,7 +49,7 @@ Image extensions participate in a generation process that is similar to the buil
 
 ### Purpose
 
-The purpose of the generation phase is to generate Dockerfiles that can be used to define the runtime base image.
+The purpose of the generation phase is to generate Dockerfiles that can be used to define the build and/or runtime base image.
 
 ### Process
 
@@ -86,16 +86,51 @@ Correspondingly, each `/bin/generate` executable:
 - MAY read the Buildpack Plan.
 - MAY log output from the build process to `stdout`.
 - MAY emit error, warning, or debug messages to `stderr`.
-- MAY write a run.Dockerfile to the `<output>` directory. This file MUST adhere to the requirements listed below.
+- MAY write either or both of `build.Dockerfile` and `run.Dockerfile` to the `<output>` directory. This file MUST adhere to the requirements listed below.
+- MAY write key-value pairs to `<output>/extend-config.toml` that are provided as build args to build.Dockerfile when extending the build image.
 - MUST NOT write SBOM (Software-Bill-of-Materials) files as described in the [Software-Bill-of-Materials](#software-bill-of-materials) section.
 
 #### Dockerfile Requirements
 
-run.Dockerfiles:
+A `run.Dockerfile`
 
 - MAY contain a single `FROM` instruction
 - MUST NOT contain any other instructions
 
+A `build.Dockerfile`
+
+- MUST begin with:
+```bash
+ARG base_image
+FROM ${base_image}
+```
+- MUST NOT contain any other `FROM` instructions
+- MAY contain `ADD`, `ARG`, `COPY`, `ENV`, `LABEL`, `RUN`, `SHELL`, `USER`, and `WORKDIR` instructions
+- MUST NOT contain any other instructions
+- SHOULD use the `build_id` build arg to invalidate the cache after a certain layer. When the `$build_id` build arg is referenced in a `RUN` instruction, all subsequent layers will be rebuilt on the next build (as the value will change)
+- SHOULD NOT edit `<app>`, `<layers>`, or `<workspace>` directories (see the [Platform Interface Specification](platform.md)) as changes will not be persisted
+
+## Phase: Extension
+
+### Purpose
+
+The purpose of the extension phase is to apply the Dockerfiles generated in the generation phase to the appropriate base image. The extension phase MUST NOT be run for Windows builds.
+
+### Process
+
+**GIVEN:**
+- The final ordered group of Dockerfiles generated during the generation phase,
+- A list of build args for each Dockerfile specified during the generation phase,
+
+For each Dockerfile in the group in order, the lifecycle MUST apply the Dockerfile to the base image as follows:
+
+- The lifecycle MUST provide each Dockerfile with:
+- A `base_image` build arg
+    - For the first Dockerfile, the value MUST be the original base image.
+    - When there are multiple Dockerfiles, the value MUST be the intermediate image generated from the application of the previous Dockerfile.
+- A `build_id` build arg
+    - The value MUST be a UUID
+
 ## Data Format
 
 ### Files
@@ -124,6 +159,20 @@ Image extension authors MUST choose a globally unique ID, for example: "io.build
 
 The image extension `id`, `version`, `api`, and `licenses` entries MUST follow the requirements defined in the [Buildpack Interface Specification](buildpack.md).
 
+### extend-config.toml (TOML)
+
+```toml
+[[build.args]]
+name = "<build arg name>"
+value = "<build arg value>"
+```
+
+The image extension MAY specify any number of args.
+
+For each arg, the image extension:
+- MUST specify a `name` to be the name of a build argument that will be provided to any output build.Dockerfile when extending the build base image.
+- MUST specify a `value` to be the value of the build argument that is provided.
+
 ### Build Plan (TOML)
 
 See the [Buildpack Interface Specification](buildpack.md).

From e6c4e936d2199642cb18b60cd7b9db90d9622c11 Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Wed, 14 Sep 2022 13:18:05 -0400
Subject: [PATCH 27/31] Extensions should receive `CNB_EXTENSION_DIR`

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 image_extension.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/image_extension.md b/image_extension.md
index f49ea6ea..59c2036f 100644
--- a/image_extension.md
+++ b/image_extension.md
@@ -43,6 +43,7 @@ Executable: `/bin/generate`, Working Dir: `<app[AR]>`
 Image extensions participate in a generation process that is similar to the buildpack [build](buildpack.md#build) process, with an interface that is similar to `/bin/build`. However:
 - Image extensions' `/bin/generate` MUST NOT write to the app directory.
 - Instead of the `CNB_LAYERS_DIR` input, image extensions MUST receive a `CNB_OUTPUT_DIR` which MUST be the absolute path of an `<output>` directory and MUST NOT be the path of the buildpack layers directory.
+- Instead of the `CNB_BUILDPACK_DIR` input, image extensions MUST receive a `CNB_EXTENSION_DIR` which MUST be the absolute path of the extension root directory.
 - If an image extension is missing `/bin/generate`, the image extension root `/generate` directory MUST be treated as a pre-populated `<output>` directory.
 
 ## Phase: Generation

From 8b5dea8b0f4815fabe7995ecddb2d18175cb8100 Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Thu, 22 Sep 2022 16:04:14 -0400
Subject: [PATCH 28/31] MUST -> SHOULD

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 image_extension.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/image_extension.md b/image_extension.md
index 59c2036f..9e3c23d6 100644
--- a/image_extension.md
+++ b/image_extension.md
@@ -34,6 +34,7 @@ Executable: `/bin/detect`, Working Dir: `<app[AR]>`
 Image extensions participate in the buildpack [detection](buildpack.md#detection) process, with the same interface for `/bin/detect`. However:
 - Detection is optional for image extensions, and they are assumed to pass detection when `/bin/detect` is not present.
 - If an image extension is missing `/bin/detect`, the image extension root `/detect` directory MUST be treated as a pre-populated `<output>` directory.
+- Instead of the `CNB_BUILDPACK_DIR` input, image extensions MUST receive a `CNB_EXTENSION_DIR` which MUST be the absolute path of the extension root directory.
 - Image extensions MUST only output `provides` entries to the build plan. They MUST NOT output `requires`.
 
 ### Generation
@@ -107,7 +108,7 @@ FROM ${base_image}
 ```
 - MUST NOT contain any other `FROM` instructions
 - MAY contain `ADD`, `ARG`, `COPY`, `ENV`, `LABEL`, `RUN`, `SHELL`, `USER`, and `WORKDIR` instructions
-- MUST NOT contain any other instructions
+- SHOULD NOT contain any other instructions
 - SHOULD use the `build_id` build arg to invalidate the cache after a certain layer. When the `$build_id` build arg is referenced in a `RUN` instruction, all subsequent layers will be rebuilt on the next build (as the value will change)
 - SHOULD NOT edit `<app>`, `<layers>`, or `<workspace>` directories (see the [Platform Interface Specification](platform.md)) as changes will not be persisted
 

From a9d2f4079c8abd693c3d912e5cf4b83ff6a28117 Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Thu, 22 Sep 2022 16:51:33 -0400
Subject: [PATCH 29/31] Extensions for Windows are not supported

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 buildpack.md       | 2 +-
 image_extension.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/buildpack.md b/buildpack.md
index ad14c512..9f66c409 100644
--- a/buildpack.md
+++ b/buildpack.md
@@ -509,7 +509,7 @@ After analysis, the lifecycle MUST proceed to the build phase.
 
 ### Purpose
 
-The purpose of the generation phase is to generate Dockerfiles that can be used to define the build and/or runtime base image.
+The purpose of the generation phase is to generate Dockerfiles that can be used to define the build and/or runtime base image. The generation phase MUST NOT be run for Windows builds.
 
 ### Process
 
diff --git a/image_extension.md b/image_extension.md
index 9e3c23d6..2859f87f 100644
--- a/image_extension.md
+++ b/image_extension.md
@@ -51,7 +51,7 @@ Image extensions participate in a generation process that is similar to the buil
 
 ### Purpose
 
-The purpose of the generation phase is to generate Dockerfiles that can be used to define the build and/or runtime base image.
+The purpose of the generation phase is to generate Dockerfiles that can be used to define the build and/or runtime base image. The generation phase MUST NOT be run for Windows builds.
 
 ### Process
 

From 7ff35405718cc4cfa028ee84571973249f218935 Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Mon, 31 Oct 2022 12:16:22 -0400
Subject: [PATCH 30/31] Update image_extension.md

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 image_extension.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/image_extension.md b/image_extension.md
index 2859f87f..8b69a36d 100644
--- a/image_extension.md
+++ b/image_extension.md
@@ -109,7 +109,7 @@ FROM ${base_image}
 - MUST NOT contain any other `FROM` instructions
 - MAY contain `ADD`, `ARG`, `COPY`, `ENV`, `LABEL`, `RUN`, `SHELL`, `USER`, and `WORKDIR` instructions
 - SHOULD NOT contain any other instructions
-- SHOULD use the `build_id` build arg to invalidate the cache after a certain layer. When the `$build_id` build arg is referenced in a `RUN` instruction, all subsequent layers will be rebuilt on the next build (as the value will change)
+- SHOULD use the `build_id` build arg to invalidate the cache after a certain layer. When the `$build_id` build arg is referenced in a `RUN` instruction, all subsequent layers will be rebuilt on the next build (as the value will change); the `build_id` build arg SHOULD be defaulted to 0 if used (this ensures portability)
 - SHOULD NOT edit `<app>`, `<layers>`, or `<workspace>` directories (see the [Platform Interface Specification](platform.md)) as changes will not be persisted
 
 ## Phase: Extension

From a841d939580ad26cd71a131eef6f424022b62ead Mon Sep 17 00:00:00 2001
From: Natalie Arellano <narellano@vmware.com>
Date: Mon, 31 Oct 2022 12:17:21 -0400
Subject: [PATCH 31/31] Update buildpack api version in README

Signed-off-by: Natalie Arellano <narellano@vmware.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 025ab99e..2a569eb6 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,6 @@ When the specification refers to a path in the context of an OCI layer tar (e.g.
 
 These documents currently specify:
 
-- Buildpack API: `0.8`
+- Buildpack API: `0.9`
 - Distribution API: `0.3`
 - Platform API: `0.9`