docs: move "Components" to subpage and other minor fixes

docs/docs/architecture/attestation.md

@@ -5,21 +5,23 @@ The following gives a detailed description of Contrast's attestation architectur
 At the end of this document, we included an [FAQ](#frequently-asked-questions-about-attestation-in-contrast) that answers the most common questions regarding attestation in hindsight of the [security benefits](../basics/security-benefits.md).
 
 ## Attestation architecture
+
 Contrast integrates with the RATS architecture, leveraging their definition of roles and processes including *Attesters*, *Verifiers*, and *Relying Parties*.
 
 ![Conceptual attestation architecture](../_media/attestation-rats-architecture.svg)
 
 Figure 1: Conceptual attestation architecture. Taken from [RFC 9334](https://www.rfc-editor.org/rfc/rfc9334.html#figure-1).
 
-
 - **Attester**: Assigned to entities that are responsible for creating *Evidence* which is then sent to a *Verifier*.
 - **Verifier**: These entities utilize the *Evidence*, *Reference Values*, and *Endorsements*. They assess the trustworthiness of the *Attester* by applying an *Appraisal Policy* for *Evidence*. Following this assessment, *Verifiers* generate *Attestation Results* for use by *Relying Parties*. The *Appraisal Policy* for *Evidence* may be provided by the *Verifier Owner*, programmed into the *Verifier*, or acquired through other means.
 - **Relying Party**: Assigned to entities that utilize *Attestation Results*, applying their own appraisal policies to make specific decisions, such as authorization decisions. This process is referred to as the "appraisal of Attestation Results." The *Appraisal Policy* for *Attestation Results* might be sourced from the *Relying Party Owner*, configured by the owner, embedded in the *Relying Party*, or obtained through other protocols or mechanisms.
 
 ## Components of Contrast's attestation
+
 The key components involved in the attestation process of Contrast are detailed below:
 
 ### Attester: Application Pods
+
 This includes all Pods of the Contrast deployment that run inside Confidential Containers and generate cryptographic evidence reflecting their current configuration and state.
 Their evidence is rooted in the [hardware measurements](../basics/confidential-containers.md) from the CPU and their [confidential VM environment](../components/runtime.md).
 The details of this evidence are given below in the section on [evidence generation and appraisal](#evidence-generation-and-appraisal).
@@ -34,7 +36,7 @@ The image is in [IGVM format](https://github.com/microsoft/igvm), encapsulating
 The kernel cmdline contains the root hash for [dm-verity](https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/verity.html) that ensures the integrity of the root filesystem.
 The root filesystem contains all  components of the container's runtime environment including the [guest agent](../basics/confidential-containers.md#kata-containers) (C).
 
-In the userland, the guest agent takes care of enforcing the [runtime policy](../components/index.md#runtime-policies) of the pod.
+In the userland, the guest agent takes care of enforcing the [runtime policy](../components/overview.md#runtime-policies) of the pod.
 While the policy is passed in during the initialization procedure via the host, the evidence for the runtime policy is part of the CPU measurements.
 During the [deployment](../deployment.md#generate-policy-annotations-and-manifest) the policy is annotated to the Kubernetes Pod resources.
 On AMD SEV-SNP the hash of the policy is then added to the attestation report via the `HOSTDATA` field by the hypervisor.
@@ -43,7 +45,8 @@ When provided with the policy from the Kata host, the guest agent verifies that
 In summary a Pod's evidence is the attestation report of the CPU that provides evidence for runtime environment and the runtime policy.
 
 ### Verifier: Coordinator and CLI
-The [Coordinator](../components/index.md#the-coordinator) acts as a verifier within the Contrast deployment, configured with a [Manifest](../components/index.md#the-manifest) that defines the reference values and serves as an appraisal policy for all pods in the deployment.
+
+The [Coordinator](../components/overview.md#the-coordinator) acts as a verifier within the Contrast deployment, configured with a [Manifest](../components/overview.md#the-manifest) that defines the reference values and serves as an appraisal policy for all pods in the deployment.
 It also pulls endorsements from hardware vendors to verify the hardware claims.
 The Coordinator operates within the cluster as a confidential container and provides similar evidence as any other Pod when it acts as an attester.
 In RATS terminology, the Coordinator's dual role is defined as a lead attester in a composite device which spans the entire deployment: Coordinator and the workload pods.
@@ -53,35 +56,36 @@ It collects evidence from other attesters and conveys it to a verifier, generati
 
 Figure 3: Contrast deployment as a composite device. Based on the composite device in [RFC 9334](https://www.rfc-editor.org/rfc/rfc9334.html#figure-4).
 
-The [CLI](../components/index.md#the-cli-command-line-interface) serves as the verifier for the Coordinator and the entire Contrast deployment, containing the reference values for the Coordinator and the endorsements from hardware vendors.
+The [CLI](../components/overview.md#the-cli-command-line-interface) serves as the verifier for the Coordinator and the entire Contrast deployment, containing the reference values for the Coordinator and the endorsements from hardware vendors.
 These reference values are built into the CLI during our release process and can be reproduced offline via reproducible builds.
 
 ### Relying Party: Data owner
+
 A relying party in the Contrast scenario could be, for example, the [data owner](../basics/security-benefits.md) that interacts with the application.
 The relying party can use the CLI to obtain the attestation results and Contrast's [CA certificates](certificates.md) bound to these results.
 The CA certificates can then be used by the relying party to authenticate the application, for example through TLS connections.
 
-
 ## Evidence generation and appraisal
 
 ### Evidence types and formats
+
 In Contrast, attestation evidence revolves around a hardware-generated attestation report, which contains several critical pieces of information:
 
 - **The hardware attestation report**: This report includes details such as the chip identifier, platform information, microcode versions, and comprehensive guest measurements. The entire report is signed by the CPU's private key, ensuring the authenticity and integrity of the data provided.
 - **The launch measurements**: Included within the hardware attestation report, this is a digest generated by the CPU that represents a hash of all initial guest memory pages. This includes essential components like the kernel, initramfs, and the kernel command line. Notably, it incorporates the root filesystem's dm-verity root hash, verifying the integrity of the root filesystem.
 - **The runtime policy hash**: Also part of the hardware attestation report, this field contains the hash of the Rego policy which dictates all expected API commands and their values from the host to the Kata guest agent. It encompasses crucial settings such as dm-verity hashes for the container image layers, environment variables, and mount points.
 
 ### Appraisal policies for evidence
+
 The appraisal of this evidence in Contrast is governed by two main components:
 
 - **The Manifest**: A JSON file used by the Coordinator to align with reference values. It sets the expectations for runtime policy hashes for each pod and includes what should be reported in the hardware attestation report for each component of the deployment.
 - **The CLI's appraisal policy**: This policy encompasses expected values of the Coordinator’s guest measurements and its runtime policy. It's embedded into the CLI during the build process and ensures that any discrepancy between the built-in values and those reported by the hardware attestation can be identified and addressed. The integrity of this policy is safeguardable through reproducible builds, allowing verification against the source code reference.
 
-
-
 ## Frequently asked questions about attestation in Contrast
 
 ### What's the purpose of remote attestation in Contrast?
+
 Remote attestation in Contrast ensures that software runs within a secure, isolated confidential computing environment.
 This process certifies that the memory is encrypted and confirms the integrity and authenticity of the software running within the deployment.
 By validating the runtime environment and the policies enforced on it, Contrast ensures that the system operates in a trustworthy state and hasn't been tampered with.

docs/docs/architecture/observability.md

@@ -26,7 +26,7 @@ manifest](../deployment#set-the-manifest) and [verifying the
 Coordinator](../deployment#verify-the-coordinator) respectively.
 
 The `meshapi.MeshAPI` service records metrics for the method `NewMeshCert`, which
-gets called by the [Initializer](../components#the-initializer) when starting a
+gets called by the [Initializer](../components/overview.md#the-initializer) when starting a
 new workload. Attestation failures from workloads to the Coordinator can be
 tracked with the counter `contrast_meshapi_attestation_failures`.
 

docs/docs/basics/features.md

@@ -8,7 +8,7 @@ From an operational perspective, Contrast provides the following key features:
 
 * **Managed Kubernetes compatibility**: Initially compatible with Azure Kubernetes Service (AKS), Contrast is designed to support additional platforms such as AWS EKS and Google Cloud GKE as they begin to accommodate confidential containers.
 
-* **Lightweight installation**: Contrast can be integrated as a [day-2 operation](../deployment.md) within existing clusters, adding minimal [components](../architecture) to your setup. This facilitates straightforward deployments using your existing YAML configurations, Helm charts, or Kustomization, enabling native Kubernetes orchestration of your applications.
+* **Lightweight installation**: Contrast can be integrated as a [day-2 operation](../deployment.md) within existing clusters, adding minimal [components](../components/overview.md) to your setup. This facilitates straightforward deployments using your existing YAML configurations, Helm charts, or Kustomization, enabling native Kubernetes orchestration of your applications.
 
 * **Remote attestation**: Contrast generates a concise attestation statement that verifies the identity, authenticity, and integrity of your deployment both internally and to external parties. This architecture ensures that updates or scaling of the application don't compromise the attestation’s validity.