chore: Update platform concepts based on feedback

docs/main/03-reference/11-promises/09-status-events.mdx

@@ -1,6 +1,8 @@
 ---
 title: Promise Status and Events
 description: Understand the status conditions and events of a Promise.
+sidebar_label: Status and Events
+keywords: [promise status, promise events, promise conditions, promise lifecycle]
 id: promise-status-events
 slug: /main/reference/promises/promise-status-events
 ---

docs/main/03-reference/13-destinations/01-destinations.md

@@ -163,31 +163,3 @@ often required by GitOps tools to ensure that all dependencies are ready before
 resources themselves are applied.
 
 :::
-
-## Status
-
-A condition of type `Ready` is provided to enable waiting for the Destination to be ready. The Destination is considered
-ready when Kratix is able to write test documents successfully.
-
-See the example below showing a Destination with `Ready` condition.
-
-```
-$ kubectl describe destinations.platform.kratix.io worker-1
-Name:         worker-1
-...
-Status:
-  Conditions:
-    Last Transition Time:  2025-03-04T15:26:21Z
-    Message:               Test documents written to State Store
-    Reason:                TestDocumentsWritten
-    Status:                True
-    Type:                  Ready
-```
-
-:::info
-
-The test documents include `dependencies/kratix-canary-namespace.yaml` and `resources/kratix-canary-configmap.yaml`. When
-the `Ready` condition status is `True` and the target is a Kubernetes cluster set up to reconcile on the Destination, you
-will see a `kratix-worker-system` namespace and a `kratix-info` configmap on the target cluster.
-
-:::

docs/main/03-reference/13-destinations/03-status-events.mdx

@@ -0,0 +1,52 @@
+---
+title: Destination Status and Events
+description: Understand the status conditions and events of a Destination.
+sidebar_label: Status and Events
+id: destination-status-events
+slug: /main/reference/destinations/status-events
+keywords: [destination status, destination events, destination conditions]
+---
+
+Kratix follows the Kubernetes convention of using status conditions and events to report Destination health.
+Destinations are considered ready when Kratix can write test documents to the backing State Store.
+
+## Conditions
+
+Destinations expose a `Ready` condition that reflects the latest health check:
+
+- `TestDocumentsWritten` – test documents were written to the State Store successfully.
+- `ReconciledSuccessfully` – init workloads are disabled, so no test documents are written.
+- `StateStoreWriteFailed` – Kratix could not write the test documents.
+
+The test documents include `dependencies/kratix-canary-namespace.yaml` and `resources/kratix-canary-configmap.yaml`.
+When the `Ready` condition is `True` and a worker cluster is reconciling the Destination, you will see a
+`kratix-worker-system` namespace and a `kratix-info` configmap on the target cluster.
+
+Example:
+
+```
+$ kubectl describe destinations.platform.kratix.io worker-1
+Name:         worker-1
+...
+Status:
+  Conditions:
+    Last Transition Time:  2025-03-04T15:26:21Z
+    Message:               Test documents written to State Store
+    Reason:                TestDocumentsWritten
+    Status:                True
+    Type:                  Ready
+```
+
+## Events
+
+Destinations emit the following events:
+
+- `DestinationReady` (`Normal`) – the Destination is ready. If init workloads are disabled, the message notes that
+  no init workloads were written.
+- `DestinationNotReady` (`Warning`) – writing test documents failed; the message includes the error.
+
+Inspect events with:
+
+```
+kubectl describe destinations.platform.kratix.io <name>
+```

docs/main/03-reference/14-statestore/02-gitstatestore.md

