diff --git a/.aspect/workflows/README.md b/.aspect/workflows/README.md
new file mode 100644
index 00000000..3d75c79b
--- /dev/null
+++ b/.aspect/workflows/README.md
@@ -0,0 +1,84 @@
+# Aspect Workflows demonstration deployment
+
+`bazel-examples` is a demonstration deployment of [Aspect Workflows](https://www.aspect.build/workflows) configured to run on Buildkite, CircleCI and GitHub Actions.
+
+You can see this Aspect Workflows demonstration deployment live for each CI host
+at the following URLS:
+
+- Buildkite: https://buildkite.com/aspect/bazel-examples
+- CircleCI: https://app.circleci.com/pipelines/github/aspect-build/bazel-examples-cci
+- GitHub Actions: https://github.com/aspect-build/bazel-examples-gha/actions/workflows/aspect-workflows.yaml
+
+## Aspect Workflows configuration yaml
+
+This is the [config.yaml](./config.yaml) file in this directory.
+
+## Buildkite pipeline configuration (in the Buildkite UI)
+
+There are two pipelines configured on Buildkite.
+
+1. Main build & test pipeline: https://buildkite.com/aspect/bazel-examples
+2. Scheduled warming pipeline: https://buildkite.com/aspect/bazel-examples-warming
+
+### Main build & test pipeline configuration
+
+The main build & test pipeline found at https://buildkite.com/aspect/bazel-examples is configured
+with the following yaml steps:
+
+```
+steps:
+  - label: ":aspect: Setup Aspect Workflows"
+    commands:
+      - "rosetta steps | buildkite-agent pipeline upload"
+    agents:
+      queue: aspect-small
+```
+
+> [!IMPORTANT]
+> The Setup Aspect Workflows step above is configured to run on the `aspect-small` queue that is serviced by a runner group made up of lightweight and inexpensive `t3a.small` AWS instances.
+
+### Scheduled warming pipeline configuration
+
+The scheduled warming pipeline found at https://buildkite.com/aspect/bazel-examples-warming is
+configured with the following yaml steps:
+
+```
+env:
+  ASPECT_WORKFLOWS_BIN_DIR: /etc/aspect/workflows/bin
+steps:
+  - label: ":fire: Create warming archives"
+    commands: |
+      echo "--- :aspect-build: Workflows environment"
+      ${ASPECT_WORKFLOWS_BIN_DIR}/configure_workflows_env
+      echo "--- :stethoscope: Agent health check"
+      ${ASPECT_WORKFLOWS_BIN_DIR}/agent_health_check
+      echo "--- :bazel: Create warming archive"
+      rosetta run warming
+      ${ASPECT_WORKFLOWS_BIN_DIR}/warming_archive
+    agents:
+      queue: aspect-warming
+```
+
+The warming pipeline is not configured to trigger on commits or PRs. Instead, it is triggered
+by a Buildkite pipeline schedule with the cron interval `0 1 * * 1-5 America/Los_Angeles`. It
+runs nightly on weekdays to create up-to-date warming archives containing cached external repositories.
+The most recent warming archive is restored during bootstrap of the "default" runner group to speed up
+the first build on cold runners.
+
+## GitHub Actions pipeline configuration
+
+This includes 3 files:
+
+1.  [.github/workflows/aspect-workflows.yaml](../../.github/workflows/aspect-workflows.yaml) : Aspect Workflows CI workflow
+
+1.  [.github/workflows/aspect-workflows-warming.yaml](../../.github/workflows/aspect-workflows-warming.yaml) : Aspect Workflows warming cron workflow
+
+1.  [.github/workflows/.aspect-workflows-reusable.yaml](../../.github/workflows/.aspect-workflows-reusable.yaml) : Aspect Workflows Reusable Workflow for GitHub Actions.
+    This files is vendored from the upstream [.aspect-workflows-reusable.yaml](https://github.com/aspect-build/workflows-action/blob/main/.github/workflows/.aspect-workflows-reusable.yaml) for the Workflows version configured in the deployment.
+
+## CircleCI pipeline configuration (generated)
+
+The CircleCI pipeline configuration, [.circleci/config.yml](../../.circleci/config.yml), is generated by the Aspect Workflows `rosetta` tool.
+
+`rosetta` is fetched by Bazel as a WORKSPACE dep (defined in [.aspect/workflows/deps.bzl](./deps.bzl)).
+The BUILD file targets to generate the CircleCI pipeline from the Aspect Workflows [config.yaml](./config.yaml) and a demostration user CircleCI configuration, [.circleci/user.yml](../../.circleci/user.yml), for non-Workflows steps are defined in [.circleci/BUILD.bazel](../../.circleci/BUILD.bazel)
diff --git a/.aspect/workflows/bazelrc b/.aspect/workflows/bazelrc
index fbbd0749..33fb1ce4 100644
--- a/.aspect/workflows/bazelrc
+++ b/.aspect/workflows/bazelrc
@@ -2,6 +2,7 @@
 common --remote_download_outputs=minimal
 common --nobuild_runfile_links
 
+# remote execution
 common:rbe --extra_execution_platforms=//bazel/platforms:x86_64_linux_remote
 common:rbe --host_platform=//bazel/platforms:x86_64_linux_remote
 common:rbe --remote_executor=unix:///mnt/ephemeral/buildbarn/.cache/bb_clientd/grpc
diff --git a/.aspect/workflows/config.yaml b/.aspect/workflows/config.yaml
index 5b57a3a5..00d05eab 100644
--- a/.aspect/workflows/config.yaml
+++ b/.aspect/workflows/config.yaml
@@ -1,3 +1,4 @@
+# See https://docs.aspect.build/workflows/configuration
 tasks:
   - checkout:
       update_strategy: rebase
diff --git a/.circleci/BUILD.bazel b/.circleci/BUILD.bazel
index 772b4528..f64aed1d 100644
--- a/.circleci/BUILD.bazel
+++ b/.circleci/BUILD.bazel
@@ -2,7 +2,7 @@ load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_file")
 
 CIRCLECI_ORG = "aspect-build"
 
-CIRCLECI_USER_CONFIG_FILE = "//.circleci:user-config.yml"
+CIRCLECI_USER_CONFIG_FILE = "//.circleci:user.yml"
 
 alias(
     name = "rosetta",
diff --git a/.circleci/user-config.yml b/.circleci/user.yml
similarity index 100%
rename from .circleci/user-config.yml
rename to .circleci/user.yml