Refactor docs structure

CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-06-15
+
+### Added
+
+- Introduced top-level documentation sections for:
+    - `client`
+    - `server`
+    - `support`
+    - `release-notes`
+    - `contribute`
+- Added release notes pages for client and server documentation.
+- Added contribution and AI usage policy guidance in `docs/contribute/index.md`.
+
+### Changed
+
+- Refactored the documentation structure from legacy `livepatch*` paths to `client/` and `server/` spaces.
+- Introduced a third-level Diátaxis-style organization in key areas (for example: `architecture`, `security`, `troubleshooting`, `configuration`, `installation`, `operations`, and `patch-management`).
+- Standardized MyST heading IDs to the new path-based naming convention and updated in-page/cross-page anchor usages accordingly.
+- Normalized toctree entries to explicit titled form (for example: `Installation <installation/index.md>`).
+
+### Fixed
+
+- Expanded `docs/redirects.txt` to preserve old URLs across the restructure, including legacy `livepatch/`, `livepatch_on_prem/`, and `livepatch_server_on_public_clouds/` paths.
+- Added missing redirects from moved client explanation pages to `support/` pages.
+- Removed shell prompt prefixes (`$`) from fenced command examples for consistency and copy/paste usability.
+
 ## [0.2.0] - 2026-06-11
 
 ### Added

README.md

@@ -9,8 +9,7 @@ Livepatch shrinks the exploit window for critical and high severity Linux kernel
 Documentation for:
 
 - Livepatch Client
-- Livepatch On-Prem Server
-- Livepatch Server on public clouds
+- Livepatch Server
 
 ## Useful links
 

docs/livepatch/reference/content-caching.md → docs/client/explanation/architecture/content-caching.md

@@ -5,7 +5,7 @@ myst:
 ---
 
 
-(livepatch-reference-content-caching)=
+(client-reference-content-caching)=
 
 # Content Caching
 

docs/livepatch/explanation/how-livepatching-works.md → docs/client/explanation/architecture/how-livepatching-works.md

@@ -5,7 +5,7 @@ myst:
 ---
 
 
-(livepatch-explanation-how-kernel-livepatching-works)=
+(client-explanation-how-kernel-livepatching-works)=
 
 # How kernel Livepatching works?
 

docs/client/explanation/architecture/index.md