@@ -143,31 +143,3 @@ Require a different method of authentication? Get in touch with us at
 [feedback@syntasso.io](mailto:feedback@syntasso.io?subject=Kratix%20Feedback)
 or [open a GitHub Issue](https://github.com/syntasso/kratix/issues/new).
 :::
-
-## Status
-
-The status of the GitStateStore can be `Ready` or `NotReady` based on Kratix's availability to write to the State Store.
-
-A condition of type `Ready` is also provided to enable waiting for the State Store to be ready.
-
-An example is provided below showing a GitStateStore coming online, including events detailing any status changes.
-
-```
-$ kubectl describe gitstatestores.platform.kratix.io default
-Name:         default
-...
-Status:
-  Conditions:
-    Last Transition Time:  2025-03-05T12:53:12Z
-    Message:               State store is ready
-    Reason:                StateStoreReady
-    Status:                True
-    Type:                  Ready
-  Status:                  Ready
-Events:
-  Type     Reason    Age    From                     Message
-  ----     ------    ----   ----                     -------
-  Warning  NotReady  2m44s  GitStateStoreController  GitStateStore "default" is not ready: Error writing test file: Get "https://172.18.0.2:31333/gitea_admin/kratix/info/refs?service=git-upload-pack": dial tcp 172.18.0.2:31333: connect: connection refused
-  Warning  NotReady  2m32s  GitStateStoreController  GitStateStore "default" is not ready: Error writing test file: repository not found: Repository not found
-  Normal   Ready     2m21s  GitStateStoreController  GitStateStore "default" is ready
-```

docs/main/03-reference/14-statestore/03-bucketstatestore.md

@@ -119,29 +119,3 @@ Require a different method of authentication? Get in touch with us at
 [feedback@syntasso.io](mailto:feedback@syntasso.io?subject=Kratix%20Feedback)
 or [open a GitHub Issue](https://github.com/syntasso/kratix/issues/new).
 :::
-
-## Status
-
-The status of the BucketStateStore can be `Ready` or `NotReady` based on Kratix's availability to write to the State Store.
-
-A [condition](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-conditions) of type `Ready` is also provided to enable waiting for the State Store to be ready.
-
-An example is provided below showing a BucketStateStore coming online, including events detailing any status changes.
-
-```
-$ kubectl describe bucketstatestores.platform.kratix.io default
-Name:         default
-...
-Status:
-  Conditions:
-    Last Transition Time:  2025-03-05T12:52:49Z
-    Message:               State store is ready
-    Reason:                StateStoreReady
-    Status:                True
-    Type:                  Ready
-  Status:                  Ready
-Events:
-  Type    Reason  Age   From                        Message
-  ----    ------  ----  ----                        -------
-  Normal  Ready   11m   BucketStateStoreController  BucketStateStore "default" is ready
-```

docs/main/03-reference/14-statestore/04-status-events.mdx

@@ -0,0 +1,74 @@
+---
+title: StateStore Status and Events
+description: Understand the status conditions and events for GitStateStore and BucketStateStore.
+sidebar_label: Status and Events
+id: statestore-status-events
+slug: /main/reference/statestore/status-events
+keywords: [statestore status, statestore events, gitstatestore status, bucketstatestore status]
+---
+
+This page applies to both `GitStateStore` and `BucketStateStore`. The status conditions and events are the same for
+both types; examples below show each resource kind.
+
+## Status
+
+The StateStore `status.status` field can be `Ready` or `NotReady`, depending on whether Kratix can write to the
+backing storage.
+
+A `Ready` condition is also provided so you can wait for State Stores to become usable.
+
+When a State Store is not ready, the condition message includes the underlying failure (for example, errors
+initialising the writer or validating permissions).
+
+## Events
+
+State Stores emit these events:
+
+- `Ready` (`Normal`) – the State Store is ready to use.
+- `NotReady` (`Warning`) – Kratix cannot write to the State Store; the message includes the failure.
+- `InvalidCredentials` (`Warning`, GitStateStore only) – authentication succeeded only after trimming trailing
+  whitespace in the Secret; update the Secret to remove it.
+
+## Examples
+
+GitStateStore:
+
+```
+$ kubectl describe gitstatestores.platform.kratix.io default
+Name:         default
+...
+Status:
+  Conditions:
+    Last Transition Time:  2025-03-05T12:53:12Z
+    Message:               State store is ready
+    Reason:                StateStoreReady
+    Status:                True
+    Type:                  Ready
+  Status:                  Ready
+Events:
+  Type     Reason    Age    From                     Message
+  ----     ------    ----   ----                     -------
+  Warning  NotReady  2m44s  GitStateStoreController  GitStateStore "default" is not ready: Error writing test file: Get "https://172.18.0.2:31333/gitea_admin/kratix/info/refs?service=git-upload-pack": dial tcp 172.18.0.2:31333: connect: connection refused
+  Warning  NotReady  2m32s  GitStateStoreController  GitStateStore "default" is not ready: Error writing test file: repository not found: Repository not found
+  Normal   Ready     2m21s  GitStateStoreController  GitStateStore "default" is ready
+```
+
+BucketStateStore:
+
+```
+$ kubectl describe bucketstatestores.platform.kratix.io default
+Name:         default
+...
+Status:
+  Conditions:
+    Last Transition Time:  2025-03-05T12:52:49Z
+    Message:               State store is ready
+    Reason:                StateStoreReady
+    Status:                True
+    Type:                  Ready
+  Status:                  Ready
+Events:
+  Type    Reason  Age   From                        Message
+  ----    ------  ----  ----                        -------
+  Normal  Ready   11m   BucketStateStoreController  BucketStateStore "default" is ready
+```

docs/main/03-reference/15-resources/06-status-events.mdx

@@ -1,6 +1,8 @@
 ---
 title: Resource Status and Events
 description: Learn about the conditions and events attached to Resource requests.
+sidebar_label: Status and Events
+keywords: [resource status, resource events, resource conditions, resource lifecycle]
 id: resource-status-events
 slug: /main/reference/resources/resource-status-events
 ---

docs/main/05-platform-concepts/04-auth/_category_.json

@@ -1,8 +1,8 @@
 {
-  "label": "Authentication and Authorization",
+  "label": "Identity and Access",
   "position": 8,
   "link": {
     "type": "generated-index",
-    "description": "How Kratix relies on Kubernetes authentication and authorization."
+    "description": "How access to Kratix is authenticated and authorized."
   }
 }

docs/main/05-platform-concepts/05-secrets.mdx

@@ -1,8 +1,11 @@
 ---
-title: Secrets
-description: How Kratix workflows access secrets via the Kubernetes model.
+title: Secret management
+description: How Kratix workflows read and write secrets via the Kubernetes model.
+sidebar_label: Secret management
 ---
 
+## Reading secrets
+
 Kratix workflows run in Kubernetes and use the native `Secret` model. If a
 workflow needs credentials or tokens, create a Kubernetes `Secret` and reference
 it as you would for any other Pod. There is no Kratix-specific secret store;
@@ -12,14 +15,17 @@ See the Kubernetes docs for the core concepts and usage:
 - [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/)
 - [Using Secrets](https://kubernetes.io/docs/concepts/configuration/secret/#using-a-secret)
 
-## Integrating external secret stores
+## Writing and syncing secrets
+
+Kratix does not define how secrets are authored or stored; it relies on whatever
+secret management workflow you already use for Kubernetes. Common approaches
+include:
 
-There are many ways to source secrets from external systems and sync them into Kubernetes.
-Common approaches include:
 - [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) for storing encrypted secrets in Git.
 - [External Secrets Operator](https://external-secrets.io/latest/) to pull from cloud secret managers.
 - [HashiCorp Vault](https://www.vaultproject.io/) via a Kubernetes auth method and sync controller.
 
-Once those tools materialize a Kubernetes `Secret`, Kratix workflows can use it
-as-is. This keeps Kratix aligned with the Kubernetes security model and lets
-you pick the integration that fits your platform.
+These tools typically reconcile into Kubernetes `Secret` objects, which makes
+them available to Kratix workflows. In GitOps workflows, the encrypted or
+generated secret manifests live in Git, and your controller applies the
+decrypted or synced secrets to the cluster.

docs/main/05-platform-concepts/06-multi-tenancy.mdx

@@ -1,13 +1,26 @@
 ---
 title: Multi-tenancy
-description: Use Kubernetes namespaces to isolate Kratix resource requests.
+description: Multi-tenancy for Kratix using standard Kubernetes isolation models.
 ---
 
-Kratix relies on Kubernetes namespaces for isolation. Every Promise-defined
-request kind (for example `Database` or `App`) is namespaced, so each request
-belongs to a namespace. This makes namespaces a natural boundary for teams,
-individuals, environments, or organisations. You can combine namespaces with
-Kubernetes features like ResourceQuotas to enforce limits and isolation.
+Kratix does not introduce a custom multi-tenancy layer. Instead, it fits into
+the same Kubernetes isolation patterns you already use. Depending on your
+security and operational requirements, you can isolate tenants with separate
+clusters, node pools, or namespaces.
+
+Separate clusters are often used to reduce blast radius or to meet DR/HA or
+regulatory requirements. Node pools help ensure workloads and workflows run on
+the right type of compute (for example, dedicated, compliant, or GPU nodes).
+Namespaces provide a lightweight boundary for teams. For example, an
+organisation might allocate `backend` and `frontend` namespaces so each team can
+manage their own Promise requests independently from the same Platform.
+
+Kratix Promises can create namespaced CRDs and therefore resource requests 
+(for example a Kratix Promise for `Database` or `App`) will be namespaced. 
+This makes namespaces a natural boundary for teams, environments, or 
+organisations. You can then combine namespaces with Kubernetes features 
+like ResourceQuotas and NetworkPolicies to enforce limits and isolation per
+team or other organisational division.
 
 Promises themselves are cluster-scoped and are not namespaced. That means a
 Promise is visible across the cluster once installed. Use Kubernetes RBAC to

docs/main/05-platform-concepts/07-private-image-registries.mdx

@@ -37,3 +37,34 @@ spec:
           imagePullSecrets:
           - name: registry-creds
 ```
+
+## Namespace scope and syncing
+
+Image pull secrets are namespace-scoped, so each namespace that runs workflows
+needs access to the right `Secret`. In practice, this often means copying or
+syncing the same credentials into multiple namespaces. A common approach is to
+use a secrets operator that can source credentials from a central store (like a
+cloud secret manager or Vault) and fan them out into the namespaces that need
+them. This keeps the source of truth centralized while still meeting the
+namespace scoping rules.
+
+## Cluster-wide options
+
+Some clusters configure registry access at the node level so workloads do not
+need per-namespace secrets. For example, you can use kubelet image credential
+providers to supply credentials based on the image registry, or configure
+registry mirrors so nodes pull from a trusted internal endpoint. This can
+simplify per-namespace management, but it also broadens who can use those
+credentials: any workload scheduled on the node can pull from the registry. Use
+this approach only when that risk is acceptable for your environment. See the
+Kubernetes docs on
+[image credential providers](https://kubernetes.io/docs/tasks/administer-cluster/kubelet-credential-provider/)
+for an overview.
+
+## Air-gapped environments
+
+If you are running in an air-gapped environment or need to mirror registries,
+the SKE [air-gapped installation](/ske/installing-ske/air-gapped) guide walks
+you through the setup. SKE handles much of the heavy lifting around registry
+mirrors and offline artifacts, so you can focus on your platform workflows
+instead of the plumbing.

docs/main/05-platform-concepts/08-api.mdx

@@ -21,6 +21,23 @@ When you update the Promise API section, you are changing the CRD that Kratix
 manages. That changes the request surface available to users and the schema
 validation Kubernetes enforces.
 
+## Making requests to CRDs
+
+Kubernetes is an API server, so all Promise requests are API calls. You can
+choose the medium that suits your workflow:
+
+- `kubectl` for direct creation and updates (for example,
+  `kubectl apply -f database.yaml`).
+- The Kubernetes API server over HTTP/JSON using client libraries or direct
+  REST calls. `kubectl` is just a client to that same API server.
+- GitOps workflows where you commit YAML to a repo watched by Flux, Argo CD, or
+  another GitOps controller. The controller applies the CRD instances to the
+  cluster on your behalf.
+
+All of these approaches also power developer portals such as Backstage, which
+ultimately create the same CRDs. For a production-ready portal integration, see
+[Kratix and Backstage](/ske/integrations/backstage/intro).
+
 ## CRD versions and Promise versions
 
 CRDs can define multiple API versions under a single kind, allowing you to

docs/main/06-learn-more/01-how-kratix-complements/01-how-kratix-complements.md → docs/main/06-learn-more/01-how-kratix-complements.md

@@ -2,6 +2,7 @@
 description: Learn more about how Kratix complements other tools in the platform space
 title: How Kratix Complements
 id: intro
+slug: /main/how-kratix-complements
 ---
 
 <img
@@ -16,6 +17,6 @@ Rather than directly comparing Kratix to technologies in our space, we prefer to
 
 Read on to understand how Kratix works with:
 
-- [Terraform](./how-kratix-complements/terraform)
-- [Crossplane](./how-kratix-complements/crossplane)
-- [Backstage](./how-kratix-complements/backstage)
+- [Terraform](/main/how-kratix-complements/terraform)
+- [Crossplane](/main/how-kratix-complements/crossplane)
+- [Backstage](/main/how-kratix-complements/backstage)