Merge 56db7e62ab into 522552f1d0

Signed-off-by: Natalie Arellano <narellano@vmware.com>

content/docs/for-platform-operators/how-to/design-platform/_index.md

@@ -0,0 +1,5 @@
++++
+title="Design your own platform"
+weight=3
+include_summaries=true
++++

content/docs/for-platform-operators/how-to/design-platform/prepare-filesystem.md

@@ -0,0 +1,16 @@
++++
+title="Prepare the filesystem"
+weight=99
++++
+
+This page is a stub! The CNB project is applying to [Google Season of Docs](https://developers.google.com/season-of-docs/docs/timeline) to receive support for improving our documentation. Please check back soon.
+
+If you are familiar with this content and would like to make a contribution, please feel free to open a PR :)
+
+To cover:
+
+* Buildpacks are stored on the filesystem as unarchived files such that:
+  * Each top-level directory is a buildpack ID.
+  * Each second-level directory is a buildpack version.
+* Mount points
+* Users

content/docs/reference/spec/platform-api.md

@@ -5,27 +5,25 @@ aliases=[
 ]
 +++
 
-The Platform specification defines the interface between the CNB [lifecycle](/docs/for-platform-operators/concepts/lifecycle/) and a [platform](/docs/for-app-developers/concepts/platform/) that runs it.
+The Platform API specifies the interface between a [lifecycle] program
+and a [platform] that runs it.
 
 <!--more-->
 
-## Buildpacks
+## API Compatibility
 
-Buildpacks are stored on the filesystem as unarchived files such that:
+A [platform] may implement more than one Platform API version at a time, although it is not required to do so.
+Platforms can control the Platform API version expected by the lifecycle by setting the `CNB_PLATFORM_API` environment variable.
 
-* Each top-level directory is a buildpack ID.
-* Each second-level directory is a buildpack version.
+A [lifecycle] may (and usually does) support more than one Platform API version at a time.
+The supported Platform API version(s) can be found in the `lifecycle.toml` file in a lifecycle tarball,
+or in a label on the [lifecycle image](https://hub.docker.com/r/buildpacksio/lifecycle).
 
-## Users
-
-For security reasons, images built with platforms, such as `pack`, build and run as non-root users.
-
-## Stacks (deprecated)
-
-A stack (deprecated) is the grouping together of the build and run base images, represented by a unique ID.
-
-The build image is used to run the buildpack lifecycle, and the run image is the base image for the application image.
+A lifecycle "supports" a platform (and vice versa) if they both declare support for the same Platform API version in format: `<major>.<minor>`.
 
 ## Further Reading
 
 You can read the complete [Platform API specification on Github](https://github.com/buildpacks/spec/blob/main/platform.md).
+
+[lifecycle]: /docs/for-platform-operators/concepts/lifecycle/
+[platform]: /docs/for-app-developers/concepts/platform/