Update docs content from https://github.com/depot/app

content/cache/authentication.mdx

@@ -18,8 +18,8 @@ Depot Cache supports authenticating with user tokens and organization tokens. Ad
 
 For specific details on how to configure your build tools to authenticate with Depot Cache, refer to the following guides:
 
-- [Bazel](/docs/cache/bazel)
-- [Gradle](/docs/cache/gradle)
-- [Pants](/docs/cache/pants)
-- [sccache](/docs/cache/sccache)
-- [Turborepo](/docs/cache/turbo)
+- [Bazel](/docs/cache/reference/bazel)
+- [Gradle](/docs/cache/reference/gradle)
+- [Pants](/docs/cache/reference/pants)
+- [sccache](/docs/cache/reference/sccache)
+- [Turborepo](/docs/cache/reference/turbo)

content/cli/reference.mdx

@@ -101,7 +101,7 @@ If you want to build a specific target in the bake file, you can specify it in t
 depot bake -f docker-bake.hcl original
 ```
 
-You can also save all of the targets built in a bake or compose file to the [ephemeral registry](/docs/guides/ephemeral-registry) for later use with the `--save` flag:
+You can also save all of the targets built in a bake or compose file to the [ephemeral registry](/docs/container-builds/how-to-guides/ephemeral-registry) for later use with the `--save` flag:
 
 ```shell
 depot bake -f docker-bake.hcl --save

content/guides/arm-containers.mdx → content/container-builds/how-to-guides/arm-containers.mdx

@@ -12,7 +12,7 @@ Depot removes emulation altogether.
 
 Depot is a remote Docker container build service that orchestrates optimized BuildKit builders on native CPUs for Intel (x86) and Arm (arm64).
 
