docs(dev): clean up the getting-started guides

content/docs/getting-started/create-component-version.md

@@ -1,5 +1,5 @@
 ---
-title: "Create Component Versions"
+title: "Create and Examine Component Versions"
 url: "/docs/getting-started/create-component-version/"
 description: "Learn how to create and store component versions using the OCM CLI."
 icon: "📦"
@@ -9,7 +9,7 @@ toc: true
 
 ## How It Works
 
-Component versions are created using a `component-constructor.yaml` file, which is a description file that contains one or multiple components. The file describes the components and their artifacts - resources and sources, metadata in form of labels and references to other components.
+Component versions are created using a `component-constructor.yaml` file, which is a description file that contains one or multiple components. The file describes the components and their artifacts – resources and sources, metadata in form of labels and references to other components.
 
 Component versions are locally stored in archives using the [Common Transfer Format (CTF)](https://github.com/open-component-model/ocm-spec/blob/main/doc/04-extensions/03-storage-backends/ctf.md). A CTF archive may contain any number of component versions and is used to transfer components to and between component repositories.
 
@@ -41,7 +41,13 @@ Quickly create a simple test file with some content in:
 echo "My first local Resource for an OCM component" > my-local-resource.txt
 ```
 
-Now, create a file named `component-constructor.yaml`. This file will define all elements of your component. In our example, the component contains a local file and a remote Docker image as resources.
+Now, create a file named `component-constructor.yaml`:
+
+```shell
+touch component-constructor.yaml
+```
+
+The `component-constructor.yaml` file will define all elements of your component. In our example, the component contains a local file and a remote Docker image as resources. 
 
 To create the example component, save the following YAML configuration to `component-constructor.yaml`:
 
@@ -67,10 +73,10 @@ components:
       version: 1.0.0
       access:
         type: ociArtifact
-        imageReference: ghcr.io/stefanprodan/podinfo:6.9.1
+        imageReference: ghcr.io/stefanprodan/podinfo:6.9.4
 ```
 
-You can use our public configuration schema to validate the configuration. The schema is available at `https://ocm.software/schemas/configuration-schema.yaml` and can be used in your editor to validate the configuration (e.g., in Visual Studio Code).
+You can use our public configuration schema to validate the configuration. The schema is available at [https://ocm.software/schemas/configuration-schema.yaml](https://ocm.software/schemas/configuration-schema.yaml) and can be used in your editor to validate the configuration (e.g., in Visual Studio Code).
 
 Component versions need to have at least a `name`, `version` and `provider` attribute. All other attributes are optional. Check out an [example component descriptor]({{< relref "component-descriptor-example.md" >}}) or the [OCM Specification](https://github.com/open-component-model/ocm-spec/blob/main/README.md) to see all available attributes. 
 
@@ -107,6 +113,8 @@ If you want to specify a different constructor file name or CTF archive name, yo
 ocm add cv --repository /path/to/my-own-ctf -c /path/to/my-component-constructor.yaml
 ```
 
+If the component version was created successfully, you will see the following output:
+
 ```shell
 ...
 component github.com/acme.org/helloworld/1.0.0 constructed ... done! [1 component version in 482ms]
@@ -245,7 +253,7 @@ The other elements listed as `layers` describe the blobs for the local resources
 
 </details>
 
-## View Component Versions
+## Examine Component Versions
 
 To list all component versions of a component stored in an OCM repository or CTF archive (which is technically also an OCM repository), you can use the [`ocm get component-version`]({{< relref "ocm_get_component-version.md" >}}) command. Only specify the component name and skip the version:
 
@@ -269,6 +277,8 @@ ocm get cv /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0
 
 In this example, the output remains the same because the component has only one component version.
 
+To get the component descriptor of that component version, use the output format option `-o yaml`:
+
 ```shell
 ocm get cv /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0 -o yaml
 ```

content/docs/getting-started/deploy-helm-chart.md

@@ -6,12 +6,13 @@ weight: 33
 toc: true
 ---
 
-This guide demonstrates how to deploy a Helm chart from an OCM component version using OCM controllers, kro, and FluxCD.
-It is a rather basic example, in which it is assumed that a developer created an application, packaged it as a Helm
+This guide demonstrates how to deploy a Helm chart from an OCM component version using OCM controllers, [kro](https://kro.run/), and [Flux](https://fluxcd.io/).
+
+For the following example, it is assumed that a developer created an application, packaged it as a Helm
 chart, and publishes it as OCM component version in an OCI registry. Then, an operator who wants to deploy the
 application via Helm chart in a Kubernetes cluster, creates a `ResourceGraphDefinition` with resources that point to
-this OCM component version. Using CEL expressions inside the `ResourceGraphDefinition`, the information about the
-resource location will be passed to FluxCD, which will then configure the Helm chart and deploy it into the Kubernetes
+the OCM component version. Using CEL expressions inside the `ResourceGraphDefinition`, the information about the
+resource location will be passed to Flux, which will then configure the Helm chart and deploy it into the Kubernetes
 cluster.
 
 ## Prerequisites

content/docs/getting-started/download-resources-from-component-versions.md

@@ -26,7 +26,7 @@ ocm download resource ghcr.io/open-component-model/ocm//ocm.software/toi/demo/he
 time=2025-08-14T13:03:54.372+02:00 level=INFO msg="resource downloaded successfully" output=helmchart.tgz
 ```
 
-Because it is stored as OCI artifact in an OCI registry, the filesystem format used for OCI artifacts is the blob format.
+Because it is stored as an OCI artifact in an OCI registry, the filesystem format used for OCI artifacts is the blob format.
 
 <details><summary>What happened?</summary>
 
@@ -72,7 +72,7 @@ jq . index.json
 
 {{<callout context="caution" title="Under Construction">}}Transformers are currently in development. We'll extend the below section once they are ready to be used. Until then, you can check out the [Transformer ADR](https://github.com/open-component-model/open-component-model/blob/main/docs/adr/0005_transformation.md){{</callout>}}
 
-To use a format more suitable for the content technology, you can use the `--transformer` to specify a transformer. The transformer will take care that the file will be saved using its correct media type, e.g. a Helm chart will be saved as a `.tgz` file which on extraction will show the complete chart.
+To use a format more suitable for the content technology, you can use the `--transformer` flag to specify a transformer. The transformer will take care that the file is saved using its correct media type. For example, a Helm chart will be saved as a `.tgz` file, which on extraction will show the complete chart.
 
 ```shell
 ocm download resource ghcr.io/open-component-model/ocm//ocm.software/toi/demo/helmdemo:0.12.0 chart --identity name=chart --output helmchart.tgz --transformer helm

content/docs/getting-started/setup.md

@@ -21,7 +21,7 @@ This document describes how to set up a local environment for running examples f
 You don't need to run kind if you are using a remote Kubernetes cluster you have access to. If so, you can skip this.
 {{</callout>}}
 
-To create a local kind cluster run the following command:
+Create a local kind cluster:
 
 ```bash
 kind create cluster
@@ -32,7 +32,7 @@ kind create cluster
 Please follow [the official installation guides for kro](https://kro.run/docs/getting-started/Installation). You might
 need [helm](https://helm.sh/docs/intro/install/) to install kro.
 
-If kro is installed correctly, you should see some similar output when running the following command:
+Verify the installation:
 
 ```bash
 kubectl get pods --all-namespaces
@@ -47,19 +47,20 @@ kro                  kro-86d5b5b5bd-6gmvr                         1/1     Runnin
 
 ## Install a Deployer
 
-Currently, we created our examples and getting-started guides using [FluxCD](https://fluxcd.io/) as deployer.
+Currently, we created our examples and getting-started guides using [Flux](https://fluxcd.io/) as deployer.
 But, in theory, you could use any other deployer that is able to apply a deployable resource to a Kubernetes cluster,
-for instance [ArgoCD](https://argo-cd.readthedocs.io/en/stable/).
+for instance [Argo CD](https://argo-cd.readthedocs.io/en/stable/).
 
-To install FluxCD, please follow the official [installation guide](https://fluxcd.io/docs/installation/). After you
-installed the CLI tool, you can run the following command to install the FluxCD controllers:
+To install the Flux CLI, please follow the official [installation guide](https://fluxcd.io/docs/installation/). After you have
+installed the CLI tool, you can proceed with the steps below.
+
+Install the Flux controllers:
 
 ```bash
 flux install
 ```
 
-If the FluxCD controllers are installed correctly, you should see some similar output when running the following
-command:
+Verify the installation:
 
 ```bash
 kubectl get pods --all-namespaces
@@ -79,21 +80,21 @@ kro                  kro-86d5b5b5bd-6gmvr                         1/1     Runnin
 
 ## Install the OCM Controllers
 
-To install the OCM controllers, you can use one of the following commands:
+Install the OCM controllers with one of the following commands:
 
 ```bash
-# In the open-component-model repository, folder kubernetes/controller
+# In the open-component-model repository
+cd kubernetes/controller
 task deploy
 ```
 
 or
 
 ```bash
-kubectl apply -k https://github.com/open-component-model/open-component-model/kubernetes/controller/config/default?ref=main
+kubectl apply -k "https://github.com/open-component-model/open-component-model/kubernetes/controller/config/default?ref=main"
 ```
 
-If the OCM controllers are installed correctly, you should see some similar output when running the
-following command:
+Verify the installation:
 
 ```bash
 kubectl get pods --all-namespaces
@@ -123,7 +124,7 @@ need access to a registry. You can either choose a public registry like [ghcr.io
 If you choose to deploy a registry into your Kubernetes cluster, you have to make sure it is accessible from outside
 the cluster (for `ocm transfer` to work) and inside the cluster (for the OCM controllers to work).
 
-We **strongly** recommend to use a registry that is publicly accessible, like [ghcr.io][ghcr.io].
+We **strongly** recommend to use a registry that is publicly accessible, like [ghcr.io](https://docs.github.com/en/packages/learn-github-packages/introduction-to-github-packages).
 (Deploying your own registry requires a lot of additional configuration. Especially, if you want to try out the
 localization example, you will need to configure a registry that is accessible with the same address from your
 CLI, kubelet, and inside the cluster.)
@@ -132,7 +133,7 @@ CLI, kubelet, and inside the cluster.)
 ---
 
 If you completed all of the above steps, you are ready to go. You can now start with the [Deploy a Helm Chart]({{< relref "docs/getting-started/deploy-helm-chart.md" >}}) guide or play around with the examples in the
-[`examples/`](https://github.com/open-component-model/open-component-model/tree/main/kubernetes/controller/examples) directory.
+[`examples/` directory on GitHub](https://github.com/open-component-model/open-component-model/tree/main/kubernetes/controller/examples) directory.
 
 [ghcr.io]: https://docs.github.com/en/packages/learn-github-packages/introduction-to-github-packages
 [registry]: https://hub.docker.com/_/registry

content/docs/getting-started/sign-component-version.md

@@ -11,10 +11,9 @@ Signing ensures the **authenticity** and **integrity** of component versions in
 
 ## Prerequisites
 
-- You have a key pair (private + public key).
-  - Don't have a key pair yet? Follow our guide: [Key Pair Generation]({{< relref "signing-and-verification.md#key-pair-generation" >}}).
-- You have the OCM CLI installed.
-  - To install the OCM CLI, follow our guide: [Install and Configure the OCM CLI]({{< relref "ocm-cli-installation" >}}).
+- [Install the OCM CLI]({{< relref "ocm-cli-installation" >}}).
+- Get a key pair (private + public key). Don't have a key pair yet? Follow our guide: [Key Pair Generation]({{< relref "signing-and-verification.md#key-pair-generation" >}}).
+- To follow the examples, you need the component version from the  guide [Create and Examine Component Versions]({{< relref "create-component-version.md" >}}).
 
 ## Minimal .ocmconfig for Signing
 
@@ -32,8 +31,9 @@ configurations:
         credentials:
           - type: Credentials/v1
             properties:
-              private_key_pem_file: ./keys/private.key
+              private_key_pem_file: "<path-to-your-private-key>"
 ```
+Replace `<path-to-your-private-key>` with the corresponding path. If you followed the [Key Pair Generation]({{< relref "signing-and-verification.md#key-pair-generation" >}}) guide, you can use the path `~/.ocm/keys/dev/private.pem`.
 
 The `identity` attributes define the consumer type for RSA signing:
 
@@ -54,7 +54,7 @@ Let's sign the component we created earlier in the [Create a Component Version](
 assuming you used the default name for the CTF:
 
 ```bash
-ocm sign cv transport-archive//github.com/acme.org/helloworld:1.0.0 --config <path to your .ocmconfig>
+ocm sign cv /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0 --config <path-to-your-.ocmconfig>
 ```
 
 This command signs the specified component version and stores the signature in the repository:
@@ -74,7 +74,7 @@ signature:
 When looking at the component descriptor, we can also see the new signature entry at the end of the descriptor:
 
 ```bash
-ocm get cv transport-archive//github.com/acme.org/helloworld:1.0.0 -oyaml
+ocm get cv /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0 -oyaml
 ```
 
 ```yaml
@@ -129,7 +129,7 @@ In case you want to replace an existing signature, use the `--force` flag.
 Otherwise you will get an error like `Error: signature "default" already exists`.
 
 ```bash
-ocm sign cv transport-archive//github.com/acme.org/helloworld:1.0.0 --force
+ocm sign cv /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0 --force
 ```
 
 > ⚠️ Only overwrite signatures if you are sure no other process relies on the existing one.
@@ -149,25 +149,30 @@ configurations:
         credentials:
           - type: Credentials/v1
             properties:
-              private_key_pem_file: ~/.ocm/keys/dev/private.key
+              private_key_pem_file: "<path-to-the-first-private-key>"
 
       - identity:
           type: RSA/v1alpha1
           signature: prod
         credentials:
           - type: Credentials/v1
             properties:
-              private_key_pem_file: ~/.ocm/keys/prod/private.key
+              private_key_pem_file: "<path-to-the-second-private-key>"
 ```
 
+Replace `<path-to-the-first-private-key>` and `<path-to-the-second-private-key>` with the corresponding paths. If you followed the [Key Pair Generation]({{< relref "signing-and-verification.md#key-pair-generation" >}}) guide, you can use the following paths:
+
+- `~/.ocm/keys/dev/private.pem` for the `dev` signature
+- `~/.ocm/keys/prod/private.pem` for the `prod` signature
+
 Then sign with the appropriate signature name:
 
 ```bash
 # Sign for development
-ocm sign cv --signature dev transport-archive//github.com/acme.org/helloworld:1.0.0
+ocm sign cv --signature dev /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0
 
 # Sign for production
-ocm sign cv --signature prod transport-archive//github.com/acme.org/helloworld:1.0.0
+ocm sign cv --signature prod /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0
 ```
 
 See the [Multi-Environment Configuration]({{< relref "signing-and-verification.md#multi-environment-configuration" >}}) section for complete examples.

content/docs/getting-started/verify-component-version.md

@@ -11,10 +11,8 @@ Verifying a component version ensures that a signature was created by a trusted
 
 ## Prerequisites
 
-- You have a public key corresponding to the signature. 
-  - Don't have a key pair yet? Follow our guide: [Key Pair Generation]({{< relref "signing-and-verification.md#key-pair-generation" >}}).
-- You have the OCM CLI installed.
-  - To install the OCM CLI, follow our guide: [Install and Configure the OCM CLI]({{< relref "ocm-cli-installation" >}}).
+- [Install the OCM CLI]({{< relref "ocm-cli-installation" >}}).
+- You need a signed component version and the public key for the signature. The following examples use the signed component version from the [Sign Component Versions]({{< relref "sign-component-version.md" >}}) guide.
 
 ## Minimal .ocmconfig for Verification
 
@@ -35,9 +33,11 @@ configurations:
         credentials:
           - type: Credentials/v1
             properties:
-              public_key_pem_file: ./keys/public.pem
+              public_key_pem_file: "<path-to-your-public-key>"
 ```
 
+Replace `<path-to-your-public-key>` with the corresponding path. If you followed the [Key Pair Generation]({{< relref "signing-and-verification.md#key-pair-generation" >}}) guide, you can use the path `~/.ocm/keys/dev/public.pem`.
+
 The `identity` attributes define the consumer type for RSA verification:
 
 - `type` must be `RSA/v1alpha1` for RSA-based verification.
@@ -98,17 +98,22 @@ configurations:
         credentials:
           - type: Credentials/v1
             properties:
-              public_key_pem_file: ~/.ocm/keys/dev/public.pem
+              public_key_pem_file: "<path-to-the-first-public-key>"
 
       - identity:
           type: RSA/v1alpha1
           signature: prod
         credentials:
           - type: Credentials/v1
             properties:
-              public_key_pem_file: ~/.ocm/keys/prod/cert-chain.pem
+              public_key_pem_file: "<path-to-the-first-public-key>"
 ```
 
+Replace `<path-to-the-first-public-key>` and `<path-to-the-second-public-key>` with the corresponding paths. If you followed the [Key Pair Generation]({{< relref "signing-and-verification.md#key-pair-generation" >}}) guide, you can use the following paths:
+
+- `~/.ocm/keys/dev/public.pem` for the `dev` signature
+- `~/.ocm/keys/prod/cert-chain.pem` for the `prod` signature
+
 Then verify the appropriate signature:
 
 ```bash