diff --git a/docs/design-docs/CaD Core Architecture.svg b/docs/design-docs/CaD Core Architecture.svg
index f2e415be84..2650dbb29a 100644
--- a/docs/design-docs/CaD Core Architecture.svg
+++ b/docs/design-docs/CaD Core Architecture.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/porch/docs/porch-roadmap.md b/porch/docs/porch-roadmap.md
index 942cf13618..7d08dcb862 100644
--- a/porch/docs/porch-roadmap.md
+++ b/porch/docs/porch-roadmap.md
@@ -31,6 +31,10 @@ document outlining future direction and work in different Porch subsystems.
* Support updating repository registration, for example when `Repository`
resource is modified to point to a different repository, or even a different
type of a repository (Git --> OCI).
+* Support read only repositories. Porch will allow package discovery in a read
+ only repository but attempt to create/modify package in read only repository
+ will result in an error. Consider supporting via RBAC so different principals
+ can have different level of access to the same repository.
* Implement repository cache eviction policy
* Support `ObjectMeta.GenerateName` for `PackageRevision` creation. Currently
package names are computed as -. Ideally Porch would accept
diff --git a/site/book/08-package-orchestration/00.md b/site/book/08-package-orchestration/00.md
new file mode 100644
index 0000000000..ccca18f51c
--- /dev/null
+++ b/site/book/08-package-orchestration/00.md
@@ -0,0 +1,62 @@
+In this chapter, we are going to cover _package orchestration_ - management
+of package lifecycle supported by the kpt toolchain.
+
+Package Orchestration encompasses management of the overall lifecycle of the
+configuration package, including:
+
+* management of package repositories
+* discovery of configuration packages and kpt functions
+* creating, modifying, updating, and deleting packages
+* versioning packages
+* WYSIWYG package authoring and customization with _guardrails_
+* evaluation of functions on package data
+* approval flow to publish a change to a configuration package
+* deployment and rollouts
+
+Package Orchestration enables [workflows](/book/02-concepts/02-workflows)
+similar to those supported by the kpt CLI, but makes them available as a
+service and enables creation of WYSIWYG user experiences, similar to the
+proof-of-concept [Backstage plugin](/guides/namespace-provisioning-ui).
+
+## Package Orchestration Concepts
+
+Package Orchestration relies on the already familiar concepts of
+[**Package**](/book/02-concepts/01-packages)
+and [**Function**](/book/02-concepts/03-functions).
+
+Package Orchestrator supports several **lifecycle stages** of packages:
+* ***Draft*** - package is being created or edited. The package contents can be
+ modified but package is not ready to be used (deployed or cloned)
+* ***Proposed*** - author of the package proposed that the package be published
+* ***Published*** - the changes to the package have been approved and the
+ package is ready to be used. Published packages can be deployed or cloned.
+
+A **Repository** containing kpt packages (for example a [git][] repository or
+an [OCI][] container registry) can be registered with the Package Orchestrator
+to enable package discovery or management.
+
+An [OCI][] container registry containing kpt functions can be registered with
+the Package Orchestrator to enable discovery of kpt functions.
+
+A repository containing *packages* can be designated as a
+***deployment repository***. *Published* packages in a deployment repository are
+considered deployment-ready.
+
+
+[git]: https://git-scm.org/
+[oci]: https://opencontainers.org/
+[config sync]: https://cloud.google.com/anthos-config-management/docs/config-sync-overview
+
+The following image illustrates how Package Orchestration fits into the overall
+configuration management ecosystem. Package Orchestration service enables
+management of packages in registered repositories and enables WYSIWYG UI
+experience of package authoring.
+A separate GitOps deployment mechanism (for example [Config Sync][]) is used to
+deploy published packages to realize the live state from the configuration and
+provides observability of the status of deployed resources.
+
+
+
+Dedicated user guides are available for the use of Porch with
+* the [Backstage UI](/guides/namespace-provisioning-ui)
+* the [kpt cli](/guides/porch-user-guide)
diff --git a/site/book/README.md b/site/book/README.md
index 005dd90c80..749c12c9f1 100644
--- a/site/book/README.md
+++ b/site/book/README.md
@@ -14,6 +14,7 @@ This book is organized as follows:
- [Chapter 5] guides you through developing custom functions.
- [Chapter 6] covers how to deploy a package to a Kubernetes cluster.
- [Chapter 7] covers effective customizations techniques.
+- [Chapter 8] covers package orchestration concepts and support in kpt toolchain.
Let's get started!
@@ -24,3 +25,4 @@ Let's get started!
[chapter 5]: /book/05-developing-functions/
[chapter 6]: /book/06-deploying-packages/
[chapter 7]: /book/07-effective-customizations/
+[chapter 8]: /book/08-package-orchestration/
diff --git a/site/guides/namespace-provisioning-cli.md b/site/guides/namespace-provisioning-cli.md
index ce19fef250..48103370c1 100644
--- a/site/guides/namespace-provisioning-cli.md
+++ b/site/guides/namespace-provisioning-cli.md
@@ -329,10 +329,10 @@ Now that we have a basic namespace package in place, let's publish it so that
other users can consume it.
```shell
-$cd .. && git add basens && git commit -am "initial pkg"
-$git push origin main
+$ cd .. && git add basens && git commit -am "initial pkg"
+$ git push origin main
-$git tag basens/v0 && git push origin basens/v0
+$ git tag basens/v0 && git push origin basens/v0
```
So, now the package should be available in the `blueprint` repo. Consumers
diff --git a/site/guides/porch-user-guide.md b/site/guides/porch-user-guide.md
index 25b062559c..cac4bf0feb 100644
--- a/site/guides/porch-user-guide.md
+++ b/site/guides/porch-user-guide.md
@@ -126,7 +126,7 @@ The command `kpt alpha repo unregister` can be used to unregister a repository:
```sh
# Unregister a repository
-$ kpt alpha repo unregister deployments
+$ kpt alpha repo unregister deployments --namespace default
```
## Package Discovery And Introspection
diff --git a/site/guides/wysiwyg.svg b/site/guides/wysiwyg.svg
deleted file mode 100644
index bde9048d8e..0000000000
--- a/site/guides/wysiwyg.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/site/sidebar.md b/site/sidebar.md
index 3ca3c4db8c..f83c8a4158 100644
--- a/site/sidebar.md
+++ b/site/sidebar.md
@@ -34,6 +34,7 @@
- [7.1 Single Value Replacement](book/07-effective-customizations/01-single-value-replacement.md)
- [7.2 Limiting Package Changes](book/07-effective-customizations/02-limiting-package-changes.md)
- [7.3 Generation](book/07-effective-customizations/03-generation.md)
+ - [8 Package Orchestration](book/08-package-orchestration/)
- [Reference](reference/)
- [Annotations](reference/annotations/)
- [apply-time mutation](reference/annotations/apply-time-mutation/)
diff --git a/site/static/images/package-orchestration.svg b/site/static/images/package-orchestration.svg
new file mode 100644
index 0000000000..2650dbb29a
--- /dev/null
+++ b/site/static/images/package-orchestration.svg
@@ -0,0 +1 @@
+
\ No newline at end of file