@@ -0,0 +1,34 @@
+---
+myst:
+  html_meta:
+    description: "How Livepatching works and what kind of updates it provides."
+---
+
+
+(client-explanation-architecture)=
+
+# Architecture
+
+How Livepatching works and what kind of updates it provides.
+
+## In this section
+
+- [How Livepatching works?](/client/explanation/architecture/how-livepatching-works.md)
+- [What kind of updates are provided by Livepatch?](/client/explanation/architecture/what-kind-of-updates-are-provided-by-livepatch.md)
+- [What kind of updates are not provided by Livepatch?](/client/explanation/architecture/what-kind-of-updates-are-not-provided-by-livepatch.md)
+- [What are Livepatch tiers?](/client/explanation/architecture/what-are-livepatch-tiers.md)
+- [When should I expect new updates?](/client/explanation/architecture/when-should-i-expect-new-updates.md)
+- [Content Caching](/client/explanation/architecture/content-caching.md)
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+:hidden:
+
+How livepatching works <how-livepatching-works.md>
+What kind of updates are provided by livepatch <what-kind-of-updates-are-provided-by-livepatch.md>
+What kind of updates are not provided by livepatch <what-kind-of-updates-are-not-provided-by-livepatch.md>
+What are livepatch tiers <what-are-livepatch-tiers.md>
+When should i expect new updates <when-should-i-expect-new-updates.md>
+Content Caching <content-caching.md>
+```

docs/livepatch/explanation/what-are-livepatch-tiers.md → docs/client/explanation/architecture/what-are-livepatch-tiers.md

@@ -5,7 +5,7 @@ myst:
 ---
 
 
-(livepatch-explanation-what-are-livepatch-tiers)=
+(client-explanation-what-are-livepatch-tiers)=
 
 # What are Livepatch tiers?
 
@@ -20,4 +20,4 @@ Livepatch delivers patches to “tiers”. A tier is a target audience for the d
 
 Our kernel team closely monitors the patch health within internal before promoting to updates and further monitoring is done before promoting the patch to stable.
 
-For finer-grained control over patch roll-out take a look at [Livepatch On-Prem](/livepatch_on_prem/index.md).
+For finer-grained control over patch roll-out take a look at [Livepatch On-Prem](/server/index.md).

docs/livepatch/explanation/what-kind-of-updates-are-not-provided-by-livepatch.md → docs/client/explanation/architecture/what-kind-of-updates-are-not-provided-by-livepatch.md

@@ -5,7 +5,7 @@ myst:
 ---
 
 
-(livepatch-explanation-what-kind-of-updates-are-not-provided-by-the-livepatch-service)=
+(client-explanation-what-kind-of-updates-are-not-provided-by-the-livepatch-service)=
 
 # What kind of updates are not provided by the Livepatch service?
 

docs/livepatch/explanation/what-kind-of-updates-are-provided-by-livepatch.md → docs/client/explanation/architecture/what-kind-of-updates-are-provided-by-livepatch.md

@@ -5,7 +5,7 @@ myst:
 ---
 
 
-(livepatch-explanation-what-kind-of-updates-will-be-provided-by-the-ubuntu-livepatch-service)=
+(client-explanation-what-kind-of-updates-will-be-provided-by-the-ubuntu-livepatch-service)=
 
 # What kind of updates will be provided by the Ubuntu Livepatch Service?
 

docs/livepatch/explanation/when-should-i-expect-new-updates.md → docs/client/explanation/architecture/when-should-i-expect-new-updates.md

@@ -5,7 +5,7 @@ myst:
 ---
 
 
-(livepatch-explanation-when-should-i-expect-new-updates)=
+(client-explanation-when-should-i-expect-new-updates)=
 
 # When should I expect new updates??
 

docs/client/explanation/index.md

@@ -0,0 +1,30 @@
+---
+myst:
+  html_meta:
+    description: "Explanation - learn about this topic in Livepatch client."
+---
+
+
+(client-explanation)=
+
+# Explanation
+
+Discussion and clarification of key topics related to Livepatch.
+
+## In this section
+
+- [Architecture](/client/explanation/architecture/index.md) — How Livepatching works and what kind of updates it provides.
+- [Security](/client/explanation/security/index.md) — How CVEs are rated and how Livepatch keeps systems secure.
+- [Patches](/client/explanation/patches/index.md) — How patches are installed and their lifecycle.
+- [Troubleshooting](/client/explanation/troubleshooting/index.md) — Diagnose and understand Livepatch client issues.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+:hidden:
+
+Architecture <architecture/index.md>
+Security <security/index.md>
+Patches <patches/index.md>
+Troubleshooting <troubleshooting/index.md>
+```

docs/client/explanation/patches/index.md

