From 15401fb2b11218b619196dd3d6401aebb02f186e Mon Sep 17 00:00:00 2001
From: Per Goncalves da Silva <pegoncal@redhat.com>
Date: Tue, 1 Oct 2024 14:42:54 +0200
Subject: [PATCH] organize docs

Signed-off-by: Per Goncalves da Silva <pegoncal@redhat.com>
---
 README.md                                     | 128 ++----------------
 .../create-installer-service-account.md       |   0
 docs/drafts/{refs => }/olmv1-limitations.md   |   0
 docs/{drafts => general}/architecture.md      |   0
 docs/{drafts => general}/developer.md         |   0
 .../olmv1_design_decisions.md}                |  96 +++++++------
 docs/general/olmv1_getting_started.md         | 117 ++++++++++++++++
 docs/{index.md => general/olmv1_overview.md}  |  16 ++-
 docs/{ => general}/olmv1_roadmap.md           |   0
 .../controlling-catalog-selection.md          |   0
 .../exploring-available-packages.md           |   2 +-
 ...eferences-permission-enforcement-plugin.md |   2 +-
 docs/{drafts => refs}/single-owner-objects.md |   0
 docs/{drafts => refs}/version-ranges.md       |   0
 .../catalog}/adding-a-catalog.md              |   0
 .../downgrade}/downgrading-an-extension.md    |   0
 .../installation}/installing-an-extension.md  |   2 +-
 .../installation}/provided-serviceaccount.md  |   0
 .../uninstalling-an-extension.md              |   0
 .../upgrade}/how-to-channel-based-upgrades.md |   0
 .../upgrade}/how-to-pin-version.md            |   2 +-
 .../upgrade}/how-to-version-range-upgrades.md |   2 +-
 .../upgrade}/how-to-z-stream-upgrades.md      |   2 +-
 .../upgrade}/upgrade-support.md               |   0
 .../upgrade}/upgrading-an-extension.md        |   8 +-
 mkdocs.yml                                    |  12 +-
 26 files changed, 210 insertions(+), 179 deletions(-)
 rename docs/drafts/{Tasks => }/create-installer-service-account.md (100%)
 rename docs/drafts/{refs => }/olmv1-limitations.md (100%)
 rename docs/{drafts => general}/architecture.md (100%)
 rename docs/{drafts => general}/developer.md (100%)
 rename docs/{olmv1_overview.md => general/olmv1_design_decisions.md} (71%)
 create mode 100644 docs/general/olmv1_getting_started.md
 rename docs/{index.md => general/olmv1_overview.md} (90%)
 rename docs/{ => general}/olmv1_roadmap.md (100%)
 rename docs/{drafts => refs}/controlling-catalog-selection.md (100%)
 rename docs/{Tasks => refs}/exploring-available-packages.md (99%)
 rename docs/{drafts => refs}/permissions-for-owner-references-permission-enforcement-plugin.md (84%)
 rename docs/{drafts => refs}/single-owner-objects.md (100%)
 rename docs/{drafts => refs}/version-ranges.md (100%)
 rename docs/{Tasks => tasks/catalog}/adding-a-catalog.md (100%)
 rename docs/{drafts => tasks/downgrade}/downgrading-an-extension.md (100%)
 rename docs/{Tasks => tasks/installation}/installing-an-extension.md (98%)
 rename docs/{drafts => tasks/installation}/provided-serviceaccount.md (100%)
 rename docs/{Tasks => tasks/uninstallation}/uninstalling-an-extension.md (100%)
 rename docs/{drafts => tasks/upgrade}/how-to-channel-based-upgrades.md (100%)
 rename docs/{drafts => tasks/upgrade}/how-to-pin-version.md (94%)
 rename docs/{drafts => tasks/upgrade}/how-to-version-range-upgrades.md (96%)
 rename docs/{drafts => tasks/upgrade}/how-to-z-stream-upgrades.md (95%)
 rename docs/{drafts => tasks/upgrade}/upgrade-support.md (100%)
 rename docs/{drafts/Tasks => tasks/upgrade}/upgrading-an-extension.md (96%)

diff --git a/README.md b/README.md
index c4a1ce3af..83aed5f0b 100644
--- a/README.md
+++ b/README.md
@@ -2,137 +2,25 @@
 The operator-controller is the central component of Operator Lifecycle Manager (OLM) v1.
 It extends Kubernetes with an API through which users can install extensions.
 
-## Mission
+## Overview
+
+OLM v1 is the follow-up to [OLM v0](https://github.com/operator-framework/operator-lifecycle-manager). Its purpose is to provide APIs, 
+controllers, and tooling that support the packaging, distribution, and lifecycling of Kubernetes extensions. It aims to:
 
-OLM’s purpose is to provide APIs, controllers, and tooling that support the packaging, distribution, and lifecycling of Kubernetes extensions. It aims to:
 - align with Kubernetes designs and user assumptions
 - provide secure, high-quality, and predictable user experiences centered around declarative GitOps concepts
 - give cluster admins the minimal necessary controls to build their desired cluster architectures and to have ultimate control
 
-## Overview
-
-OLM v1 is the follow-up to OLM v0, located [here](https://github.com/operator-framework/operator-lifecycle-manager).
-
 OLM v1 consists of two different components:
+
 * operator-controller (this repository)
 * [catalogd](https://github.com/operator-framework/catalogd)
 
-For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/olmv1_overview.md).
-
-### Installation
-
-The following script will install OLMv1 on a Kubernetes cluster. If you don't have one, you can deploy a Kubernetes cluster with [KIND](https://sigs.k8s.io/kind).
-
-> [!CAUTION]  
-> Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
-> may affect an existing installation of cert-manager and cause cluster instability.
-
-The latest version of Operator Controller can be installed with the following command:
-
-```bash
-curl -L -s https://github.com/operator-framework/operator-controller/releases/latest/download/install.sh | bash -s
-```
-
-## Getting Started with OLM v1
-
-This quickstart procedure will guide you through the following processes:
-* Deploying a catalog
-* Installing, upgrading, or downgrading an extension
-* Deleting catalogs and extensions
-
-### Create a Catalog
-
-OLM v1 is designed to source content from an on-cluster catalog in the file-based catalog ([FBC](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs)) format.
-These catalogs are deployed and configured through the `ClusterCatalog` resource. More information on adding catalogs
-can be found [here](./docs/Tasks/adding-a-catalog).
-
-The following example uses the official [OperatorHub](https://operatorhub.io) catalog that contains many different
-extensions to choose from. Note that this catalog contains packages designed to work with OLM v0, and that not all packages
-will work with OLM v1. More information on catalog exploration and content compatibility can be found [here](./docs/refs/catalog-queries.md). 
-
-To create the catalog, run the following command:
-
-```bash
-# Create ClusterCatalog
-kubectl apply -f - <<EOF
-apiVersion: catalogd.operatorframework.io/v1alpha1
-kind: ClusterCatalog
-metadata:
-  name: operatorhubio
-spec:
-  source:
-    type: image
-    image:
-      ref: quay.io/operatorhubio/catalog:latest
-      pollInterval: 10m
-EOF
-```
-
-Once the catalog is unpacked successfully, its content will be available for installation.
-
-```bash
-# Wait for the ClusterCatalog to be unpacked
-kubectl wait --for=condition=Unpacked=True clustercatalog/operatorhubio --timeout=60s
-```
-
-### Install a Cluster Extension
-
-For simplicity, the following example manifest includes all necessary resources to install the ArgoCD operator. 
-The manifest includes installation namespace, installer service account and associated minimal set of RBAC permissions 
-needed for installation, and the ClusterExtension resource, which specifies the name and version of the extension to install.
-More information on installing extensions can be found [here](docs/Tasks/installing-an-extension).
-
-```bash
-# Apply the sample ClusterExtension. Manifest already includes
-# namespace and adequately privileged service account
-kubectl apply -f https://raw.githubusercontent.com/operator-framework/operator-controller/main/config/samples/olm_v1alpha1_clusterextension.yaml
-```
-
-### Upgrade the Cluster Extension
-
-To upgrade the installed extension, update the version field in the ClusterExtension resource. Note that
-there must be CRD compatibility between the versions being upgraded, and the target version must be
-compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md), 
-compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md), 
-and on the extension upgrade process [here](./docs/drafts/Tasks/upgrading-an-extension).
-
-```bash
-# Update to v0.11.0
-kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.11.0"}}}}'
-
-```
-
-For information on the downgrade process, see [here](docs/drafts/downgrading-an-extension.md).
-
-### Uninstall the Cluster Extension
-
-To uninstall an extension, delete the ClusterExtension resource. This will trigger the uninstallation process, which will
-remove all resources created by the extension. More information on uninstalling extensions can be found [here](./docs/Tasks/uninstalling-an-extension).
-
-```bash
-# Delete cluster extension and residing namespace
-kubectl delete clusterextension/argocd
-```
-
-#### Cleanup
-
-Extension installation requires the creation of a namespace, an installer service account, and its RBAC. Once the
-extension is uninstalled, these resources can be cleaned up.
-
-```bash
-# Delete namespace, and by extension, the installer service account, Role, and RoleBinding
-kubectl delete namespace argocd
-```
+For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/general/olmv1_design_decisions.md).
 
