diff --git a/README.md b/README.md
index 00ac5f707d..93e9c5e3f7 100644
--- a/README.md
+++ b/README.md
@@ -32,27 +32,27 @@ Shipwright supports any tool that can build container images in Kubernetes clust
 
 ## Try It!
 
-* We assume you already have a Kubernetes cluster (v1.20+). If you don't, you can use [KinD](https://kind.sigs.k8s.io), which you can install by running [`./hack/install-kind.sh`](./hack/install-kind.sh).
+- We assume you already have a Kubernetes cluster (v1.20+). If you don't, you can use [KinD](https://kind.sigs.k8s.io), which you can install by running [`./hack/install-kind.sh`](./hack/install-kind.sh).
 
-* We also require a Tekton installation (v0.27+). To install the newest supported version, run:
+- We also require a Tekton installation (v0.27+). To install the newest supported version, run:
 
   ```bash
   kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/previous/v0.30.0/release.yaml
   ```
 
-* Install the Shipwright deployment. To install the latest version, run:
+- Install the Shipwright deployment. To install the latest version, run:
 
   ```bash
   kubectl apply --filename https://github.com/shipwright-io/build/releases/download/v0.8.0/release.yaml
   ```
 
-* Install the Shipwright strategies. To install the latest version, run:
+- Install the Shipwright strategies. To install the latest version, run:
 
   ```bash
   kubectl apply --filename https://github.com/shipwright-io/build/releases/download/v0.8.0/sample-strategies.yaml
   ```
 