@@ -0,0 +1,28 @@
+---
+myst:
+  html_meta:
+    description: "How patches are installed, their lifecycle, and security considerations."
+---
+
+
+(client-explanation-patches)=
+
+# Patches
+
+How patches are installed, their lifecycle, and security considerations.
+
+## In this section
+
+- [Patch Lifecycle: From CVE to Client Machines](/client/explanation/patches/patch-lifecycle.md)
+- [Patch Installation](/client/explanation/patches/patch-installation.md)
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+:hidden:
+
+Patch Lifecycle <patch-lifecycle.md>
+Patch Installation <patch-installation.md>
+```
+
+

docs/livepatch/reference/patch-installation.md → docs/client/explanation/patches/patch-installation.md

@@ -5,7 +5,7 @@ myst:
 ---
 
 
-(livepatch-reference-patch-installation)=
+(client-explanation-patches-patch-installation)=
 
 # Patch Installation
 

docs/livepatch/reference/patch-lifecycle.md → docs/client/explanation/patches/patch-lifecycle.md

@@ -5,7 +5,7 @@ myst:
 ---
 
 
-(livepatch-reference-patch-lifecycle-from-cve-to-client-machines)=
+(client-explanation-patches-patch-lifecycle-from-cve-to-client-machines)=
 
 # Patch Lifecycle: From CVE to Client Machines
 
@@ -28,17 +28,17 @@ Upon successful testing internally, patches are released in phases to the update
 
 Once the livepatch for a kernel has been released for use, the Livepatch client downloads the patch from the configured Livepatch server and patch source. The downloaded payload consists of the Linux kernel module responsible for patching the running kernel, as well as some metadata. The Livepatch client then inserts the kernel module by making the appropriate syscall. This only affects the in-memory kernel code and not the installed kernel.
 
-The Livepatch client is also equipped with mechanisms to prevent crash loops on installation of a faulty livepatch. For more information on patch installation and preventing crash loops, see [Patch Installation reference](/livepatch/reference/patch-installation.md)
+The Livepatch client is also equipped with mechanisms to prevent crash loops on installation of a faulty livepatch. For more information on patch installation and preventing crash loops, see [Patch Installation reference](/client/explanation/patches/patch-installation.md)
 
 ## Livepatch Security
 
 Ensuring the secure transmission and application of a livepatch is paramount to maintaining kernel stability and preventing installation of malicious kernel modules. The Livepatch client ensures that installed livepatches are genuine and authentic before applying them to the kernel. This is achieved by verifying the livepatch content using SHA256 file checksums, verifying the digital signature for the livepatch kernel module using asymmetric encryption and using TLS to communicate with the hosted Canonical Livepatch server.
 
-For more information on how the security of livepatches is ensured, see [Patch Security reference.](/livepatch/reference/patch-security.md)
+For more information on how the security of livepatches is ensured, see [Patch Security reference.](/client/reference/patches/patch-security.md)
 
 ## Livepatch Monitoring and Blocklisting on faulty patches
 
-In order to [avoid crash loops after application of a faulty livepatch](/livepatch/reference/patch-installation.md), Livepatch client monitors the health of the machine before, during, and after the patching activity. The various phases of Livepatch client's activity include: patch download, patch insertion, patch transition, and patch application.
+In order to [avoid crash loops after application of a faulty livepatch](/client/explanation/patches/patch-installation.md), Livepatch client monitors the health of the machine before, during, and after the patching activity. The various phases of Livepatch client's activity include: patch download, patch insertion, patch transition, and patch application.
 
 Livepatch client transmits pings which contain data about patching activity to Livepatch server. These pings are anonymous and are only used to understand the health and status of machines during the insertion process and after the application process.
 
@@ -51,3 +51,6 @@ If the system is on kernel version 4.4 or earlier, due to older kernel interface
 After a livepatch module is applied, the Livepatch client sends multiple health pings to the hosted Canonical Livepatch server. The first ping will have the time spent waiting for the kernel to apply the livepatch module (if running a kernel later than version 4.4), Then the client sends 3 more health pings from 1 minute, 5 minutes and 15 minutes from the time the kernel applied the livepatch module.
 
 If Livepatch client is retrieving patches from livepatch.canonical.com, the reported metrics are monitored by Canonical's Livepatch team. In the unlikely event that Livepatch client is reporting an error across a significant number of machines, the Livepatch team performs further analysis, and considers halting distribution (blocklisting) of the patch in question. Once a patch has been blocklisted, it will no longer be distributed to new clients or applied in the client machines that already possess the blocklisted patch.
+
+
+

docs/livepatch/explanation/how-cves-are-rated.md → docs/client/explanation/security/how-cves-are-rated.md

@@ -5,7 +5,7 @@ myst:
 ---
 
 
-(livepatch-explanation-how-do-you-rate-a-cve)=
+(client-explanation-how-do-you-rate-a-cve)=
 
 # How do you rate a CVE?
 

docs/client/explanation/security/index.md

@@ -0,0 +1,30 @@
+---
+myst:
+  html_meta:
+    description: "How CVEs are rated and how Livepatch keeps systems secure."
+---
+
+
+(client-explanation-security)=
+
+# Security
+
+How CVEs are rated and how Livepatch keeps systems secure.
+
+## In this section
+
+- [How CVEs are rated?](/client/explanation/security/how-cves-are-rated.md)
+- [Security Overview](/client/explanation/security/security-overview.md)
+- [Security Lifecycle](/client/explanation/security/security-lifecycle.md)
+- [Livepatch security notices](/client/explanation/security/livepatch-security-notices.md)
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+:hidden:
+
+How cves are rated <how-cves-are-rated.md>
+Security overview <security-overview.md>
+Security lifecycle <security-lifecycle.md>
+Livepatch security notices <livepatch-security-notices.md>
+```

