Clean up app-dev concepts

Signed-off-by: Natalie Arellano <[email protected]>

Author: Natalie Arellano

content/docs/_index.md

@@ -17,7 +17,7 @@ summary="Get started with Cloud Native Buildpacks."
 
 ## Going deeper
 
-See how-to guides, concepts, and advanced tutorials tailored to specific personas:
+See how-to guides, concepts, and tutorials tailored to specific personas:
 
 *  [App Developers](/docs/for-app-developers/)
 *  [Buildpack Authors](/docs/for-buildpack-authors/)

content/docs/for-app-developers/concepts/_index.md

@@ -1,6 +1,5 @@
 +++
 title="Concepts"
 weight=2
-expand=false
 include_summaries=true
 +++

content/docs/for-app-developers/concepts/base-images/_index.md

@@ -0,0 +1,5 @@
++++
+title="What are base images?"
+weight=5
+include_summaries=true
++++

content/docs/for-app-developers/concepts/base-images/build.md

@@ -3,7 +3,8 @@ title="Build image"
 weight=1
 +++
 
-## What is a build image?
-
 The **build image** provides the base image from which the build environment is constructed.
+
+<!--more-->
+
 The build environment is the containerized environment in which the [lifecycle][lifecycle] (and thereby [buildpacks][buildpack]) are executed.

content/docs/for-app-developers/concepts/base-images/run.md

@@ -3,9 +3,10 @@ title="Run image"
 weight=2
 +++
 
-## What is a run image?
-
 The **run image** provides the base image for application images.
+
+<!--more-->
+
 The lifecycle requires a reference to a run image and (where necessary) possible run image mirrors in order to construct the application image.
 
 ### Run image mirrors

content/docs/for-app-developers/concepts/base-images/stack.md

@@ -1,15 +1,15 @@
 +++
 title="Stack"
-weight=4
+weight=99
 aliases=[
     "/docs/using-pack/stacks/"
 ]
 +++
 
-## What is a stack?
-
 A stack (deprecated) is the grouping together of the build and run base images, represented by a unique ID.
 
+<!--more-->
+
 As of Platform API 0.12 and Buildpack API 0.10, stacks are deprecated in favor of existing constructs in the container image ecosystem such as operating system name, operating system distribution, and architecture.
 
 For more information, see

content/docs/for-app-developers/concepts/build.md

@@ -0,0 +1,27 @@
++++
+title="What happens during build?"
+weight=3
++++
+
+`Build` is the process of executing one or more [buildpacks][buildpack] against an application's source code to produce a runnable OCI image.
+
+<!--more-->
+
+## Building explained
+
+![build diagram](/docs/for-app-developers/concepts/build.svg)
+
+Each [buildpack] inspects the source code and provides relevant dependencies.
+An image is then generated from the app's source code and these dependencies.
+
+During the build process, the [build-time base image] becomes the environment in which buildpacks are executed,
+and the [runtime base image] becomes the base for the final app image.
+
+[Buildpacks][buildpack] can be bundled together with a specific [build-time base image], resulting in a [builder] image.
+Builders provide a convenient way to distribute buildpacks.
+
+[build-time base image]: /docs/for-app-developers/concepts/base-images/build/
+[builder]: /docs/for-platform-operators/concepts/builder
+[buildpack]: /docs/for-app-developers/concepts/buildpack/
+[lifecycle]: /docs/for-platform-operators/concepts/lifecycle/
+[runtime base image]: /docs/for-app-developers/concepts/base-images/run/

content/docs/for-app-developers/concepts/buildpacks-operations/build.svg renamed to content/docs/for-app-developers/concepts/build.svg

@@ -0,0 +1,33 @@
++++
+title="What is a builder?"
+weight=2
++++
+
+A `builder` is an OCI image containing
+an ordered combination of [buildpacks][buildpack] and
+a [build-time base image], a [lifecycle] binary, and a reference to a [runtime base image].
+
+<!--more-->
+
+The [build-time base image] provides the base environment for the `builder`
+(e.g., an Ubuntu Jammy OS image with build tooling) and
+a [runtime base image] provides the base environment for the `app image` during runtime.
+
+![builder](/docs/for-app-developers/concepts/builder.svg)
+
+Under the hood a builder uses the [lifecycle] to run the `detect` phase for all the `buildpacks` it contains, in order,
+and then proceeds to run the `build` phase for all the `buildpacks` that passed detection.
+
+This allows us to have a **single** `builder` that can detect and build various kinds of applications automatically.
+
+For example, let's say `demo-builder` contains the `Python` and `Node` buildpack. Then -
+
+- If your project just has a `requirements.txt`, `demo-builder` will only run the Python `build` steps.
+- If your project just has a `package-lock.json`, `demo-builder` will only run the Node `build` steps.
+- If your project has both `package-lock.json` and `requirements.txt`, `demo-builder` will run **both** the Python and Node `build` steps.
+- If your project has no related files, `demo-builder` will fail to `detect` and exit.
+
+[build-time base image]: /docs/for-app-developers/concepts/base-images/build/
+[buildpack]: /docs/for-app-developers/concepts/buildpack/
+[lifecycle]: /docs/for-platform-operators/concepts/lifecycle/
+[runtime base image]: /docs/for-app-developers/concepts/base-images/run/