-* Generate a secret to access your container registry, such as one on [Docker Hub](https://hub.docker.com/) or [Quay.io](https://quay.io/):
+- Generate a secret to access your container registry, such as one on [Docker Hub](https://hub.docker.com/) or [Quay.io](https://quay.io/):
 
   ```bash
   REGISTRY_SERVER=https://index.docker.io/v1/ REGISTRY_USER=<your_registry_user> REGISTRY_PASSWORD=<your_registry_password>
@@ -63,54 +63,32 @@ Shipwright supports any tool that can build container images in Kubernetes clust
       --docker-email=<your_email>
   ```
 
-* Create a *Build* object, replacing `<REGISTRY_ORG>` with the registry username your `push-secret` secret have access to:
+- Create and submit your *BuildRun* object, replacing `<REGISTRY_ORG>` with the registry username your `push-secret` secret have access to:
 
   ```bash
-  REGISTRY_ORG=<your_registry_org>
-  cat <<EOF | kubectl apply -f -
-  apiVersion: shipwright.io/v1alpha1
-  kind: Build
-  metadata:
-    name: buildpack-nodejs-build
-  spec:
-    source:
-      url: https://github.com/shipwright-io/sample-nodejs
-      contextDir: source-build
-    strategy:
-      name: buildpacks-v3
-      kind: ClusterBuildStrategy
-    output:
-      image: docker.io/${REGISTRY_ORG}/sample-nodejs:latest
-      credentials:
-        name: push-secret
-  EOF
-  ```
-
-To view the *Build* which you just created:
-
-  ```
- $ kubectl get builds
- 
-  NAME                     REGISTERED   REASON      BUILDSTRATEGYKIND      BUILDSTRATEGYNAME   CREATIONTIME
-  buildpack-nodejs-build   True         Succeeded   ClusterBuildStrategy   buildpacks-v3       68s
-  ```  
-* Submit your *BuildRun*:
-
-  ```bash
-  cat <<EOF | kubectl create -f -
+  kubectl create --filename - <<EOF
   apiVersion: shipwright.io/v1alpha1
   kind: BuildRun
   metadata:
     generateName: buildpack-nodejs-buildrun-
   spec:
-    buildRef:
-      name: buildpack-nodejs-build
+    buildSpec:
+      source:
+        url: https://github.com/shipwright-io/sample-nodejs
+        contextDir: source-build
+      strategy:
+        name: buildpacks-v3
+        kind: ClusterBuildStrategy
+      output:
+        image: docker.io/${REGISTRY_ORG}/sample-nodejs:latest
+        credentials:
+          name: push-secret
   EOF
   ```
 
-* Wait until your *BuildRun* is completed and then you can view it as follows:
+- Wait until your *BuildRun* is completed and then you can view it as follows:
 
-  ```
+  ```bash
   $ kubectl get buildruns
   
   NAME                              SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
@@ -123,7 +101,7 @@ To view the *Build* which you just created:
   kubectl get buildrun --output name | xargs kubectl wait --for=condition=Succeeded --timeout=180s
   ```
 
-* After your *BuildRun* is completed, check your container registry, you will find the new generated image uploaded there.
+- After your *BuildRun* is completed, check your container registry, you will find the new generated image uploaded there.
 
 ## Please tell us more!
 
@@ -175,16 +153,16 @@ Our sample build strategies are all functional on linux/amd64. Their support on
 
 We host weekly meetings for users, contributors, maintainers and anyone interested in the project. The weekly meetings take place on Mondays at 1pm UTC.
 
-* Meeting [minutes](https://github.com/shipwright-io/community/issues?q=is%3Aissue+label%3Acommunity+label%3Ameeting)
-* Public calendar [invite](https://calendar.google.com/calendar/u/1?cid=Y19iMWVndjc3anUyczJkbWNkM2R1ZnAxazhuNEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t)
+- Meeting [minutes](https://github.com/shipwright-io/community/issues?q=is%3Aissue+label%3Acommunity+label%3Ameeting)
+- Public calendar [invite](https://calendar.google.com/calendar/u/1?cid=Y19iMWVndjc3anUyczJkbWNkM2R1ZnAxazhuNEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t)
 
 ### Want to contribute
 
 We are so excited to have you!
 
-* See [CONTRIBUTING.md](CONTRIBUTING.md) for an overview of our processes
-* See [DEVELOPMENT.md](DEVELOPMENT.md) for how to get started
-* See [HACK.md](HACK.md) for how to build, test & run
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for an overview of our processes
+- See [DEVELOPMENT.md](DEVELOPMENT.md) for how to get started
+- See [HACK.md](HACK.md) for how to build, test & run
   (advanced reading material)
 - Look at our
   [good first issues](https://github.com/shipwright-io/build/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
diff --git a/docs/buildrun.md b/docs/buildrun.md
index 6e5d58cbdc..dca29b43cf 100644
--- a/docs/buildrun.md
+++ b/docs/buildrun.md
@@ -81,6 +81,31 @@ spec:
     name: buildpack-nodejs-build-namespaced
 ```
 
+_Please note:_ The `BuildRef` and `BuildSpec` are mutually exclusive.
+
+### Defining the BuildSpec
+
+Alternatively to `BuildRef`, a complete `BuildSpec` can be embedded into the `BuildRun` to be used for the build.
+
+```yaml
+apiVersion: shipwright.io/v1alpha1
+kind: BuildRun
+metadata:
+  name: buildpack-nodejs-buildrun-namespaced
+spec:
+  buildSpec:
+    source:
+      url: https://github.com/shipwright-io/sample-go.git
+      contextDir: source-build
+    strategy:
+      kind: ClusterBuildStrategy
+      name: buildpacks-v3
+    output:
+      image: foo/bar:latest
+```
+
+_Please note:_ The `BuildRef` and `BuildSpec` are mutually exclusive.
+
 ### Defining ParamValues
 
 A `BuildRun` resource can define _paramValues_ for parameters specified in the build strategy. If a value has been provided for a parameter with the same name in the `Build` already, then the value from the `BuildRun` will have precedence.
@@ -248,13 +273,13 @@ The `status.conditions` hosts different fields, like `status`, `reason` and `mes
 
 The following table illustrates the different states a BuildRun can have under its `status.conditions`:
 
-| Status | Reason | CompletionTime is set | Description |
-| --- | --- | --- | --- |
-| Unknown | Pending                                  | No  | The BuildRun is waiting on a Pod in status Pending. |
-| Unknown | Running                                  | No  | The BuildRun has been validate and started to perform its work. |l
-| Unknown | Running                                  | No  | The BuildRun has been validate and started to perform its work. |
-| Unknown | BuildRunCanceled                         | No  | The user requested the BuildRun to be canceled.  This results in the BuildRun controller requesting the TaskRun be canceled.  Cancellation has not been done yet. |
-| True    | Succeeded                                | Yes | The BuildRun Pod is done. |
+| Status   | Reason                                  | CompletionTime is set | Description |
+| ---      | ---                                     | --- | --- |
+| Unknown  | Pending                                 | No  | The BuildRun is waiting on a Pod in status Pending. |
+| Unknown  | Running                                 | No  | The BuildRun has been validate and started to perform its work. |l
+| Unknown  | Running                                 | No  | The BuildRun has been validate and started to perform its work. |
+| Unknown  | BuildRunCanceled                        | No  | The user requested the BuildRun to be canceled.  This results in the BuildRun controller requesting the TaskRun be canceled.  Cancellation has not been done yet. |
+| True     | Succeeded                               | Yes | The BuildRun Pod is done. |
 | False    | Failed                                  | Yes | The BuildRun failed in one of the steps. |
 | False    | BuildRunTimeout                         | Yes | The BuildRun timed out. |
 | False    | UnknownStrategyKind                     | Yes | The Build specified strategy Kind is unknown. (_options: ClusterBuildStrategy or BuildStrategy_) |
@@ -276,6 +301,7 @@ The following table illustrates the different states a BuildRun can have under i
 | False    | BuildNotFound                           | Yes | The related Build in the BuildRun was not found. |
 | False    | BuildRunCanceled                        | Yes | The BuildRun and underlying TaskRun were canceled successfully. |
 | False    | BuildRunNameInvalid                     | Yes | The defined `BuildRun` name (`metadata.name`) is invalid. The `BuildRun` name should be a [valid label value](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). |
+| False    | BuildRunInvalid                         | Yes | The defined `BuildRun` fields are invalid, i.e. a disallowed combination of fields is used. |
 | False    | PodEvicted                              | Yes | The BuildRun Pod was evicted from the node it was running on. See [API-initiated Eviction](https://kubernetes.io/docs/concepts/scheduling-eviction/api-eviction/) and [Node-pressure Eviction](https://kubernetes.io/docs/concepts/scheduling-eviction/node-pressure-eviction/) for more information. |
 
 _Note_: We heavily rely on the Tekton TaskRun [Conditions](https://github.com/tektoncd/pipeline/blob/main/docs/taskruns.md#monitoring-execution-status) for populating the BuildRun ones, with some exceptions.