-When a Docker image build is routed to Depot either via [`depot build`](/docs/cli/reference#depot-build) or [`docker build`](/docs/guides/docker-build#how-to-use-depot-with-docker), we launch optimized builders for each architecture requested with a persistent layer cache attached to them. Each builder has 16 CPUs, 32GB of memory, and at least 50GB of fast NVMe cache SSDs.
+When a Docker image build is routed to Depot either via [`depot build`](/docs/cli/reference#depot-build) or [`docker build`](/docs/container-builds/how-to-guides/docker-build#how-to-use-depot-with-docker), we launch optimized builders for each architecture requested with a persistent layer cache attached to them. Each builder has 16 CPUs, 32GB of memory, and at least 50GB of fast NVMe cache SSDs.
 
 ## How to build Docker images for Arm CPUs like M1/M2 MacBooks or AWS Graviton
 

content/guides/continuous-integration.mdx → content/container-builds/how-to-guides/continuous-integration.mdx

@@ -10,7 +10,7 @@ Depot provides a remote Docker build service that makes the image build process
 
 By routing the image build step of your CI to Depot, you can complete the image build up to 40x faster than you could in your generic CI provider. Saving you build minutes in your existing CI provider and, more importantly, saving you developer time waiting for the build to finish.
 
-The `depot build` command is a drop-in replacement for `docker build` and `docker buildx build`. Alternatively, you can [configure your local Docker CLI to use Depot as the default builder](/docs/guides/docker-build). Depot launches remote builders for both native Intel & Arm CPUs with 16 CPUs, 32 GB of memory, and a 50 GB persistent NVMe cache SSD.
+The `depot build` command is a drop-in replacement for `docker build` and `docker buildx build`. Alternatively, you can [configure your local Docker CLI to use Depot as the default builder](/docs/container-builds/how-to-guides/docker-build). Depot launches remote builders for both native Intel & Arm CPUs with 16 CPUs, 32 GB of memory, and a 50 GB persistent NVMe cache SSD.
 
 Running `depot` in a continuous integration environment is a great way to get fast and consistent builds with any CI provider. See below for documentation on integrating Depot with your CI provider.
 

content/guides/docker-build.mdx → content/container-builds/how-to-guides/docker-build.mdx

@@ -42,4 +42,4 @@ Again, you can confirm that builds are going to your Depot project by looking fo
 
 ## Using Depot with Docker Compose
 
-You can efficiently build Compose service images in parallel with Depot, with either `depot bake --load -f ./docker-compose.yml` or `docker compose build`. See [the Docker Compose integration guide](/docs/guides/docker-compose) for more information.
+You can efficiently build Compose service images in parallel with Depot, with either `depot bake --load -f ./docker-compose.yml` or `docker compose build`. See [the Docker Compose integration guide](/docs/container-builds/how-to-guides/docker-compose) for more information.

content/guides/docker-compose.mdx → content/container-builds/how-to-guides/docker-compose.mdx

@@ -82,7 +82,7 @@ Once configured, you can use `docker compose build` as usual. The `build` comman
 $ docker compose build
 ```
 
-See the [Docker integration guide](/docs/guides/docker-build) for more information about `depot configure-docker`.
+See the [Docker integration guide](/docs/container-builds/how-to-guides/docker-build) for more information about `depot configure-docker`.
 
 ### Caveats
 

content/guides/local-development.mdx → content/container-builds/how-to-guides/local-development.mdx

@@ -51,4 +51,4 @@ depot configure-docker
 docker build -t my-image:latest .
 ```
 
-For a full guide on using Depot via your existing `docker build` of `docker compose` commands, see our [Docker integration guide](/docs/guides/docker-build#docker-compose-build).
+For a full guide on using Depot via your existing `docker build` of `docker compose` commands, see our [Docker integration guide](/docs/container-builds/how-to-guides/docker-build#docker-compose-build).

content/container-builds/how-to-guides/optimal-dockerfiles.mdx

@@ -0,0 +1,14 @@
+---
+title: Best practice Dockerfiles
+ogTitle: Best practice Dockerfiles
+description: A set of best practice Dockerfiles for building Docker images
+---
+
+We've assembled some best practice Dockerfiles for building Docker images for several different languages:
+
+## Guides
+
+- [Dockerfile for Node.js using `pnpm`](/docs/container-builds/how-to-guides/optimal-dockerfiles/node-pnpm-dockerfile)
+- [Dockerfile for Python using `uv`](/docs/container-builds/how-to-guides/optimal-dockerfiles/python-uv-dockerfile)
+- [Dockerfile for Python using `poetry`](/docs/container-builds/how-to-guides/optimal-dockerfiles/python-poetry-dockerfile)
+- [Dockerfile for Rust](/docs/container-builds/how-to-guides/optimal-dockerfiles/rust-dockerfile)

content/languages/node.mdx → content/container-builds/how-to-guides/optimal-dockerfiles/node.mdx

@@ -8,4 +8,4 @@ We've assembled some best practice Dockerfiles for building Docker images for No
 
 ## Guides
 
-- [Dockerfile for Node.js using `pnpm`](/docs/languages/node-pnpm-dockerfile)
+- [Dockerfile for Node.js using `pnpm`](/docs/container-builds/how-to-guides/optimal-dockerfiles/node-pnpm-dockerfile)

content/languages/python.mdx → content/container-builds/how-to-guides/optimal-dockerfiles/python.mdx

@@ -8,5 +8,5 @@ We've assembled some best practice Dockerfiles for building Docker images for Py
 
 ## Guides
 
-- [Dockerfile for Python using `uv`](/docs/languages/python-uv-dockerfile)
-- [Dockerfile for Python using `poetry`](/docs/languages/python-poetry-dockerfile)
+- [Dockerfile for Python using `uv`](/docs/container-builds/how-to-guides/optimal-dockerfiles/python-uv-dockerfile)
+- [Dockerfile for Python using `poetry`](/docs/container-builds/how-to-guides/optimal-dockerfiles/python-poetry-dockerfile)

content/container-builds/overview.mdx

@@ -60,9 +60,9 @@ We support OIDC trust relationships with GitHub, CircleCI, Buildkite, and Mint s
 
 We can accelerate your image builds for other developer tools like Dev Containers & Docker Compose. You can either use our drop-in replacements for `docker build` and `docker bake`, or configure Docker to use Depot as the remote builder.
 
-- [How to use Depot in local development](/docs/guides/local-development)
-- [How to use Depot with Docker & Docker Compose](/docs/guides/docker-build)
-- [How to use Depot with Dev Containers](/docs/guides/devcontainers)
+- [How to use Depot in local development](/docs/container-builds/how-to-guides/local-development)
+- [How to use Depot with Docker & Docker Compose](/docs/container-builds/how-to-guides/docker-build)
+- [How to use Depot with Dev Containers](/docs/container-builds/how-to-guides/devcontainers)
 
 ### Build autoscaling
 
@@ -72,7 +72,7 @@ We offer autoscaling for our remote container builds. By default, all builds for
 
 We offer a built-in ephemeral registry that you can use to save the images from your `depot build` and `depot bake` commands to a temporary registry. You can then pull those images back down or push them to your final registry as you see fit.
 
-[Learn more about the ephemeral registry](/docs/guides/ephemeral-registry)
+[Learn more about the ephemeral registry](/docs/container-builds/how-to-guides/ephemeral-registry)
 
 ## How does it work?
 
@@ -82,7 +82,7 @@ Builder instances come with 16 CPUs, 32GB of memory, and an SSD disk for layer c
 
 We offer native Intel and Arm builder instances for all projects. Hence, both architectures build with zero emulation, and you don't have to run your own build runners to get native multi-platform images.
 
-Once built, the image can be left in the build cache (the default) or downloaded to the local Docker daemon with `--load` or pushed to a registry with `--push`. If `--push` is specified, the image is pushed to the registry directly from the remote builder via high-speed network links and does not use your local network connection. See our [private registry guide](/docs/guides/private-registries) for more details on pushing to private Docker registries like Amazon ECR or Docker Hub.
+Once built, the image can be left in the build cache (the default) or downloaded to the local Docker daemon with `--load` or pushed to a registry with `--push`. If `--push` is specified, the image is pushed to the registry directly from the remote builder via high-speed network links and does not use your local network connection. See our [private registry guide](/docs/container-builds/how-to-guides/private-registries) for more details on pushing to private Docker registries like Amazon ECR or Docker Hub.
 
 You can generally plug Depot into your existing Docker image build workflows with minimal changes, whether you're building locally or in CI.
 
@@ -144,11 +144,11 @@ Depot works best in the following scenarios:
 
 1. **Building the Docker image is slow in CI** — common CI providers often do not have native support for the Docker build cache. Instead, they require layer cache to be saved to and loaded from tarballs over slow networks. Often, CI providers offer limited resources as well, causing overall build time to be long.
 
-   Depot works within your existing CI workflow by swapping out the call to `docker build` with `depot build`. Or by configuring `docker` in your environment to leverage Depot. See [our continuous integration guides](/docs/guides/continuous-integration) for more information.
+   Depot works within your existing CI workflow by swapping out the call to `docker build` with `depot build`. Or by configuring `docker` in your environment to leverage Depot. See [our continuous integration guides](/docs/container-builds/how-to-guides/continuous-integration) for more information.
 
 2. **You need to build images for multiple platforms/multiple architectures (Intel and Arm)** — today, you're often stuck with managing your own build runner or relying on slow emulation in order to build multi-platform images. For example, CI providers usually run their workflows on Intel machines. So, to create a Docker image for Arm, you either have to launch your own BuildKit builder for Arm and connect to it from your CI provider. Or build your Arm image with slow QEMU emulation.
 
-   Depot can [build multi-platform and Arm images](/docs/guides/arm-containers) natively with zero-emulation and without running additional infrastructure.
+   Depot can [build multi-platform and Arm images](/docs/container-builds/how-to-guides/arm-containers) natively with zero-emulation and without running additional infrastructure.
 
 3. **Building the Docker image on your local machine is slow or expensive** — Docker can hog resources on developer machines, taking up valuable network, CPU, and memory resources. Depot executes builds on remote compute infrastructure; it offloads the CPU, memory, disk, and network resources required to that remote builder. If builds on your local machine are slow due to constrained compute, disk, or network, `depot build` eliminates the need to rely on your local environment.
 

content/api/overview.mdx → content/container-builds/reference/api-overview.mdx

@@ -12,7 +12,7 @@ We currently support the following SDKs for interacting with Depot:
 
 ## Authentication
 
-Authentication to the API is handled via an `Authorization` header with the value being an Organization Token that you generate inside of your Organization Settings. See the [Authentication docs](/docs/api/authentication) for more details.
+Authentication to the API is handled via an `Authorization` header with the value being an Organization Token that you generate inside of your Organization Settings. See the [Authentication docs](/docs/container-builds/reference/api-authentication) for more details.
 
 ## Security
 

content/overview/faq.mdx

@@ -18,23 +18,23 @@ We have all our authentication options documented for `depot` in our [CLI authen
 
 ## How do I push my images to a private registry?
 
-You can use the `--push` flag to push your images to a private registry. Our `depot` CLI uses your local Docker credentials provider. So, any registry you've logged into with `docker login` or similar will be available when running a Depot build. See our guide on [private registries](/docs/guides/private-registries) for more details.
+You can use the `--push` flag to push your images to a private registry. Our `depot` CLI uses your local Docker credentials provider. So, any registry you've logged into with `docker login` or similar will be available when running a Depot build. See our guide on [private registries](/docs/container-builds/how-to-guides/private-registries) for more details.
 
 ## Can I build Docker images for M1/M2 Macs?
 
-Yes! Depot supports native Arm container builds out of the box. We detect the architecture of the machine requesting a build via `depot build`. If that architecture is Arm, we route the build to a builder running Arm natively. You can build Docker images for M1/M2 Macs and run the resulting image immediately, as it is made specifically for your architecture. See our documentation on [Arm containers](/docs/guides/arm-containers) for more details.
+Yes! Depot supports native Arm container builds out of the box. We detect the architecture of the machine requesting a build via `depot build`. If that architecture is Arm, we route the build to a builder running Arm natively. You can build Docker images for M1/M2 Macs and run the resulting image immediately, as it is made specifically for your architecture. See our documentation on [Arm containers](/docs/container-builds/how-to-guides/arm-containers) for more details.
 
 ## Can I build multi-platform Docker images?
 
-Yes! Check out our [integration guide](/docs/guides/arm-containers#what-about-multi-architecture-containers) on how we do it.
+Yes! Check out our [integration guide](/docs/container-builds/how-to-guides/arm-containers#what-about-multi-architecture-containers) on how we do it.
 
 ## How should I use Depot with a monorepo setup?
 
 If you're building multiple images from a single monorepo, and the builds are lightweight, we tend to recommend using a single project. But we detail some other options in our [monorepo guide](/blog/how-to-use-depot-in-monorepos).
 
 ## Can I use Depot with my existing `docker build` or `docker buildx build` commands?
 
-Yes! We have a [`depot configure-docker`](/docs/cli/reference#depot-configure-docker) command that configures Depot as a plugin for the Docker CLI and sets Depot as the default builder for both `docker build` and `docker buildx build`. See our [`docker build` guide](/docs/guides/docker-build) for more details.
+Yes! We have a [`depot configure-docker`](/docs/cli/reference#depot-configure-docker) command that configures Depot as a plugin for the Docker CLI and sets Depot as the default builder for both `docker build` and `docker buildx build`. See our [`docker build` guide](/docs/container-builds/how-to-guides/docker-build) for more details.
 
 ## What are these extra files in my registry?
 

content/overview/index.mdx

@@ -38,4 +38,4 @@ We offer Depot-managed GitHub Actions Runners that bring the power of Depot to t
 
 If you need to build container images from untrusted sources or simply want to be able to call an API to build an image, we offer our remote container build infrastructure behind an API. You can use our build API to build container images from your own code on behalf of your own users using our `depot` CLI or with `buildx` as a library.
 
-[Learn more about the Build API.](/docs/api/overview)
+[Learn more about the Build API](/docs/container-builds/reference/api-overview)