docs/livepatch/explanation/livepatch-security-notices.md → docs/client/explanation/security/livepatch-security-notices.md

@@ -5,7 +5,7 @@ myst:
 ---
 
 
-(livepatch-explanation-livepatch-security-notices)=
+(client-explanation-livepatch-security-notices)=
 
 # Livepatch security notices
 

docs/livepatch/explanation/security-lifecycle.md → docs/client/explanation/security/security-lifecycle.md

@@ -5,7 +5,7 @@ myst:
 ---
 
 
-(livepatch-explanation-livepatch-client-security-lifecycle)=
+(client-explanation-livepatch-client-security-lifecycle)=
 
 # Livepatch Client Security Lifecycle
 

docs/livepatch/explanation/security-overview.md → docs/client/explanation/security/security-overview.md

@@ -5,7 +5,7 @@ myst:
 ---
 
 
-(livepatch-explanation-security-overview)=
+(client-explanation-security-overview)=
 
 # Security Overview
 
@@ -15,30 +15,30 @@ This document provides an overview of the security features and practices implem
 
 The Livepatch client incorporates several mechanisms to ensure the integrity and authenticity of patches and the security of communication:
 
-- **Patch Verification**: Patches undergo a verification process using SHA256 checksums to ensure file integrity upon download. For more details, refer to the [Cryptographic Documentation](/livepatch/reference/patch-security.md).
+- **Patch Verification**: Patches undergo a verification process using SHA256 checksums to ensure file integrity upon download. For more details, refer to the [Cryptographic Documentation](/client/reference/patches/patch-security.md).
 
-- **Patch Signatures**: All Linux kernel modules distributed as part of patches are cryptographically signed by Canonical using SHA512 with RSA. This verifies their authenticity and prevents the installation of malicious patches. Further information can be found in the [Cryptographic Documentation](/livepatch/reference/patch-security.md).
+- **Patch Signatures**: All Linux kernel modules distributed as part of patches are cryptographically signed by Canonical using SHA512 with RSA. This verifies their authenticity and prevents the installation of malicious patches. Further information can be found in the [Cryptographic Documentation](/client/reference/patches/patch-security.md).
 
-- **TLS Communication**: The Livepatch client uses HTTPS and relies on TLS v1.2 or higher for secure communication with the Livepatch server, utilizing host machine CA certificates and additional fixed certificates for server authentication. Details on TLS communication are available in the [Cryptographic Documentation](/livepatch/reference/patch-security.md).
+- **TLS Communication**: The Livepatch client uses HTTPS and relies on TLS v1.2 or higher for secure communication with the Livepatch server, utilizing host machine CA certificates and additional fixed certificates for server authentication. Details on TLS communication are available in the [Cryptographic Documentation](/client/reference/patches/patch-security.md).
 
 ## Risks
 
 While the Livepatch client is designed with security in mind, it is important to be aware of potential risks:
 
 - **TLS Enforcement (On-premises deployments)**: Although the Canonical hosted Livepatch server redirects HTTP to HTTPS, there is no client-side enforcement for TLS usage in on-premises deployments. Forgoing TLS in such scenarios is not recommended due to security implications.
 