-```bash
-# Delete installer service account cluster roles
-kubectl delete clusterrole argocd-installer-clusterrole && kubectl delete clusterrole argocd-rbac-clusterrole
-```
+## Getting Started
 
-```bash
-# Delete installer service account cluster role bindings
-kuebctl delete clusterrolebinding argocd-installer-binding && kubectl delete clusterrolebinding argocd-rbac-binding
-```
+To get started with OLM v1, please see our [Getting Started](docs/general/olmv1_getting_started.md) documentation.
 
 ## License
 
diff --git a/docs/drafts/Tasks/create-installer-service-account.md b/docs/drafts/create-installer-service-account.md
similarity index 100%
rename from docs/drafts/Tasks/create-installer-service-account.md
rename to docs/drafts/create-installer-service-account.md
diff --git a/docs/drafts/refs/olmv1-limitations.md b/docs/drafts/olmv1-limitations.md
similarity index 100%
rename from docs/drafts/refs/olmv1-limitations.md
rename to docs/drafts/olmv1-limitations.md
diff --git a/docs/drafts/architecture.md b/docs/general/architecture.md
similarity index 100%
rename from docs/drafts/architecture.md
rename to docs/general/architecture.md
diff --git a/docs/drafts/developer.md b/docs/general/developer.md
similarity index 100%
rename from docs/drafts/developer.md
rename to docs/general/developer.md
diff --git a/docs/olmv1_overview.md b/docs/general/olmv1_design_decisions.md
similarity index 71%
rename from docs/olmv1_overview.md
rename to docs/general/olmv1_design_decisions.md
index 417f6d5ba..79ec098fa 100644
--- a/docs/olmv1_overview.md
+++ b/docs/general/olmv1_design_decisions.md
@@ -1,48 +1,56 @@
-# OLM v1 Overview
+# The Road to v1: Multi-Tenancy Challenges, Lessons Learned, and Design Shifts
 
-## What won't OLMv1 do that OLMv0 did?
+This provides historical context on the design explorations and challenges that led to substantial design shifts between 
+OLM v1 and its predecessor. It explains the technical reasons why OLM v1 cannot support major v0 features, such as, 
+multi-tenancy, and namespace-specific controller configurations. Finally, it highlights OLM v1’s shift toward 
+more secure, predictable, and simple operations while moving away from some of the complex, error-prone features of OLM v0.
 
-TL;DR: OLMv1 cannot feasibly support multi-tenancy or any feature that assumes multi-tenancy. All multi-tenancy features end up falling over because of the global API system of Kubernetes. While this short conclusion may be unsatisfying, the reasons are complex and intertwined.
+## What won't OLM v1 do that OLM v0 did?
+
+TL;DR: OLM v1 cannot feasibly support multi-tenancy or any feature that assumes multi-tenancy. All multi-tenancy features end up falling over because of the global API system of Kubernetes. While this short conclusion may be unsatisfying, the reasons are complex and intertwined.
 
 ### Historical Context
 
 Nearly every active contributor in the Operator Framework project contributed to design explorations and prototypes over an entire year. For each of these design explorations, there are complex webs of features and assumptions that are necessary to understand the context that ultimately led to a conclusion of infeasibility.
 
 Here is a sampling of some of the ideas we explored:
-- [[WIP] OLM v1's approach to multi-tenancy](https://docs.google.com/document/d/1xTu7XadmqD61imJisjnP9A6k38_fiZQ8ThvZSDYszog/edit#heading=h.m19itc78n5rw)
-- [OLMv1 Multi-tenancy Brainstorming](https://docs.google.com/document/d/1ihFuJR9YS_GWW4_p3qjXu3WjvK0NIPIkt0qGixirQO8/edit#heading=h.vy9860qq1j01)
+
+- [OLM v1's approach to multi-tenancy](https://docs.google.com/document/d/1xTu7XadmqD61imJisjnP9A6k38_fiZQ8ThvZSDYszog/edit#heading=h.m19itc78n5rw)
+- [OLM v1 Multi-tenancy Brainstorming](https://docs.google.com/document/d/1ihFuJR9YS_GWW4_p3qjXu3WjvK0NIPIkt0qGixirQO8/edit#heading=h.vy9860qq1j01)
 
 ### Watched namespaces cannot be configured in a first-class API
 
-OLMv1 will not have a first-class API for configuring the namespaces that a controller will watch.
+OLM v1 will not have a first-class API for configuring the namespaces that a controller will watch.
 
 Kubernetes APIs are global. Kubernetes is designed with the assumption that a controller WILL reconcile an object no matter where it is in the cluster.
 
 However, Kubernetes does not assume that a controller will be successful when it reconciles an object.
 
 The Kubernetes design assumptions are:
+
 - CRDs and their controllers are trusted cluster extensions.
 - If an object for an API exists a controller WILL reconcile it, no matter where it is in the cluster.
 
-OLMv1 will make the same assumption that Kubernetes does and that users of Kubernetes APIs do. That is: If a user has RBAC to create an object in the cluster, they can expect that a controller exists that will reconcile that object. If this assumption does not hold, it will be considered a configuration issue, not an OLMv1 bug.
+OLM v1 will make the same assumption that Kubernetes does and that users of Kubernetes APIs do. That is: If a user has RBAC to create an object in the cluster, they can expect that a controller exists that will reconcile that object. If this assumption does not hold, it will be considered a configuration issue, not an OLM v1 bug.
 
 This means that it is a best practice to implement and configure controllers to have cluster-wide permission to read and update the status of their primary APIs. It does not mean that a controller needs cluster-wide access to read/write secondary APIs. If a controller can update the status of its primary APIs, it can tell users when it lacks permission to act on secondary APIs.
 
 ### Dependencies based on watched namespaces
 
-Since there will be no first-class support for configuration of watched namespaces, OLMv1 cannot resolve dependencies among bundles based on where controllers are watching.
+Since there will be no first-class support for configuration of watched namespaces, OLM v1 cannot resolve dependencies among bundles based on where controllers are watching.
 
-However, not all bundle constraints are based on dependencies among bundles from different packages. OLMv1 will be able to support constraints against cluster state. For example, OLMv1 could support a “kubernetesVersionRange” constraint that blocks installation of a bundle if the current kubernetes cluster version does not fall into the specified range.
+However, not all bundle constraints are based on dependencies among bundles from different packages. OLM v1 will be able to support constraints against cluster state. For example, OLM v1 could support a “kubernetesVersionRange” constraint that blocks installation of a bundle if the current kubernetes cluster version does not fall into the specified range.
 
 #### Background
 
-For packages that specify API-based dependencies, OLMv0’s dependency checker knows which controllers are watching which namespaces. While OLMv1 will have awareness of which APIs are present on a cluster (via the discovery API), it will not know which namespaces are being watched for reconciliation of those APIs. Therefore dependency resolution based solely on API availability would only work in cases where controllers are configured to watch all namespaces.
+For packages that specify API-based dependencies, OLMv0’s dependency checker knows which controllers are watching which namespaces. While OLM v1 will have awareness of which APIs are present on a cluster (via the discovery API), it will not know which namespaces are being watched for reconciliation of those APIs. Therefore dependency resolution based solely on API availability would only work in cases where controllers are configured to watch all namespaces.
 
 For packages that specify package-based dependencies, OLMv0’s dependency checker again knows which controllers are watching which namespaces. This case is challenging for a variety of reasons:
+
 1. How would a dependency resolver know which extensions were installed (let alone which extensions were watching which namespaces)? If a user is running the resolver, they would be blind to an installed extension that is watching their namespace if they don’t have permission to list extensions in the installation namespace. If a controller is running the resolver, then it might leak information to a user about installed extensions that the user is not otherwise entitled to know.
 2. Even if (1) could be overcome, the lack of awareness of watched namespaces means that the resolver would have to make assumptions. If only one controller is installed, is it watching the right set of namespaces to meet the constraint? If multiple controllers are installed, are any of them watching the right set of namespaces? Without knowing the watched namespaces of the parent and child controllers, a correct dependency resolver implementation is not possible to implement.
 
-Note that regardless of the ability of OLMv1 to perform dependency resolution (now or in the future), OLMv1 will not automatically install a missing dependency when a user requests an operator. The primary reasoning is that OLMv1 will err on the side of predictability and cluster-administrator awareness.
+Note that regardless of the ability of OLM v1 to perform dependency resolution (now or in the future), OLM v1 will not automatically install a missing dependency when a user requests an operator. The primary reasoning is that OLM v1 will err on the side of predictability and cluster-administrator awareness.
 
 ### "Watch namespace"-aware operator discoverability
 
@@ -50,7 +58,7 @@ When operators add APIs to a cluster, these APIs are globally visible. As stated
 
 Therefore, the API discoverability story boils down to answering this question for the user: “What APIs do I have access to in a given namespace?” Fortunately, built-in APIs exist to answer this question: Kubernetes Discovery, SelfSubjectRulesReview (SSRR), and SelfSubjectAccessReview (SSAR).
 
-However, helping users discover which actual controllers will reconcile those APIs is not possible unless OLMv1 knows which namespaces those controllers are watching.
+However, helping users discover which actual controllers will reconcile those APIs is not possible unless OLM v1 knows which namespaces those controllers are watching.
 
 Any solution here would be unaware of where a controller is actually watching and could only know “is there a controller installed that provides an implementation of this API?”. However even knowledge of a controller installation is not certain. Any user can use the discovery, SSRR, and SSAR. Not all users can list all Extensions (see [User discovery of “available” APIs](#user-discovery-of-available-apis)).
 
@@ -59,19 +67,21 @@ Any solution here would be unaware of where a controller is actually watching an
 The multi-tenancy promises that OLMv0 made were false promises. Kubernetes is not multi-tenant with respect to management of APIs (because APIs are global). Any promise that OLMv0 has around multi-tenancy evaporates when true tenant isolation attempts are made, and any attempt to fix a broken promise is actually just a bandaid on an already broken assumption.
 
 So where do we go from here? There are multiple solutions that do not involve OLM implementing full multi-tenancy support, some or all of which can be explored.
+
 1. Customers transition to a control plane per tenant
 2. Extension authors update their operators to support customers’ multi-tenancy use cases
 3. Extension authors with “simple” lifecycling concerns transition to other packaging and deployment strategies (e.g. helm charts)
 
 ### Single-tenant control planes
 
-One choice for customers would be to adopt low-overhead single-tenant control planes in which every tenant can have full control over their APIs and controllers and be truly isolated (at the control plane layer at least) from other tenants. With this option, the things OLMv1 cannot do (listed above) are irrelevant, because the purpose of all of those features is to support multi-tenant control planes in OLM.
+One choice for customers would be to adopt low-overhead single-tenant control planes in which every tenant can have full control over their APIs and controllers and be truly isolated (at the control plane layer at least) from other tenants. With this option, the things OLM v1 cannot do (listed above) are irrelevant, because the purpose of all of those features is to support multi-tenant control planes in OLM.
 
 The [Kubernetes multi-tenancy docs](https://kubernetes.io/docs/concepts/security/multi-tenancy/#virtual-control-plane-per-tenant) contain a good overview of the options in this space. Kubernetes vendors may also have their own virtual control plane implementations.
 
 ### Shift multi-tenant responsibility to operators
 
 There is a set of operators that both (a) provide fully namespace-scoped workload-style operands and that (b) provide a large amount of value to their users for advanced features like backup and migration. For these operators, the Operator Framework program would suggest that they shift toward supporting multi-tenancy directly. That would involve:
+
 1. Taking extreme care to avoid API breaking changes.
 2. Supporting multiple versions of their operands in a single version of the operator (if required by users in multi-tenant clusters).
 3. Maintaining support for versioned operands for the same period of time that the operator is supported for a given cluster version.
@@ -79,7 +89,7 @@ There is a set of operators that both (a) provide fully namespace-scoped workloa
 
 ### Operator authors ship controllers outside of OLM
 
-Some projects have been successful delivering and supporting their operator on Kubernetes, but outside of OLM, for example with helm-packaged operators. On this path, individual layered project teams have more flexibility in solving lifecycling problems for their users because they are unencumbered by OLM’s opinions. However the tradeoff is that those project teams and their users take on responsibility and accountability for safe upgrades, automation, and multi-tenant architectures. With OLMv1 no longer attempting to support multi-tenancy in a first-class way, these tradeoffs change and project teams may decide that a different approach is necessary.
+Some projects have been successful delivering and supporting their operator on Kubernetes, but outside of OLM, for example with helm-packaged operators. On this path, individual layered project teams have more flexibility in solving lifecycling problems for their users because they are unencumbered by OLM’s opinions. However the tradeoff is that those project teams and their users take on responsibility and accountability for safe upgrades, automation, and multi-tenant architectures. With OLM v1 no longer attempting to support multi-tenancy in a first-class way, these tradeoffs change and project teams may decide that a different approach is necessary.
 
 This path does not necessarily mean a scattering of content in various places. It would still be possible to provide customers with a marketplace of content (e.g. see https://artifacthub.io/).
 
@@ -110,10 +120,11 @@ OLM constantly monitors the state of all on-cluster resources for all the operat
 ### CRD Upgrade Safety Checks
 
 Before OLM upgrades a CRD, OLM performs a set of safety checks to identify any changes that potentially would have negative impacts, such as:
+
 - data loss
 - incompatible schema changes
 
-These checks may not be a guarantee that an upgrade is safe; instead, they are intended to provide an early warning sign for identifiable incompatibilities. False positives (OLMv1 claims a breaking change when there is none) and false negatives (a breaking change makes it through the check without being caught) are possible, at least while the OLMv1 team iterates on this feature.
+These checks may not be a guarantee that an upgrade is safe; instead, they are intended to provide an early warning sign for identifiable incompatibilities. False positives (OLM v1 claims a breaking change when there is none) and false negatives (a breaking change makes it through the check without being caught) are possible, at least while the OLM v1 team iterates on this feature.
 
 ### User permissions management
 
@@ -124,61 +135,65 @@ Also note that user permission management does not unlock operator discoverabili
 ### User discovery of “available” APIs
 
 In the future, the Operator Framework team could explore building an API similar to SelfSubjectAccessReview and SelfSubjectRulesReview that answers the question:
-“What is the public metadata of all of the extensions that are installed on the cluster that provide APIs that I have permission for in namespace X?”
+“What is the public metadata of all extensions that are installed on the cluster that provide APIs that I have permission for in namespace X?”
 
 One solution would be to join “installed extensions with user permissions”. If an installed extension provides an API that a user has RBAC permission for, that extension would be considered available to that user in that scope. This solution would not be foolproof: it makes the (reasonable) assumption that an administrator only configures RBAC for a user in a namespace where a controller is reconciling that object. If an administrator gives a user RBAC access to an API without also configuring that controller to watch the namespace that they have access to, the discovery solution would report an available extension, but then nothing would actually reconcile the object they create.
 
 This solution would tell users about API-only and API+controller bundles that are installed. It would not tell users about controller-only bundles, because they do not include APIs.
 
-Other similar API-centric solutions could be explored as well. For example, pursuing enhancements to OLMv1 or core Kubernetes related to API metadata and/or grouping.
+Other similar API-centric solutions could be explored as well. For example, pursuing enhancements to OLM v1 or core Kubernetes related to API metadata and/or grouping.
 
-A key note here is that controller-specific metadata like the version of the controller that will reconcile the object in a certain namespace is not necessary for discovery. Discovery is primarily about driving user flows around presenting information and example usage of a group of APIs such that CLIs and UIs can provide rich experiences around interactions with available APIs.
+A key insight here is that controller-specific metadata like the version of the controller that will reconcile the object in a certain namespace is not necessary for discovery. Discovery is primarily about driving user flows around presenting information and example usage of a group of APIs such that CLIs and UIs can provide rich experiences around interactions with available APIs.
 
 ## Approach
 
-We will adhere to the following tenets in our approach for the design and implementation of OLMv1
+We will adhere to the following tenets in our approach for the design and implementation of OLM v1
 
 ### Do not fight Kubernetes
 
 One of the key features of cloud-native applications/extensions/operators is that they typically come with a Kubernetes-based API (e.g. CRD) and a controller that reconciles instances of that API. In Kubernetes, API registration is cluster-scoped. It is not possible to register different APIs in different namespaces. Instances of an API can be cluster- or namespace-scoped. All APIs are global (they can be invoked/accessed regardless of namespace). For cluster-scoped APIs, the names of their instances must be unique. For example, it’s possible to have Nodes named “one” and “two”, but it’s not possible to have multiple Nodes named “two”. For namespace-scoped APIs, the names of their instances must be unique per namespace. The following illustrates this for ConfigMaps, a namespace-scoped API:
 
 Allowed
+
 - Namespace: test, name: my-configmap
 - Namespace: other, name: my-configmap
 
 Disallowed
+
 - Namespace: test, name: my-configmap
 - Namespace: test, name: my-configmap
 
 In cases where OLMv0 decides that joint ownership of CRDs will not impact different tenants, OLMv0 allows multiple installations of bundles that include the same named CRD, and OLMv0 itself manages the CRD lifecycle. This has security implications because it requires OLMv0 to act as a deputy, but it also pits OLM against the limitations of the Kubernetes API. OLMv0 promises that different versions of an operator can be installed in the cluster for use by different tenants without tenants being affected by each other. This is not a promise OLM can make because it is not possible to have multiple versions of the same CRD present on a cluster for different tenants.
 
-In OLMv1, we will not design the core APIs and controllers around this promise. Instead, we will build an API where ownership of installed objects is not shared. Managed objects are owned by exactly one extension.
+In OLM v1, we will not design the core APIs and controllers around this promise. Instead, we will build an API where ownership of installed objects is not shared. Managed objects are owned by exactly one extension.
 
 This pattern is generic, aligns with the Kubernetes API, and makes multi-tenancy a possibility, but not a guarantee or core concept. We will explore the implications of this design on existing OLMv0 registry+v1 bundles as part of the larger v0 to v1 migration design. For net new content, operator authors that intend multiple installations of operator on the same cluster would need to package their components to account for this ownership rule. Generally, this would entail separation along these lines:
 - CRDs, conversion webhook workloads, and admission webhook configurations and workloads, APIServices and workloads.
 - Controller workloads, service accounts, RBAC, etc.
 
-OLMv1 will include primitives (e.g. templating) to make it possible to have multiple non-conflicting installations of bundles.
+OLM v1 will include primitives (e.g. templating) to make it possible to have multiple non-conflicting installations of bundles.
 
-However it should be noted that the purpose of these primitives is not to enable multi-tenancy. It is to enable administrators to provide configuration for the installation of an extension. The fact that operators can be packaged as separate bundles and parameterized in a way that permits multiple controller installations is incidental, and not something that OLMv1 will encourage or promote.
+However, it should be noted that the purpose of these primitives is not to enable multi-tenancy. It is to enable administrators to provide configuration for the installation of an extension. The fact that operators can be packaged as separate bundles and parameterized in a way that permits multiple controller installations is incidental, and not something that OLM v1 will encourage or promote.
 
 ### Make OLM secure by default
 
 OLMv0 runs as cluster-admin, which is a security concern. OLMv0 has optional security controls for operator installations via the OperatorGroup, which allows a user with permission to create or update them to also set a ServiceAccount that will be used for authorization purposes on operator installations and upgrades in that namespace. If a ServiceAccount is not explicitly specified, OLM’s cluster-admin credentials are used. Another avenue that cluster administrators have is to lock down permissions and usage of the CatalogSource API, disable default catalogs, and provide tenants with custom vetted catalogs. However if a cluster admin is not aware of these options, the default configuration of a cluster results in users with permission to create a Subscription in namespaces that contain an OperatorGroup effectively have cluster-admin, because OLMv0 has unlimited permissions to install any bundle available in the default catalogs and the default community catalog is not vetted for limited RBAC. Because OLMv0 is used to install more RBAC and run arbitrary workloads, there are numerous potential vectors that attackers could exploit. While there are no known exploits and there has not been any specific concern reported from customers, we believe CNCF’s reputation rest on secure cloud-native software and that this is a non-negotiable area to improve.
 
 To make OLM secure by default:
-- OLMv1 will not be granted cluster admin permissions. Instead it will require service accounts provided by users to actually install, upgrade, and delete content. In addition to the security this provides, it also fulfills one of OLM’s long-standing requirements: halt when bundle upgrades require additional permissions and wait until those permissions are granted.
-- OLMv1 will use secure communication protocols between all internal components and between itself and its clients.
+
+- OLM v1 will not be granted cluster admin permissions. Instead, it will require service accounts provided by users to actually install, upgrade, and delete content. In addition to the security this provides, it also fulfills one of OLM’s long-standing requirements: halt when bundle upgrades require additional permissions and wait until those permissions are granted.
+- OLM v1 will use secure communication protocols between all internal components and between itself and its clients.
 
 ### Simple and predictable semantics for install, upgrade, and delete
 
 OLMv0 has grown into a complex web of functionality that is difficult to understand, even for seasoned Kubernetes veterans.
 
-In OLMv1 we will move to GitOps-friendly APIs that allow administrators to rely on their experience with conventional Kubernetes API behavior (declarative, eventually consistent) to manage operator lifecycles.
+In OLM v1 we will move to GitOps-friendly APIs that allow administrators to rely on their experience with conventional Kubernetes API behavior (declarative, eventually consistent) to manage operator lifecycles.
 
-OLMv1 will reduce its API surface down to two primary APIs that represent catalogs of content, and intent for that content to be installed on the cluster.
+OLM v1 will reduce its API surface down to two primary APIs that represent catalogs of content, and intent for that content to be installed on the cluster.
+
+OLM v1 will:
 
-OLMv1 will:
 - Permit administrators to pin to specific versions, channels, version ranges, or combinations of both.
 - Permit administrators to pause management of an installation for maintenance or troubleshooting purposes.
 - Put opinionated guardrails up by default (e.g. follow operator developer-defined upgrade edges).
@@ -188,53 +203,58 @@ OLMv1 will:
 ### APIs and behaviors to handle common controller patterns
 
 OLMv0 takes an extremely opinionated stance on the contents of the bundles it installs and in the way that operators can be lifecycled. The original designers believed these opinions would keep OLM’s scope limited and that they encompassed best practices for operator lifecycling. Some of these opinions are:
+
 - All bundles must include a ClusterServiceVersion, which ostensibly gives operator authors an API that they can use to fully describe how to run the operator, what permissions it requires, what APIs it provides, and what metadata to show to users.
 - Bundles cannot contain arbitrary objects. OLMv0 needs to have specific handling for each resource that it supports.
 - Cluster administrators cannot override OLM safety checks around CRD changes or upgrades.
 
-OLMv1 will take a slightly different approach:
-- It will not require bundles to have very specific controller-centric shapes. OLMv1 will happily install a bundle that contains a deployment, service, and ingress or a bundle that contains a single configmap.
+OLM v1 will take a slightly different approach:
+
+- It will not require bundles to have very specific controller-centric shapes. OLM v1 will happily install a bundle that contains a deployment, service, and ingress or a bundle that contains a single configmap.
 - However for bundles that do include CRDs, controllers, RBAC, webhooks, and other objects that relate to the behavior of the apiserver, OLM will continue to have opinions and special handling:
   - CRD upgrade checks (best effort)
   - Specific knowledge and handling of webhooks.
-- To the extent necessary OLMv1 will include optional controller-centric concepts in its APIs and or CLIs in order to facilitate the most common controller patterns. Examples could include:
+- To the extent necessary OLM v1 will include optional controller-centric concepts in its APIs and or CLIs in order to facilitate the most common controller patterns. Examples could include:
   - Permission management
   - CRD upgrade check policies
-- OLMv1 will continue to have opinions about upgrade traversals and CRD changes that help users prevent accidental breakage, but it will also allow administrators to disable safeguards and proceed anyway.
+- OLM v1 will continue to have opinions about upgrade traversals and CRD changes that help users prevent accidental breakage, but it will also allow administrators to disable safeguards and proceed anyway.
 
-OLMv0 has some support for automatic upgrades. However administrators cannot control the maximum version for automatic upgrades, and the upgrade policy (manual vs automatic) applies to all operators in a namespace. If any operator’s upgrade policy is manual, all upgrades of all operators in the namespace must be approved manually.
+OLMv0 has some support for automatic upgrades. However, administrators cannot control the maximum version for automatic upgrades, and the upgrade policy (manual vs automatic) applies to all operators in a namespace. If any operator’s upgrade policy is manual, all upgrades of all operators in the namespace must be approved manually.
 
-OLMv1 will have fine-grained control for version ranges (and pins) and for controlling automatic upgrades for individual operators regardless of the policy of other operators installed in the same namespace.
+OLM v1 will have fine-grained control for version ranges (and pins) and for controlling automatic upgrades for individual operators regardless of the policy of other operators installed in the same namespace.
 
 ### Constraint checking (but not automated on-cluster management)
 
 OLMv0 includes support for dependency and constraint checking for many common use cases (e.g. required and provided APIs, required cluster version, required package versions). It also has other constraint APIs that have not gained traction (e.g. CEL expressions and compound constraints). In addition to its somewhat hap-hazard constraint expression support, OLMv0 also automatically installs dependency trees, which has proven problematic in several respects:
+
 1. OLMv0 can resolve existing dependencies from outside the current namespace, but it can only install new dependencies in the current namespace. One scenario where this is problematic is if A depends on B, where A supports only OwnNamespace mode and B supports only AllNamespace mode. In that case, OLMv0’s auto dependency management fails because B cannot be installed in the same namespace as A (assuming the OperatorGroup in that namespace is configured for OwnNamespace operators to work).
 2. OLMv0’s logic for choosing a dependency among multiple contenders is confusing and error-prone, and an administrator’s ability to have fine-grained control of upgrades is essentially limited to building and deploying tailor-made catalogs.
 3. OLMv0 automatically installs dependencies. The only way for an administrator to avoid this OLMv0 functionality is to fully understand the dependency tree in advance and to then install dependencies from the leaves to the root so that OLMv0 always detects that dependencies are already met. If OLMv0 installs a dependency for you, it does not uninstall it when it is no longer depended upon.
 
-OLMv1 will not provide dependency resolution among packages in the catalog (see [Dependencies based on watched namespaces](#dependencies-based-on-watched-namespaces))
+OLM v1 will not provide dependency resolution among packages in the catalog (see [Dependencies based on watched namespaces](#dependencies-based-on-watched-namespaces))
 
-OLMv1 will provide constraint checking based on available cluster state. Constraint checking will be limited to checking whether the existing constraints are met. If so, install proceeds. If not, unmet constraints will be reported and the install/upgrade waits until constraints are met.
+OLM v1 will provide constraint checking based on available cluster state. Constraint checking will be limited to checking whether the existing constraints are met. If so, install proceeds. If not, unmet constraints will be reported and the install/upgrade waits until constraints are met.
 
-The Operator Framework team will perform a survey of registry+v1 packages that currently rely on OLMv0’s dependency features and will suggest a solution as part of the overall OLMv0 to OLMv1 migration effort.
+The Operator Framework team will perform a survey of registry+v1 packages that currently rely on OLMv0’s dependency features and will suggest a solution as part of the overall OLMv0 to OLM v1 migration effort.
 
 ### Client libraries and CLIs contribute to the overall UX
 
 OLMv0 has no official client libraries or CLIs that can be used to augment its functionality or provide a more streamlined user experience. The kubectl "operator" plugin was developed several years ago, but has never been a focus of the core Operator Framework development team, and has never factored into the overall architecture.
 
-OLMv1 will deliver an official CLI (likely by overhauling the kubectl operator plugin) and will use it to meet requirements that are difficult or impossible to implement in a controller, or where an architectural assessment dictates that a client is the better choice. This CLI would automate standard workflows over cluster APIs to facilitate simple administrative actions (e.g. automatically create RBAC and ServiceAccounts necessary for an extension installation as an optional step in the CLI’s extension install experience).
+OLM v1 will deliver an official CLI (likely by overhauling the kubectl operator plugin) and will use it to meet requirements that are difficult or impossible to implement in a controller, or where an architectural assessment dictates that a client is the better choice. This CLI would automate standard workflows over cluster APIs to facilitate simple administrative actions (e.g. automatically create RBAC and ServiceAccounts necessary for an extension installation as an optional step in the CLI’s extension install experience).
 
 The official CLI will provide administrators and users with a UX that covers the most common scenarios users will encounter.
 
-The official CLI will explicitly NOT attempt to cover complex scenarios. Maintainers will reject requests to over-complicate the CLI. Users with advanced use cases will be able to directly interact with OLMv1’s on-cluster APIs.
+The official CLI will explicitly NOT attempt to cover complex scenarios. Maintainers will reject requests to over-complicate the CLI. Users with advanced use cases will be able to directly interact with OLM v1’s on-cluster APIs.
 
 The idea is:
+
 - On-cluster APIs can be used to manage operators in 100% of cases (assuming bundle content is structured in a compatible way)
 - The official CLI will cover standard user flows, covering ~80% of use cases.
 - Third-party or unofficial CLIs will cover the remaining ~20% of use cases.
 
 Areas where the official CLI could provide value include:
+
 - Catalog interactions (search, list, inspect, etc.)
 - Standard install/upgrade/delete commands
 - Upgrade previews
diff --git a/docs/general/olmv1_getting_started.md b/docs/general/olmv1_getting_started.md
new file mode 100644
index 000000000..3f05620b6
--- /dev/null
+++ b/docs/general/olmv1_getting_started.md
@@ -0,0 +1,117 @@
+# Getting Started with OLM v1
+
+### Installation
+
+The following script will install OLMv1 on a Kubernetes cluster. If you don't have one, you can deploy a Kubernetes cluster with [KIND](https://sigs.k8s.io/kind).
+
+> [!CAUTION]  
+> Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
+> may affect an existing installation of cert-manager and cause cluster instability.
+
+The latest version of Operator Controller can be installed with the following command:
+
+```bash
+curl -L -s https://github.com/operator-framework/operator-controller/releases/latest/download/install.sh | bash -s
+```
+
+## Getting Started with OLM v1
+
+This quickstart procedure will guide you through the following processes:
+
+* Deploying a catalog
+* Installing, upgrading, or downgrading an extension
+* Deleting catalogs and extensions
+
+### Create a Catalog
+
+OLM v1 is designed to source content from an on-cluster catalog in the file-based catalog ([FBC](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs)) format.
+These catalogs are deployed and configured through the `ClusterCatalog` resource. More information on adding catalogs
+can be found [here](./docs/Tasks/adding-a-catalog).
+
+The following example uses the official [OperatorHub](https://operatorhub.io) catalog that contains many different
+extensions to choose from. Note that this catalog contains packages designed to work with OLM v0, and that not all packages
+will work with OLM v1. More information on catalog exploration and content compatibility can be found [here](./docs/refs/catalog-queries.md).
+
+To create the catalog, run the following command:
+
+```bash
+# Create ClusterCatalog
+kubectl apply -f - <<EOF
+apiVersion: catalogd.operatorframework.io/v1alpha1
+kind: ClusterCatalog
+metadata:
+  name: operatorhubio
+spec:
+  source:
+    type: image
+    image:
+      ref: quay.io/operatorhubio/catalog:latest
+      pollInterval: 10m
+EOF
+```
+
+Once the catalog is unpacked successfully, its content will be available for installation.
+
+```bash
+# Wait for the ClusterCatalog to be unpacked
+kubectl wait --for=condition=Unpacked=True clustercatalog/operatorhubio --timeout=60s
+```
+
+### Install a Cluster Extension
+
+For simplicity, the following example manifest includes all necessary resources to install the ArgoCD operator.
+The manifest includes installation namespace, installer service account and associated minimal set of RBAC permissions
+needed for installation, and the ClusterExtension resource, which specifies the name and version of the extension to install.
+More information on installing extensions can be found [here](docs/Tasks/installing-an-extension).
+
+```bash
+# Apply the sample ClusterExtension. Manifest already includes
+# namespace and adequately privileged service account
+kubectl apply -f https://raw.githubusercontent.com/operator-framework/operator-controller/main/config/samples/olm_v1alpha1_clusterextension.yaml
+```
+
+### Upgrade the Cluster Extension
+
+To upgrade the installed extension, update the version field in the ClusterExtension resource. Note that
+there must be CRD compatibility between the versions being upgraded, and the target version must be
+compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md),
+compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md),
+and on the extension upgrade process [here](./docs/drafts/Tasks/upgrading-an-extension).
+
+```bash
+# Update to v0.11.0
+kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.11.0"}}}}'
+
+```
+
+For information on the downgrade process, see [here](docs/drafts/downgrading-an-extension.md).
+
+### Uninstall the Cluster Extension
+
+To uninstall an extension, delete the ClusterExtension resource. This will trigger the uninstallation process, which will
+remove all resources created by the extension. More information on uninstalling extensions can be found [here](./docs/Tasks/uninstalling-an-extension).
+
+```bash
+# Delete cluster extension and residing namespace
+kubectl delete clusterextension/argocd
+```
+
+#### Cleanup
+
+Extension installation requires the creation of a namespace, an installer service account, and its RBAC. Once the
+extension is uninstalled, these resources can be cleaned up.
+
+```bash
+# Delete namespace, and by extension, the installer service account, Role, and RoleBinding
+kubectl delete namespace argocd
+```
+
+```bash
+# Delete installer service account cluster roles
+kubectl delete clusterrole argocd-installer-clusterrole && kubectl delete clusterrole argocd-rbac-clusterrole
+```
+
+```bash
+# Delete installer service account cluster role bindings
+kuebctl delete clusterrolebinding argocd-installer-binding && kubectl delete clusterrolebinding argocd-rbac-binding
+```
diff --git a/docs/index.md b/docs/general/olmv1_overview.md
similarity index 90%
rename from docs/index.md
rename to docs/general/olmv1_overview.md
index 6fda98519..ca3928973 100644
--- a/docs/index.md
+++ b/docs/general/olmv1_overview.md
@@ -1,4 +1,6 @@
-# What is Operator Lifecycle Manager (OLM)?
+# Overview
+
+## What is Operator Lifecycle Manager (OLM)?
 
 Operator Lifecycle Manager (OLM) is an open-source [CNCF](https://www.cncf.io/) project with the mission to manage the 
 lifecycle of cluster extensions centrally and declaratively on Kubernetes clusters. Its purpose is to make installing, 
@@ -6,12 +8,14 @@ running, and updating functional extensions to the cluster easy, safe, and repro
 
 Previously, OLM was focused on a particular type of cluster extension: [Operators](https://operatorhub.io/what-is-an-operator#:~:text=is%20an%20Operator-,What%20is%20an%20Operator%20after%20all%3F,or%20automation%20software%20like%20Ansible.). 
 Operators are a method of packaging, deploying, and managing a Kubernetes application. An Operator is composed of one or more controllers paired with one or both of the following objects:
+
 * One or more API extensions 
 * One or more [CustomResourceDefinitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) (CRDs).
 
 OLM helped define lifecycles for these extensions: from packaging and distribution to installation, configuration, upgrade, and removal.
 
 The first iteration of OLM, termed OLM v0, included several concepts and features targeting the stability, security, and supportability of the life-cycled applications, for instance:
+
 * A dependency model that enabled cluster extensions to focus on their primary purpose by delegating out of scope behavior to dependencies
 * A constraint model that allowed cluster extension developers to define support limitations such as conflicting extensions, and minimum kubernetes versions
 * A namespace-based multi-tenancy model in lieu of namespace-scoped CRDs
@@ -20,11 +24,12 @@ The first iteration of OLM, termed OLM v0, included several concepts and feature
 Since its initial release, OLM has helped catalyse the growth of Operators throughout the Kubernetes ecosystem. [OperatorHub.io](https://operatorhub.io/)
 is a popular destination for discovering Operators, and boasts over 300 packages from many different vendors.
 
-# Why are we building OLM v1?
+## Why are we building OLM v1?
 
 OLM v0 has been in production for over 5 years, and the community to leverage this experience and question the initial
 goals and assumptions of the project. OLM v1 is a complete redesign and rewrite of OLM taking into account this accumulated experience. 
 Compared to its predecessor, amongst other things, OLM v1 aims to provide:
+
 * A simpler API surface and mental model
 * Less opinionated automation and greater flexibility
 * Support for Kubernetes applications beyond only Operators
@@ -32,9 +37,10 @@ Compared to its predecessor, amongst other things, OLM v1 aims to provide:
 * Helm Chart support
 * GitOps support
 
-For an in-depth look at OLM v1, please see the [OLM v1 Overview](olmv1_overview.md) and the [Roadmap](olmv1_roadmap.md).
+To learn more about where v1 one came from, and where it's going, please see [The Road to v1: Multi-Tenancy Challenges, Lessons Learned, and Design Shifts](olmv1_design_decisions.md) 
+and our feature [Roadmap](olmv1_roadmap.md).
 
-# The OLM community
+## The OLM community
 
 In this next iteration of OLM, the community has also taken care to make it as contributor-friendly as possible, and welcomes new contributors. 
 The project is tracked in a [GitHub project](https://github.com/orgs/operator-framework/projects/8/), 
@@ -46,4 +52,4 @@ You can reach out to the OLM community for feedbacks/discussions/contributions i
   * [Operator Framework on Google Groups](https://groups.google.com/forum/#!forum/operator-framework)
   * Weekly in-person Working Group meeting: [olm-wg](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group)
 
-For further information on contributing, please consult the [Contribution Guide](../CONTRIBUTING.md)
+For further information on contributing, please consult the [Contribution Guide](../../CONTRIBUTING.md)
diff --git a/docs/olmv1_roadmap.md b/docs/general/olmv1_roadmap.md
similarity index 100%
rename from docs/olmv1_roadmap.md
rename to docs/general/olmv1_roadmap.md
diff --git a/docs/drafts/controlling-catalog-selection.md b/docs/refs/controlling-catalog-selection.md
similarity index 100%
rename from docs/drafts/controlling-catalog-selection.md
rename to docs/refs/controlling-catalog-selection.md
diff --git a/docs/Tasks/exploring-available-packages.md b/docs/refs/exploring-available-packages.md
similarity index 99%
rename from docs/Tasks/exploring-available-packages.md
rename to docs/refs/exploring-available-packages.md
index eb3e1499a..6b3071001 100644
--- a/docs/Tasks/exploring-available-packages.md
+++ b/docs/refs/exploring-available-packages.md
@@ -143,4 +143,4 @@ The following examples will show this default behavior, but for simplicity's sak
 
 ### Additional resources
 
-* [Catalog queries](../refs/catalog-queries.md)
+* [Catalog queries](catalog-queries.md)
diff --git a/docs/drafts/permissions-for-owner-references-permission-enforcement-plugin.md b/docs/refs/permissions-for-owner-references-permission-enforcement-plugin.md
similarity index 84%
rename from docs/drafts/permissions-for-owner-references-permission-enforcement-plugin.md
rename to docs/refs/permissions-for-owner-references-permission-enforcement-plugin.md
index f80d332e0..d283869f8 100644
--- a/docs/drafts/permissions-for-owner-references-permission-enforcement-plugin.md
+++ b/docs/refs/permissions-for-owner-references-permission-enforcement-plugin.md
@@ -2,7 +2,7 @@
 
 The [`OwnerReferencesPermissionEnforcement`](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#ownerreferencespermissionenforcement) admission plugin requires a user to have permission to set finalizers on owner objects when creating or updating an object to contain an `ownerReference` with `blockOwnerDeletion: true`.
 
-When operator-controller installs or upgrades a `ClusterExtension`, it sets an `ownerReference` on each object with `blockOwnerDeletion: true`. Therefore serviceaccounts configured in `.spec.serviceAccount.name` must have the following permission in a bound `ClusterRole`:
+When operator-controller installs or upgrades a `ClusterExtension`, it sets an `ownerReference` on each object with `blockOwnerDeletion: true`. Therefore, serviceaccounts configured in `.spec.serviceAccount.name` must have the following permission in a bound `ClusterRole`:
 
    ```yaml
    - apiGroups: ["olm.operatorframework.io"]
diff --git a/docs/drafts/single-owner-objects.md b/docs/refs/single-owner-objects.md
similarity index 100%
rename from docs/drafts/single-owner-objects.md
rename to docs/refs/single-owner-objects.md
diff --git a/docs/drafts/version-ranges.md b/docs/refs/version-ranges.md
similarity index 100%
rename from docs/drafts/version-ranges.md
rename to docs/refs/version-ranges.md
diff --git a/docs/Tasks/adding-a-catalog.md b/docs/tasks/catalog/adding-a-catalog.md
similarity index 100%
rename from docs/Tasks/adding-a-catalog.md
rename to docs/tasks/catalog/adding-a-catalog.md
diff --git a/docs/drafts/downgrading-an-extension.md b/docs/tasks/downgrade/downgrading-an-extension.md
similarity index 100%
rename from docs/drafts/downgrading-an-extension.md
rename to docs/tasks/downgrade/downgrading-an-extension.md
diff --git a/docs/Tasks/installing-an-extension.md b/docs/tasks/installation/installing-an-extension.md
similarity index 98%
rename from docs/Tasks/installing-an-extension.md
rename to docs/tasks/installation/installing-an-extension.md
index 1458a1653..1a0e956cf 100644
--- a/docs/Tasks/installing-an-extension.md
+++ b/docs/tasks/installation/installing-an-extension.md
@@ -8,7 +8,7 @@ After you add a catalog to your cluster, you can install an extension by creatin
 * A deployed and unpacked catalog
 * The name, and optionally version, or channel, of the [supported extension](../concepts/supported-extensions.md) to be installed
 * An existing namespace in which to install the extension
-* A suitable service account for installation (more information can be found [here](../drafts/Tasks/create-installer-service-account.md))
+* A suitable service account for installation (more information can be found [here](../../drafts/create-installer-service-account.md))
 
 
 ## Procedure
diff --git a/docs/drafts/provided-serviceaccount.md b/docs/tasks/installation/provided-serviceaccount.md
similarity index 100%
rename from docs/drafts/provided-serviceaccount.md
rename to docs/tasks/installation/provided-serviceaccount.md
diff --git a/docs/Tasks/uninstalling-an-extension.md b/docs/tasks/uninstallation/uninstalling-an-extension.md
similarity index 100%
rename from docs/Tasks/uninstalling-an-extension.md
rename to docs/tasks/uninstallation/uninstalling-an-extension.md
diff --git a/docs/drafts/how-to-channel-based-upgrades.md b/docs/tasks/upgrade/how-to-channel-based-upgrades.md
similarity index 100%
rename from docs/drafts/how-to-channel-based-upgrades.md
rename to docs/tasks/upgrade/how-to-channel-based-upgrades.md
diff --git a/docs/drafts/how-to-pin-version.md b/docs/tasks/upgrade/how-to-pin-version.md
similarity index 94%
rename from docs/drafts/how-to-pin-version.md
rename to docs/tasks/upgrade/how-to-pin-version.md
index 17bd7e1c6..5ba1c39db 100644
--- a/docs/drafts/how-to-pin-version.md
+++ b/docs/tasks/upgrade/how-to-pin-version.md
@@ -21,4 +21,4 @@ spec:
       name: argocd-installer
 ```
 
-For more information on SemVer version ranges see [version ranges](version-ranges.md)
+For more information on SemVer version ranges see [version ranges](../../refs/version-ranges.md)
diff --git a/docs/drafts/how-to-version-range-upgrades.md b/docs/tasks/upgrade/how-to-version-range-upgrades.md
similarity index 96%
rename from docs/drafts/how-to-version-range-upgrades.md
rename to docs/tasks/upgrade/how-to-version-range-upgrades.md
index 9a5c305ee..15bef4a9c 100644
--- a/docs/drafts/how-to-version-range-upgrades.md
+++ b/docs/tasks/upgrade/how-to-version-range-upgrades.md
@@ -21,4 +21,4 @@ spec:
       name: argocd-installer
 ```
 
-For more information on SemVer version ranges see [version-rages](version-ranges.md)
\ No newline at end of file
+For more information on SemVer version ranges see [version-rages](../../refs/version-ranges.md)
\ No newline at end of file
diff --git a/docs/drafts/how-to-z-stream-upgrades.md b/docs/tasks/upgrade/how-to-z-stream-upgrades.md
similarity index 95%
rename from docs/drafts/how-to-z-stream-upgrades.md
rename to docs/tasks/upgrade/how-to-z-stream-upgrades.md
index 835abc2b5..deeef2fc9 100644
--- a/docs/drafts/how-to-z-stream-upgrades.md
+++ b/docs/tasks/upgrade/how-to-z-stream-upgrades.md
@@ -21,4 +21,4 @@ spec:
       name: argocd-installer
 ```
 
-For more information on SemVer version ranges see [version ranges](version-ranges.md)
+For more information on SemVer version ranges see [version ranges](../../refs/version-ranges.md)
diff --git a/docs/drafts/upgrade-support.md b/docs/tasks/upgrade/upgrade-support.md
similarity index 100%
rename from docs/drafts/upgrade-support.md
rename to docs/tasks/upgrade/upgrade-support.md
diff --git a/docs/drafts/Tasks/upgrading-an-extension.md b/docs/tasks/upgrade/upgrading-an-extension.md
similarity index 96%
rename from docs/drafts/Tasks/upgrading-an-extension.md
rename to docs/tasks/upgrade/upgrading-an-extension.md
index ec13c7317..481a083d4 100644
--- a/docs/drafts/Tasks/upgrading-an-extension.md
+++ b/docs/tasks/upgrade/upgrading-an-extension.md
@@ -2,16 +2,16 @@
 
 Existing extensions can be upgraded by updating the version field in the ClusterExtension resource.
 
-For information on downgrading an extension, see [Downgrade an Extension](../downgrading-an-extension.md).
+For information on downgrading an extension, see [Downgrade an Extension](../downgrade/downgrading-an-extension.md).
 
 ## Prerequisites
 
 * You have an extension installed
-* The target version is compatible with OLM v1 (see [OLM v1 limitations](../refs/olmv1-limitations.md))
+* The target version is compatible with OLM v1 (see [OLM v1 limitations](../../drafts/olmv1-limitations.md))
 * CRD compatibility between the versions being upgraded or downgraded (see [CRD upgrade safety](../../refs/crd-upgrade-safety.md))
-* The installer service account's RBAC permissions are adequate for the target version (see [Minimal RBAC for Installer Service Account](create-installer-service-account.md))
+* The installer service account's RBAC permissions are adequate for the target version (see [Minimal RBAC for Installer Service Account](../../drafts/create-installer-service-account.md))
 
-For more detailed information see [Upgrade Support](../upgrade-support.md).
+For more detailed information see [Upgrade Support](upgrade-support.md).
 
 ## Procedure
 
diff --git a/mkdocs.yml b/mkdocs.yml
index cc95662a3..aecac92b5 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -9,15 +9,15 @@ theme:
 repo_url: https://github.com/operator-framework/operator-controller
 
 nav:
-  - Home: 'index.md'
+  - Home: 'olmv1_overview.md'
   - Components: 'components.md'
   - Tasks:
-    - Adding a catalog of extensions: 'Tasks/adding-a-catalog.md'
-    - Finding extensions to install: 'Tasks/exploring-available-packages.md'
-    - Installing an extension: 'Tasks/installing-an-extension.md'
-    - Deleting an extension: 'Tasks/uninstalling-an-extension.md'
+    - Adding a catalog of extensions: 'tasks/adding-a-catalog.md'
+    - Finding extensions to install: 'tasks/exploring-available-packages.md'
+    - Installing an extension: 'tasks/installing-an-extension.md'
+    - Deleting an extension: 'tasks/uninstalling-an-extension.md'
   - References:
-    - Supported extensions: 'refs//supported-extensions.md'
+    - Supported extensions: 'refs/supported-extensions.md'
     - API references:
       - Operator Controller API reference: 'refs/api/operator-controller-api-reference.md'
       - CatalogD API reference: 'refs/api/catalogd-api-reference.md'