-- **Privileged access to Auth Tokens**: Authentication for the Livepatch Client, with the Livepatch Server, can be established using [Auth Tokens](/livepatch_on_prem/reference/authentication.md#client-apis) or [Resource Tokens](/livepatch_on_prem/reference/authentication.md#client-apis). After successful client registration, a machine token is issued to the Livepatch client which can be used for subsequent authentication. Privileged access to this token must be controlled to prevent usage by a malicious third-party.
+- **Privileged access to Auth Tokens**: Authentication for the Livepatch Client, with the Livepatch Server, can be established using [Auth Tokens](/server/reference/authentication/authentication.md#client-apis) or [Resource Tokens](/server/reference/authentication/authentication.md#client-apis). After successful client registration, a machine token is issued to the Livepatch client which can be used for subsequent authentication. Privileged access to this token must be controlled to prevent usage by a malicious third-party.
 
 - **Data at Rest**: The Livepatch client does not encrypt its data at rest. However, all client data is stored in the [$SNAP_COMMON](https://snapcraft.io/docs/reference/development/environment-variables/#snap-common) and [$SNAP_DATA](https://snapcraft.io/docs/reference/development/environment-variables/#snap-data) directories. The Livepatch client snap ensures that only the root user has read and write access to the sensitive data stored in these directories. It is recommended to maintain strict privileged access controls, to prevent unauthorized access of the snap data.
 
 ## Related Security Documentation
 
-[Patch Security](/livepatch/reference/patch-security.md): This document provides in-depth details on the cryptographic approaches used by the Livepatch client for patch verification, signatures, and secure communication.
+[Patch Security](/client/reference/patches/patch-security.md): This document provides in-depth details on the cryptographic approaches used by the Livepatch client for patch verification, signatures, and secure communication.
 
-[Secure Client Operation](/livepatch/how-to-guides/securely-configure-and-operate-the-client.md): This document provides information on how to securely configure and operate the Livepatch client.
+[Secure Client Operation](/client/how-to-guides/security/securely-configure-and-operate-the-client.md): This document provides information on how to securely configure and operate the Livepatch client.
 
-[Secure Client Decommissioning](/livepatch/how-to-guides/securely-decommission-the-client.md): This document provides information on how to securely decommission the Livepatch client snap and its data.
+[Secure Client Decommissioning](/client/how-to-guides/security/securely-decommission-the-client.md): This document provides information on how to securely decommission the Livepatch client snap and its data.
 
-[Security Lifecycle](/livepatch/explanation/security-lifecycle.md):This document provides insights into how the security of the Livepatch client is maintained. It also provides guidelines on how security updates to the Livepatch client snap can be controlled.
+[Security Lifecycle](/client/explanation/security/security-lifecycle.md):This document provides insights into how the security of the Livepatch client is maintained. It also provides guidelines on how security updates to the Livepatch client snap can be controlled.
 
-[Reporting Security Vulnerabilities](/livepatch/how-to-guides/report-client-vulnerability.md): This document lays out the process to report security vulnerabilities found in the Livepatch client and provides information about the Ubuntu Security disclosure and embargo policy.
+[Reporting Security Vulnerabilities](/client/how-to-guides/security/report-client-vulnerability.md): This document lays out the process to report security vulnerabilities found in the Livepatch client and provides information about the Ubuntu Security disclosure and embargo policy.

docs/livepatch/explanation/do-i-need-to-reboot.md → docs/client/explanation/troubleshooting/do-i-need-to-reboot.md

@@ -5,7 +5,7 @@ myst:
 ---
 
 
-(livepatch-explanation-do-i-need-to-reboot)=
+(client-explanation-do-i-need-to-reboot)=
 
 # Do I need to reboot?
 

docs/client/explanation/troubleshooting/index.md

@@ -0,0 +1,34 @@
+---
+myst:
+  html_meta:
+    description: "Diagnose and understand Livepatch client issues."
+---
+
+
+(client-explanation-troubleshooting)=
+
+# Troubleshooting
+
+Diagnose and understand Livepatch client issues.
+
+## In this section
+
+- [Why Livepatch is not working on my machine?](/client/explanation/troubleshooting/why-livepatch-is-not-working-on-my-machine.md)
+- [Service access problem](/client/explanation/troubleshooting/service-access-problem.md)
+- [Why are there missing patches?](/client/explanation/troubleshooting/why-are-there-missing-patches.md)
+- [What happens when a problem cannot be patched?](/client/explanation/troubleshooting/what-happens-when-a-problem-cannot-be-patched.md)
+- [Do I need to reboot?](/client/explanation/troubleshooting/do-i-need-to-reboot.md)
+- [What is patch cut-off date?](/client/explanation/troubleshooting/what-is-patch-cut-off-date.md)
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+:hidden:
+
+Why livepatch is not working on my machine <why-livepatch-is-not-working-on-my-machine.md>
+Service access problem <service-access-problem.md>
+Why are there missing patches <why-are-there-missing-patches.md>
+What happens when a problem cannot be patched <what-happens-when-a-problem-cannot-be-patched.md>
+Do i need to reboot <do-i-need-to-reboot.md>
+What is patch cut off date <what-is-patch-cut-off-date.md>
+```