diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml
new file mode 100644
index 0000000000..66c917d51d
--- /dev/null
+++ b/.github/workflows/automatic-doc-checks.yml
@@ -0,0 +1,23 @@
+#
+name: Automatic doc checks
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    paths:
+      - 'docs/**'   # Only run on changes to the docs directory
+
+  workflow_dispatch:
+    # Manual trigger
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  documentation-checks:
+    uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
+    with:
+      working-directory: "docs"
+      fetch-depth: 0
diff --git a/.github/workflows/check_libs.yaml b/.github/workflows/check_libs.yaml
index 6ba39d8f32..b46880e64c 100644
--- a/.github/workflows/check_libs.yaml
+++ b/.github/workflows/check_libs.yaml
@@ -14,6 +14,7 @@ on:
       - 'LICENSE'
       - '**.md'
       - 'renovate.json'
+      - 'docs/**'
 
 jobs:
   lib-check:
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 334cc49a18..ab6017b5a9 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -11,7 +11,7 @@ on:
     paths-ignore:
       - '**.md'
       - '.github/renovate.json5'
-      - '.github/workflows/sync_docs.yaml'
+      - 'docs/**'
   schedule:
     - cron: '53 0 * * *'  # Daily at 00:53 UTC
   # Triggered on push to branch "main" by .github/workflows/release.yaml
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
index 1297ccd9bd..c055ae6d98 100644
--- a/.github/workflows/release.yaml
+++ b/.github/workflows/release.yaml
@@ -10,7 +10,6 @@ on:
       - 'docs/**'
       - '.github/renovate.json5'
       - '.github/workflows/check_libs.yaml'
-      - '.github/workflows/sync_docs.yaml'
 
 jobs:
   ci-tests:
diff --git a/.github/workflows/sync_docs.yaml b/.github/workflows/sync_docs.yaml
deleted file mode 100644
index b1ff70bacd..0000000000
--- a/.github/workflows/sync_docs.yaml
+++ /dev/null
@@ -1,18 +0,0 @@
-# Copyright 2024 Canonical Ltd.
-# See LICENSE file for licensing details.
-name: Sync docs from Discourse
-
-on:
-  workflow_dispatch:
-  schedule:
-    - cron: '53 0 * * *'  # Daily at 00:53 UTC
-
-jobs:
-  sync-docs:
-    name: Sync docs from Discourse
-    uses: canonical/data-platform-workflows/.github/workflows/sync_docs.yaml@v32.0.0
-    with:
-      reviewers: a-velasco
-    permissions:
-      contents: write  # Needed to create git tags
-      pull-requests: write  # Needed to create PR
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 0000000000..7469fec387
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,39 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  jobs:
+    post_checkout:
+    - git fetch --unshallow || true
+    # Cancel building pull requests when there aren't changed in the docs directory.
+    # If there are no changes (git diff exits with 0) we force the command to return with 183.
+    # This is a special exit code on Read the Docs that will cancel the build immediately.
+    # https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition
+    - |
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/docs-dev -- 'docs/' '.readthedocs.yaml';
+      then
+        exit 183;
+      fi
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: dirhtml
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+formats:
+- pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+  - requirements: docs/requirements.txt
diff --git a/README.md b/README.md
index 81b3b37212..c1af7a22cf 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,6 @@
 [![CharmHub Badge](https://charmhub.io/mysql/badge.svg)](https://charmhub.io/mysql)
 [![Release](https://github.com/canonical/mysql-operator/actions/workflows/release.yaml/badge.svg)](https://github.com/canonical/mysql-operator/actions/workflows/release.yaml)
 [![Tests](https://github.com/canonical/mysql-operator/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/canonical/mysql-operator/actions/workflows/ci.yaml?query=branch%3Amain)
-[![Docs](https://github.com/canonical/mysql-operator/actions/workflows/sync_docs.yaml/badge.svg)](https://github.com/canonical/mysql-operator/actions/workflows/sync_docs.yaml)
 
 ## Description
 
diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt
new file mode 100644
index 0000000000..50a6100232
--- /dev/null
+++ b/docs/.custom_wordlist.txt
@@ -0,0 +1,80 @@
+# Leave a blank line at the end of this file to support concatenation
+airgap
+async
+backend
+backends
+backport
+Charmcraft
+cjk
+cryptographically
+databag
+dvipng
+fonts
+freefont
+Furo
+github
+GitHub
+GPG
+gyre
+html
+https
+InnoDB
+Intersphinx
+io
+ip
+Jira
+landscape
+lang
+lastmod
+LaTeX
+latexmk
+MinIO
+Multipass
+mydumper
+mysql
+MyST
+nameserver
+nameservers
+Open Graph
+otf
+PDF
+Percona
+plantuml
+PNG
+PR
+Pygments
+pymarkdown
+QEMU
+Read the Docs
+readthedocs
+reStructuredText
+Rockcraft
+rst
+sitemapindex
+snap_daemon
+Sphinx
+Spread
+spread_test_example
+subproject
+subprojects
+SVG
+tex
+texlive
+TOC
+toctree
+txt
+uncommenting
+URL
+utils
+VMs
+WCAG
+whitespace
+whitespaces
+wordlist
+xbstream
+xetex
+xindy
+xml
+xtrabackup
+yaml
+YouTube
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000000..aad78f1f7c
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,26 @@
+# Environment
+*env*/
+.sphinx/venv/
+
+# Sphinx
+.sphinx/warnings.txt
+.sphinx/.wordlist.dic
+.sphinx/.doctrees/
+.sphinx/update/
+.sphinx/node_modules/
+
+# Vale
+.sphinx/styles/*
+.sphinx/vale.ini
+
+# Build outputs
+_build
+
+# Node.js
+package*.json
+
+# Unrelated cache and config files
+.DS_Store
+__pycache__
+.idea/
+.vscode/
diff --git a/docs/.sphinx/.pre-commit-config.yaml b/docs/.sphinx/.pre-commit-config.yaml
new file mode 100644
index 0000000000..07e0b48cbd
--- /dev/null
+++ b/docs/.sphinx/.pre-commit-config.yaml
@@ -0,0 +1,23 @@
+repos:
+  - repo: local
+    hooks:
+      - id: make-spelling
+        name: Run make spelling
+        entry: make -C docs spelling
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$
+
+      - id: make-linkcheck
+        name: Run make linkcheck
+        entry: make -C docs linkcheck
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$
+
+      - id: make-woke
+        name: Run make woke
+        entry: make -C docs woke
+        language: system
+        pass_filenames: false
+        files: ^docs/.*\.(rst|md|txt)$
diff --git a/docs/.sphinx/.pymarkdown.json b/docs/.sphinx/.pymarkdown.json
new file mode 100644
index 0000000000..2c4c669dbf
--- /dev/null
+++ b/docs/.sphinx/.pymarkdown.json
@@ -0,0 +1,46 @@
+{
+    "plugins": {
+        "selectively_enable_rules": true,
+        "heading-style": {
+            "enabled": true,
+            "style": "atx"
+        },
+        "commands-show-output": {
+            "enabled": true
+        },
+        "no-missing-space-atx": {
+            "enabled": true
+        },
+        "blanks-around-headings": {
+            "enabled": true
+        },
+        "heading-start-left": {
+            "enabled": true
+        },
+        "no-trailing-punctuation": {
+            "enabled": true,
+            "punctuation": ".,;。，；"
+        },
+        "blanks-around-fences": {
+            "enabled": true,
+            "list_items": false
+        },
+        "blanks-around-lists": {
+            "enabled": true
+        },
+        "hr-style": {
+            "enabled": true
+        },
+        "no-empty-links": {
+            "enabled": true
+        },
+        "no-alt-text": {
+            "enabled": true
+        }
+    },
+    "extensions": {
+        "front-matter" : {
+            "enabled" : true
+        }
+    }
+}
diff --git a/docs/.sphinx/get_vale_conf.py b/docs/.sphinx/get_vale_conf.py
new file mode 100644
index 0000000000..e2a81c088a
--- /dev/null
+++ b/docs/.sphinx/get_vale_conf.py
@@ -0,0 +1,151 @@
+#! /usr/bin/env python
+
+import os
+import shutil
+import subprocess
+import tempfile
+import sys
+import logging
+import argparse
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(message)s',
+    datefmt='%Y-%m-%d %H:%M:%S'
+)
+
+SPHINX_DIR = os.path.join(os.getcwd(), ".sphinx")
+
+GITHUB_REPO = "canonical/documentation-style-guide"
+GITHUB_CLONE_URL = f"https://github.com/{GITHUB_REPO}.git"
+
+# Source paths to copy from repo
+VALE_FILE_LIST = [
+    "styles/Canonical",
+    "styles/config/vocabularies/Canonical",
+    "styles/config/dictionaries",
+    "vale.ini"
+]
+
+def clone_repo_and_copy_paths(file_source_dest, overwrite=False):
+    """
+    Clone the repository to a temporary directory and copy required files
+    
+    Args:
+        file_source_dest: dictionary of file paths to copy from the repository,
+            and their destination paths
+        overwrite: boolean flag to overwrite existing files in the destination
+    
+    Returns:
+        bool: True if all files were copied successfully, False otherwise
+    """
+
+    if not file_source_dest:
+        logging.error("No files to copy")
+        return False
+
+    # Create temporary directory on disk for cloning
+    temp_dir = tempfile.mkdtemp()
+    logging.info("Cloning repository <%s> to temporary directory: %s", GITHUB_REPO, temp_dir)
+    clone_cmd = ["git", "clone", "--depth", "1", GITHUB_CLONE_URL, temp_dir]
+
+    try:
+        result = subprocess.run(
+            clone_cmd, 
+            capture_output=True, 
+            text=True,
+            check=True
+        )
+        logging.debug("Git clone output: %s", result.stdout)
+    except subprocess.CalledProcessError as e:
+        logging.error("Git clone failed: %s", e.stderr)
+        return False
+
+    # Copy files from the cloned repository to the destination paths
+    is_copy_success = True
+    for source, dest in file_source_dest.items():
+        source_path = os.path.join(temp_dir, source)
+
+        if not os.path.exists(source_path):
+            is_copy_success = False
+            logging.error("Source path not found: %s", source_path)
+            continue
+
+        if not copy_files_to_path(source_path, dest, overwrite):
+            is_copy_success = False            
+            logging.error("Failed to copy %s to %s", source_path, dest)
+
+    # Clean up temporary directory
+    logging.info("Cleaning up temporary directory: %s", temp_dir)
+    shutil.rmtree(temp_dir)
+
+    return is_copy_success
+
+def copy_files_to_path(source_path, dest_path, overwrite=False):
+    """
+    Copy a file or directory from source to destination
+    
+    Args:
+        source_path: Path to the source file or directory
+        dest_path: Path to the destination
+        overwrite: Boolean flag to overwrite existing files in the destination
+        
+    Returns:
+        bool: True if copy was successful, False otherwise
+    """
+    # Skip if source file doesn't exist
+    if not os.path.exists(source_path):
+        logging.warning("Source path not found: %s", source_path)
+        return False
+
+    logging.info("Copying %s to %s", source_path, dest_path)
+    # Handle existing files
+    if os.path.exists(dest_path):
+        if overwrite:
+            logging.info("  Destination exists, overwriting: %s", dest_path)
+            if os.path.isdir(dest_path):
+                shutil.rmtree(dest_path)
+            else:
+                os.remove(dest_path)
+        else:
+            logging.info("  Destination exists, skip copying (use overwrite=True to replace): %s",
+                         dest_path)
+            return True     # Skip copying
+
+    # Copy the source to destination
+    try:
+        if os.path.isdir(source_path):
+            # entire directory
+            shutil.copytree(source_path, dest_path)
+        else:
+            # individual files
+            shutil.copy2(source_path, dest_path)
+        return True
+    except (shutil.Error, OSError) as e:
+        logging.error("Copy failed: %s", e)
+        return False
+
+def parse_arguments():
+    parser = argparse.ArgumentParser(description="Download Vale configuration files")
+    parser.add_argument("--no-overwrite", action="store_true", help="Don't overwrite existing files")
+    return parser.parse_args()
+
+def main():
+    # Define local directory paths
+    vale_files_dict = {file: os.path.join(SPHINX_DIR, file) for file in VALE_FILE_LIST}
+
+    # Parse command line arguments, default to overwrite_enabled = True
+    overwrite_enabled = not parse_arguments().no_overwrite
+
+    # Download into /tmp through git clone 
+    if not clone_repo_and_copy_paths(vale_files_dict, overwrite=overwrite_enabled):
+        logging.error("Failed to download files from repository")
+        return 1
+
+    logging.info("Download complete")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())  # Keep return code
diff --git a/docs/.sphinx/metrics/build_metrics.py b/docs/.sphinx/metrics/build_metrics.py
new file mode 100644
index 0000000000..529fb85b9b
--- /dev/null
+++ b/docs/.sphinx/metrics/build_metrics.py
@@ -0,0 +1,94 @@
+#!/usr/bin/python3
+
+import sys
+import argparse
+from pathlib import Path
+from html.parser import HTMLParser
+from urllib.parse import urlsplit
+
+
+class MetricsParser(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.int_link_count = 0
+        self.ext_link_count = 0
+        self.fragment_count = 0
+        self.image_count = 0
+        self.in_object = 0
+
+    @property
+    def link_count(self):
+        return self.fragment_count + self.int_link_count + self.ext_link_count
+
+    def read(self, file):
+        """
+        Read *file* (a file-like object with a ``read`` method returning
+        strings) a chunk at a time, feeding each chunk to the parser.
+        """
+        # Ensure the parser state is reset before each file (just in case
+        # there's an erroneous dangling <object>)
+        self.reset()
+        self.in_object = 0
+        buf = ''
+        while True:
+            # Parse 1MB chunks at a time
+            buf = file.read(1024**2)
+            if not buf:
+                break
+            self.feed(buf)
+
+    def handle_starttag(self, tag, attrs):
+        """
+        Count <a>, <img>, and <object> tags to determine the number of internal
+        and external links, and the number of images.
+        """
+        attrs = dict(attrs)
+        if tag == 'a' and 'href' in attrs:
+            # If there's no href, it's an anchor; if there's no hostname
+            # (netloc) or path, it's just a fragment link within the page
+            url = urlsplit(attrs['href'])
+            if url.netloc:
+                self.ext_link_count += 1
+            elif url.path:
+                self.int_link_count += 1
+            else:
+                self.fragment_count += 1
+        elif tag == 'object':
+            # <object> tags are a bit complex as they nest to offer fallbacks
+            # and may contain an <img> fallback. We only want to count the
+            # outer-most <object> in this case
+            if self.in_object == 0:
+                self.image_count += 1
+            self.in_object += 1
+        elif tag == 'img' and self.in_object == 0:
+            self.image_count += 1
+
+    def handle_endtag(self, tag):
+        if tag == 'object':
+            # Never let in_object be negative
+            self.in_object = max(0, self.in_object - 1)
+
+
+def main(args=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        'build_dir', metavar='build-dir', nargs='?', default='.',
+        help="The directory to scan for HTML files")
+    config = parser.parse_args(args)
+
+    parser = MetricsParser()
+    for path in Path(config.build_dir).rglob('*.html'):
+        with path.open('r', encoding='utf-8', errors='replace') as f:
+            parser.read(f)
+
+    print('Summarising metrics for build files (.html)...')
+    print(f'\tlinks: {parser.link_count} ('
+          f'{parser.fragment_count} #frag…, '
+          f'{parser.int_link_count} /int…, '
+          f'{parser.ext_link_count} https://ext…'
+          ')')
+    print(f'\timages: {parser.image_count}')
+
+
+if __name__ == '__main__':
+    sys.exit(main())
diff --git a/docs/.sphinx/metrics/source_metrics.sh b/docs/.sphinx/metrics/source_metrics.sh
new file mode 100755
index 0000000000..07147d6361
--- /dev/null
+++ b/docs/.sphinx/metrics/source_metrics.sh
@@ -0,0 +1,66 @@
+#!/bin/bash
+# shellcheck disable=all
+
+VENV=".sphinx/venv/bin/activate"
+
+files=0
+words=0
+readabilityWords=0
+readabilitySentences=0
+readabilitySyllables=0
+readabilityAverage=0
+readable=true
+
+# measure number of files (.rst and .md), excluding those in .sphinx dir
+files=$(find . -type d -path './.sphinx' -prune -o -type f \( -name '*.md' -o -name '*.rst' \) -print | wc -l)
+
+# calculate metrics only if source files are present
+if [ "$files" -eq 0 ]; then
+    echo "There are no source files to calculate metrics"
+else
+    # measure raw total number of words, excluding those in .sphinx dir
+    words=$(find . -type d -path './.sphinx' -prune -o \( -name '*.md' -o -name '*.rst' \) -exec cat {} + | wc -w)
+
+    # calculate readability for markdown source files
+    echo "Activating virtual environment to run vale..."
+    source "${VENV}"
+
+    for file in *.md *.rst; do
+        if [ -f "$file" ]; then
+            readabilityWords=$(vale ls-metrics "$file" | grep '"words"' | sed 's/[^0-9]*//g')
+            readabilitySentences=$(vale ls-metrics "$file" | grep '"sentences"' | sed 's/[^0-9]*//g')
+            readabilitySyllables=$(vale ls-metrics "$file" | grep '"syllables"' | sed 's/[^0-9]*//g')
+        fi
+    done
+
+    echo "Deactivating virtual environment..."
+    deactivate
+
+    # calculate mean number of words
+    if [ "$files" -ge 1 ]; then
+        meanval=$((readabilityWords / files))
+    else
+        meanval=$readabilityWords
+    fi
+
+    readabilityAverage=$(echo "scale=2; 0.39 * ($readabilityWords / $readabilitySentences) + (11.8 * ($readabilitySyllables / $readabilityWords)) - 15.59" | bc)
+
+    # cast average to int for comparison
+    readabilityAverageInt=$(echo "$readabilityAverage / 1" | bc)
+
+    # value below 8 is considered readable
+    if [ "$readabilityAverageInt" -lt 8 ]; then
+        readable=true
+    else
+        readable=false
+    fi
+
+    # summarise latest metrics
+    echo "Summarising metrics for source files (.md, .rst)..."
+    echo -e "\ttotal files: $files"
+    echo -e "\ttotal words (raw): $words"
+    echo -e "\ttotal words (prose): $readabilityWords"
+    echo -e "\taverage word count: $meanval"
+    echo -e "\treadability: $readabilityAverage"
+    echo -e "\treadable: $readable"
+fi
diff --git a/docs/.sphinx/pa11y.json b/docs/.sphinx/pa11y.json
new file mode 100644
index 0000000000..04dc1e1c5e
--- /dev/null
+++ b/docs/.sphinx/pa11y.json
@@ -0,0 +1,9 @@
+{
+  "chromeLaunchConfig": {
+    "args": [
+      "--no-sandbox"
+    ]
+  },
+  "reporter": "cli",
+  "standard": "WCAG2AA"
+}
diff --git a/docs/.sphinx/version b/docs/.sphinx/version
new file mode 100644
index 0000000000..26aaba0e86
--- /dev/null
+++ b/docs/.sphinx/version
@@ -0,0 +1 @@
+1.2.0
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000000..0b498e12f6
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,185 @@
+# Minimal makefile for Sphinx documentation
+#
+# Add your customisation to `Makefile` instead.
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXDIR       = .sphinx
+SPHINXOPTS      ?= -c . -d $(SPHINXDIR)/.doctrees -j auto
+SPHINXBUILD     ?= $(VENVDIR)/bin/sphinx-build
+SOURCEDIR       = .
+BUILDDIR        = _build
+VENVDIR         = $(SPHINXDIR)/venv
+PA11Y           = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json
+VENV            = $(VENVDIR)/bin/activate
+TARGET          = *
+ALLFILES        =  *.rst **/*.rst
+METRICSDIR      = $(SOURCEDIR)/.sphinx/metrics
+REQPDFPACKS     = latexmk fonts-freefont-otf texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng
+CONFIRM_SUDO    ?= N
+VALE_CONFIG     = $(SPHINXDIR)/vale.ini
+SPHINX_HOST     ?= 127.0.0.1
+SPHINX_PORT     ?= 8000
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@echo
+	@echo "-------------------------------------------------------------"
+	@echo "* watch, build and serve the documentation:  make run"
+	@echo "* only build:                                make html"
+	@echo "* only serve:                                make serve"
+	@echo "* clean built doc files:                     make clean-doc"
+	@echo "* clean full environment:                    make clean"
+	@echo "* check links:                               make linkcheck"
+	@echo "* check markdown:                            make lint-md"
+	@echo "* check spelling:                            make spelling"
+	@echo "* check spelling (without building again):   make spellcheck"
+	@echo "* check inclusive language:                  make woke"
+	@echo "* check accessibility:                       make pa11y"
+	@echo "* check style guide compliance:              make vale"
+	@echo "* check style guide compliance on target:    make vale TARGET=*"
+	@echo "* check metrics for documentation:           make allmetrics"
+	@echo "* other possible targets:                    make <TAB twice>"
+	@echo "-------------------------------------------------------------"
+	@echo
+
+.PHONY: help full‑help html epub pdf linkcheck spelling spellcheck woke \
+        vale pa11y run serve install pa11y‑install   \
+        vale‑install pdf‑prep pdf‑prep‑force clean clean‑doc allmetrics \
+        update lint-md
+
+full-help: $(VENVDIR)
+	@. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m"
+	@echo "Run 'make help' to see supported targets."
+
+# If requirements are updated, venv should be rebuilt and timestamped.
+$(VENVDIR):
+	@echo "... setting up virtualenv"
+	python3 -m venv $(VENVDIR) || { echo "You must install python3-venv before you can build the documentation."; exit 1; }
+	. $(VENV); pip install $(PIPOPTS) --require-virtualenv \
+	    --upgrade -r requirements.txt \
+            --log $(VENVDIR)/pip_install.log
+	@test ! -f $(VENVDIR)/pip_list.txt || \
+            mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak
+	@. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt
+	@touch $(VENVDIR)
+
+pa11y-install:
+	@command -v $(PA11Y) >/dev/null || { \
+			echo "Installing \"pa11y\" from npm..."; echo; \
+			mkdir -p $(SPHINXDIR)/node_modules/ ; \
+			npm install --prefix $(SPHINXDIR) pa11y; \
+		}
+
+pymarkdownlnt-install:
+	@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/pymarkdown || pip install pymarkdownlnt
+
+install: $(VENVDIR)
+
+run: install
+	. $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml --host $(SPHINX_HOST) --port $(SPHINX_PORT) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+# Does not depend on $(BUILDDIR) to rebuild properly at every run.
+html: install
+	. $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
+
+epub: install
+	. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)
+
+serve: html
+	cd "$(BUILDDIR)"; python3 -m http.server --bind 127.0.0.1 8000
+
+clean: clean-doc
+	@test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
+	rm -rf $(VENVDIR)
+	rm -rf $(SPHINXDIR)/node_modules/
+	rm -rf $(SPHINXDIR)/styles
+	rm -rf $(VALE_CONFIG)
+
+clean-doc:
+	git clean -fx "$(BUILDDIR)"
+	rm -rf $(SPHINXDIR)/.doctrees
+
+linkcheck: install
+	. $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; }
+	exit 0
+
+pa11y: pa11y-install html
+	find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)
+
+lint-md: pymarkdownlnt-install
+	@. $(VENV); pymarkdownlnt --config $(SPHINXDIR)/.pymarkdown.json scan --recurse --exclude=./$(SPHINXDIR)/** $(SOURCEDIR)
+
+vale-install: install
+	@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install rst2html vale
+	@. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py
+	@echo '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(SPHINXDIR)/styles/woke.filter
+	@echo '.Level=="error" and .Name!="Canonical.500-Repeated-words" and .Name!="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/error.filter
+	@echo '.Name=="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/spelling.filter
+	@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --version \;
+
+woke: vale-install
+	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+	@cat $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
+	@echo "Running Vale acceptable term check against $(TARGET). To change target set TARGET= with make command"
+	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/woke.filter' --glob='*.{md,rst}' $(TARGET)
+	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+
+vale: vale-install
+	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+	@cat $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
+	@echo "Running Vale against $(TARGET). To change target set TARGET= with make command"
+	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/error.filter' --glob='*.{md,rst}' $(TARGET)
+	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+
+spelling: vale-install
+	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+	@cat $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt
+	@echo "Running Vale against $(TARGET). To change target set TARGET= with make command"
+	@. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/spelling.filter' --glob='*.{md,rst}' $(TARGET)
+	@cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt
+
+spellcheck: spelling
+	@echo "Please note that the \`make spellcheck\` command is being deprecated in favor of \`make spelling\`"
+
+pdf-prep: install
+	@for packageName in $(REQPDFPACKS); do (dpkg-query -W -f='$${Status}' $$packageName 2>/dev/null | \
+        grep -c "ok installed" >/dev/null && echo "Package $$packageName is installed") && continue || \
+        (echo; echo "PDF generation requires the installation of the following packages: $(REQPDFPACKS)" && \
+        echo "" && echo "Run 'sudo make pdf-prep-force' to install these packages" && echo "" && echo \
+        "Please be aware these packages will be installed to your system") && exit 1 ; done
+
+pdf-prep-force:
+	apt-get update
+	apt-get upgrade -y
+	apt-get install --no-install-recommends -y $(REQPDFPACKS) \
+
+pdf: pdf-prep
+	@. $(VENV); sphinx-build -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+	@rm ./$(BUILDDIR)/latex/front-page-light.pdf || true
+	@rm ./$(BUILDDIR)/latex/normal-page-footer.pdf || true
+	@find ./$(BUILDDIR)/latex -name "*.pdf" -exec mv -t ./$(BUILDDIR) {} +
+	@rm -r $(BUILDDIR)/latex
+	@echo
+	@echo "Output can be found in ./$(BUILDDIR)"
+	@echo
+
+allmetrics: html
+	@echo "Recording documentation metrics..."
+	@echo "Checking for existence of vale..."
+	. $(VENV)
+	@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale
+	@. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py
+	@. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(VALE_CONFIG)" $(TARGET) > /dev/null \;
+	@eval '$(METRICSDIR)/source_metrics.sh $(PWD)'
+	@$(METRICSDIR)/build_metrics.py $(BUILDDIR)
+
+update: install
+	@. $(VENV); .sphinx/update_sp.py
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%:
+	$(MAKE) —no-print-directory install
+	. $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000000..93b40ee9ff
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,358 @@
+import datetime
+import os
+import yaml
+
+# Configuration for the Sphinx documentation builder.
+# All configuration specific to your project should be done in this file.
+#
+# If you're new to Sphinx and don't want any advanced or custom features,
+# just go through the items marked 'TODO'.
+#
+# A complete list of built-in Sphinx configuration values:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+#
+# Our starter pack uses the custom Canonical Sphinx extension
+# to keep all documentation based on it consistent and on brand:
+# https://github.com/canonical/canonical-sphinx
+
+
+#######################
+# Project information #
+#######################
+
+# Project name
+#
+# TODO: Update with the official name of your project or product
+
+project = "Charmed MySQL"
+author = "Canonical Ltd."
+
+
+# Sidebar documentation title; best kept reasonably short
+#
+# TODO: To include a version number, add it here (hardcoded or automated).
+#
+# TODO: To disable the title, set to an empty string.
+
+html_title = project + " documentation"
+
+
+# Copyright string; shown at the bottom of the page
+#
+# Now, the starter pack uses CC-BY-SA as the license
+# and the current year as the copyright year.
+#
+# TODO: If your docs need another license, specify it instead of 'CC-BY-SA'.
+#
+# TODO: If your documentation is a part of the code repository of your project,
+#       it inherits the code license instead; specify it instead of 'CC-BY-SA'.
+#
+# NOTE: For static works, it is common to provide the first publication year.
+#       Another option is to provide both the first year of publication
+#       and the current year, especially for docs that frequently change,
+#       e.g. 2022–2023 (note the en-dash).
+#
+#       A way to check a repo's creation date is to get a classic GitHub token
+#       with 'repo' permissions; see https://github.com/settings/tokens
+#       Next, use 'curl' and 'jq' to extract the date from the API's output:
+#
+#       curl -H 'Authorization: token <TOKEN>' \
+#         -H 'Accept: application/vnd.github.v3.raw' \
+#         https://api.github.com/repos/canonical/<REPO> | jq '.created_at'
+
+copyright = "%s CC-BY-SA, %s" % (datetime.date.today().year, author)
+
+
+# Documentation website URL
+#
+# TODO: Update with the official URL of your docs or leave empty if unsure.
+#
+# NOTE: The Open Graph Protocol (OGP) enhances page display in a social graph
+#       and is used by social media platforms; see https://ogp.me/
+
+# ogp_site_url = "https://canonical-starter-pack.readthedocs-hosted.com/"
+
+
+# Preview name of the documentation website
+#
+# TODO: To use a different name for the project in previews, update as needed.
+
+ogp_site_name = project
+
+
+# Preview image URL
+#
+# TODO: To customise the preview image, update as needed.
+
+ogp_image = "https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg"
+
+
+# Product favicon; shown in bookmarks, browser tabs, etc.
+
+# TODO: To customise the favicon, uncomment and update as needed.
+
+# html_favicon = '.sphinx/_static/favicon.png'
+
+
+# Dictionary of values to pass into the Sphinx context for all pages:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_context
+
+html_context = {
+    # Product page URL; can be different from product docs URL
+    #
+    # TODO: Change to your product website URL,
+    #       dropping the 'https://' prefix, e.g. 'ubuntu.com/lxd'.
+    #
+    # TODO: If there's no such website,
+    #       remove the {{ product_page }} link from the page header template
+    #       (usually .sphinx/_templates/header.html; also, see README.rst).
+    "product_page": "canonical.com/data/mysql",
+    # Product tag image; the orange part of your logo, shown in the page header
+    #
+    # TODO: To add a tag image, uncomment and update as needed.
+    # 'product_tag': '_static/tag.png',
+    # Your Discourse instance URL
+    #
+    # TODO: Change to your Discourse instance URL or leave empty.
+    #
+    # NOTE: If set, adding ':discourse: 123' to an .rst file
+    #       will add a link to Discourse topic 123 at the bottom of the page.
+    "discourse": "https://discourse.charmhub.io",
+    # Your Mattermost channel URL
+    #
+    # TODO: Change to your Mattermost channel URL or leave empty.
+    "mattermost": "",
+    # Your Matrix channel URL
+    #
+    # TODO: Change to your Matrix channel URL or leave empty.
+    "matrix": "https://matrix.to/#/#charmhub-data-platform:ubuntu.com",
+    # Your documentation GitHub repository URL
+    #
+    # TODO: Change to your documentation GitHub repository URL or leave empty.
+    #
+    # NOTE: If set, links for viewing the documentation source files
+    #       and creating GitHub issues are added at the bottom of each page.
+    "github_url": "https://github.com/canonical/mysql-operator",
+    # Docs branch in the repo; used in links for viewing the source files
+    #
+    # TODO: To customise the branch, uncomment and update as needed.
+    'repo_default_branch': 'main',
+    # Docs location in the repo; used in links for viewing the source files
+    "repo_folder": "/docs/",
+
+    # Docs location in the repo; used in links for viewing the source files
+    "repo_folder": "/docs/",
+
+    # TODO: To enable or disable the Previous / Next buttons at the bottom of pages
+    # Valid options: none, prev, next, both
+    "sequential_nav": "none",
+
+    # TODO: To enable listing contributors on individual pages, set to True
+    "display_contributors": True,
+
+    # Required for feedback button    
+    'github_issues': 'enabled',
+}
+
+# TODO: To enable the edit button on pages, uncomment and change the link to a
+# public repository on GitHub or Launchpad. Any of the following link domains
+# are accepted:
+# - https://github.com/example-org/example"
+# - https://launchpad.net/example
+# - https://git.launchpad.net/example
+#
+html_theme_options = {
+'source_edit_link': 'https://github.com/canonical/mysql-operator',
+}
+
+# Project slug; see https://meta.discourse.org/t/what-is-category-slug/87897
+#
+# TODO: If your documentation is hosted on https://docs.ubuntu.com/,
+#       uncomment and update as needed.
+
+# slug = ''
+
+#######################
+# Sitemap configuration: https://sphinx-sitemap.readthedocs.io/
+#######################
+
+# Base URL of RTD hosted project
+
+html_baseurl = 'https://canonical-charmed-mysql.readthedocs-hosted.com/'
+
+# URL scheme. Add language and version scheme elements.
+# When configured with RTD variables, check for RTD environment so manual runs succeed:
+
+if 'READTHEDOCS_VERSION' in os.environ:
+    version = os.environ["READTHEDOCS_VERSION"]
+    sitemap_url_scheme = '{version}{link}'
+else:
+    sitemap_url_scheme = 'MANUAL/{link}'
+
+# Include `lastmod` dates in the sitemap:
+
+sitemap_show_lastmod = True
+
+#######################
+# Template and asset locations
+#######################
+
+#html_static_path = ["_static"]
+#templates_path = ["_templates"]
+
+
+#############
+# Redirects #
+#############
+
+# To set up redirects: https://documatt.gitlab.io/sphinx-reredirects/usage.html
+# For example: 'explanation/old-name.html': '../how-to/prettify.html',
+
+# To set up redirects in the Read the Docs project dashboard:
+# https://docs.readthedocs.io/en/stable/guides/redirects.html
+
+# NOTE: If undefined, set to None, or empty,
+#       the sphinx_reredirects extension will be disabled.
+
+# redirects = {}
+
+# rediraffe_redirects = "redirects.txt"
+
+###########################
+# Link checker exceptions #
+###########################
+
+# A regex list of URLs that are ignored by 'make linkcheck'
+#
+# TODO: Remove or adjust the ACME entry after you update the contributing guide
+
+linkcheck_ignore = [
+    "http://127.0.0.1:8000",
+    "https://github.com/canonical/ACME/*",
+    "https://matrix.to/*",
+    "https://portal.azure.com/*",
+    "https://dev.mysql.com/*",
+    "https://www.mysql.com/*"
+    ]
+
+
+# A regex list of URLs where anchors are ignored by 'make linkcheck'
+
+linkcheck_anchors_ignore_for_url = [r"https://github\.com/.*"]
+
+# give linkcheck multiple tries on failure
+# linkcheck_timeout = 30
+linkcheck_retries = 3
+
+########################
+# Configuration extras #
+########################
+
+# Custom MyST syntax extensions; see
+# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
+#
+# NOTE: By default, the following MyST extensions are enabled:
+#       substitution, deflist, linkify
+
+myst_enable_extensions = set()
+
+# Enables MyST references via standard anchors
+myst_heading_anchors = 3
+
+# Custom Sphinx extensions; see
+# https://www.sphinx-doc.org/en/master/usage/extensions/index.html
+
+# NOTE: The canonical_sphinx extension is required for the starter pack.
+#       It automatically enables the following extensions:
+#       - custom-rst-roles
+#       - myst_parser
+#       - notfound.extension
+#       - related-links
+#       - sphinx_copybutton
+#       - sphinx_design
+#       - sphinx_reredirects
+#       - sphinx_tabs.tabs
+#       - sphinxcontrib.jquery
+#       - sphinxext.opengraph
+#       - terminal-output
+#       - youtube-links
+
+extensions = [
+    "canonical_sphinx",
+    "sphinxcontrib.cairosvgconverter",
+    "sphinx_last_updated_by_git",
+    "sphinx.ext.intersphinx",
+    "sphinx_sitemap",
+]
+
+# Excludes files or directories from processing
+
+exclude_patterns = [
+]
+
+# Adds custom CSS files, located under 'html_static_path'
+
+# html_css_files = []
+
+
+# Adds custom JavaScript files, located under 'html_static_path'
+
+# html_js_files = []
+
+
+# Specifies a reST snippet to be appended to each .rst file
+
+rst_epilog = """
+.. include:: /reuse/links.txt
+.. include:: /reuse/substitutions.txt
+"""
+
+# Feedback button at the top; enabled by default
+#
+# TODO: To disable the button, uncomment this.
+
+# disable_feedback_button = True
+
+
+# Your manpage URL
+#
+# TODO: To enable manpage links, uncomment and replace {codename} with required
+#       release, preferably an LTS release (e.g. noble). Do *not* substitute
+#       {section} or {page}; these will be replaced by sphinx at build time
+#
+# NOTE: If set, adding ':manpage:' to an .rst file
+#       adds a link to the corresponding man section at the bottom of the page.
+
+# manpages_url = 'https://manpages.ubuntu.com/manpages/{codename}/en/' + \
+#     'man{section}/{page}.{section}.html'
+
+
+# Specifies a reST snippet to be prepended to each .rst file
+# This defines a :center: role that centers table cell content.
+# This defines a :h2: role that styles content for use with PDF generation.
+
+rst_prolog = """
+.. role:: center
+   :class: align-center
+.. role:: h2
+    :class: hclass2
+.. role:: woke-ignore
+    :class: woke-ignore
+.. role:: vale-ignore
+    :class: vale-ignore
+"""
+
+# Workaround for https://github.com/canonical/canonical-sphinx/issues/34
+
+if "discourse_prefix" not in html_context and "discourse" in html_context:
+    html_context["discourse_prefix"] = html_context["discourse"] + "/t/"
+
+# Workaround for substitutions.yaml
+
+if os.path.exists('./reuse/substitutions.yaml'):
+    with open('./reuse/substitutions.yaml', 'r') as fd:
+        myst_substitutions = yaml.safe_load(fd.read())
+
+# Add configuration for intersphinx mapping
+
+# intersphinx_mapping = {}
diff --git a/docs/explanation.md b/docs/explanation.md
deleted file mode 100644
index 3a8eb478c8..0000000000
--- a/docs/explanation.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# Explanation
-
-Additional context about key concepts behind the MySQL charm.
-
-## Core concepts and design
-* [Architecture]
-* [Interfaces and endpoints]
-* [Juju]
-* [Legacy charm]
-
-## Operational concepts
-* [Users]
-* [Logs]
-  * [Audit logs]
-
-## Security and hardening
-* [Security hardening guide][Security]
-  * [Cryptography]
-
-<!-- Links -->
-
-[Architecture]: /t/11756
-[Interfaces and endpoints]: /t/10250
-[Juju]: /t/11959
-[Legacy charm]: /t/10788
-
-[Users]: /t/10789
-[Logs]: /t/11993
-[Audit logs]: /t/15424
-
-[Security]: /t/16784
-[Cryptography]: /t/16785
\ No newline at end of file
diff --git a/docs/explanation/e-architecture.md b/docs/explanation/architecture.md
similarity index 74%
rename from docs/explanation/e-architecture.md
rename to docs/explanation/architecture.md
index a6ab02d031..81e444f664 100644
--- a/docs/explanation/e-architecture.md
+++ b/docs/explanation/architecture.md
@@ -2,10 +2,10 @@
 
 [MySQL](https://www.mysql.com/) is the world’s most popular open source database. The "[Charmed MySQL](https://charmhub.io/mysql)" is a Juju-based operator to deploy and support MySQL from [day 0 to day 2](https://codilime.com/blog/day-0-day-1-day-2-the-software-lifecycle-in-the-cloud-age/), it is based on the [MySQL Community Edition](https://www.mysql.com/products/community/) using the built-in cluster functionality: [MySQL InnoDB ClusterSet](https://dev.mysql.com/doc/mysql-shell/8.0/en/innodb-clusterset.html).
 
-<a name="hld"></a>
 ## HLD (High Level Design)
 
 The charm design leverages on the SNAP “[charmed-mysql](https://snapcraft.io/charmed-mysql)” which is deployed by Juju on the specified VM/MAAS/bare-metal machine based on Ubuntu Jammy/22.04. SNAP allows to run MySQL service(s) in a secure and isolated environment ([strict confinement](https://ubuntu.com/blog/demystifying-snap-confinement)). The installed SNAP:
+
 ```
 > juju ssh mysql/0
 > snap list charmed-mysql
@@ -40,11 +40,11 @@ The `mysqld` snap service is a main MySQL instance which is normally up and runn
 
 The `mysql-router` snap service used in [Charmed MySQL Router](https://charmhub.io/mysql-router?channel=dpe/edge) only and should be stopped on [Charmed MySQL](https://charmhub.io/mysql) deployments.
 
-All `exporter` services are activated after the relation with [COS Monitoring](/t/9900) only.
+All `exporter` services are activated after the relation with [COS Monitoring](/how-to/monitoring-cos/enable-monitoring) only.
 
-> **:information_source: Note:** it is possible to star/stop/restart snap services manually but it is NOT recommended to avoid a split brain with a charm state machine! Do it with a caution!!!
+> **Note:** it is possible to star/stop/restart snap services manually but it is NOT recommended to avoid a split brain with a charm state machine! Do it with a caution!!!
 
-> **:warning: Important:** all snap resources must be executed under the special user `snapd_daemon` only!
+> **Important:** all snap resources must be executed under the special user `snapd_daemon` only!
 
 The snap "charmed-mysql" also ships list of tools used by charm:
 * `charmed-mysql.mysql` (alias `mysql`) - mysql client to connect `mysqld`.
@@ -54,9 +54,8 @@ The snap "charmed-mysql" also ships list of tools used by charm:
 * `charmed-mysql.xtrabackup` - a tool to backup/restore MySQL DB.
 
 The `mysql` and `mysqlsh` are well known and popular tools to manage MySQL.
-The `xtrabackup (xbcloud+xbstream)` used for [MySQL Backups](/t/9896) only to store backups on S3 compatible storage.
+The `xtrabackup (xbcloud+xbstream)` used for [MySQL Backups](/how-to/back-up-and-restore/create-a-backup) only to store backups on S3 compatible storage.
 
-<a name="integrations"></a>
 ## Integrations
 
 ### MySQL Router
@@ -81,48 +80,48 @@ The charm "[MySQL Test App](https://charmhub.io/mysql-test-app)" is a Canonical
 
 ### Grafana
 
-Grafana is an open-source visualization tools that allows to query, visualize, alert on, and visualize metrics from mixed datasources in configurable dashboards for observability. This charms is shipped with its own Grafana dashboard and supports integration with the [Grafana Operator](https://charmhub.io/grafana-k8s) to simplify observability. Please follow [COS Monitoring](/t/9900) setup.
+Grafana is an open-source visualization tools that allows to query, visualize, alert on, and visualize metrics from mixed datasources in configurable dashboards for observability. This charms is shipped with its own Grafana dashboard and supports integration with the [Grafana Operator](https://charmhub.io/grafana-k8s) to simplify observability. Please follow [COS Monitoring](/how-to/monitoring-cos/enable-monitoring) setup.
 
 ### Loki
 
-Loki is an open-source fully-featured logging system. This charms is shipped with support for the [Loki Operator](https://charmhub.io/loki-k8s) to collect the generated logs. Please follow [COS Monitoring](/t/9900) setup.
+Loki is an open-source fully-featured logging system. This charms is shipped with support for the [Loki Operator](https://charmhub.io/loki-k8s) to collect the generated logs. Please follow [COS Monitoring](/how-to/monitoring-cos/enable-monitoring) setup.
 
 ### Prometheus
 
-Prometheus is an open-source systems monitoring and alerting toolkit with a dimensional data model, flexible query language, efficient time series database and modern alerting approach. This charm is shipped with a Prometheus exporters, alerts and support for integrating with the [Prometheus Operator](https://charmhub.io/prometheus-k8s) to automatically scrape the targets. Please follow [COS Monitoring](/t/9900) setup.
+Prometheus is an open-source systems monitoring and alerting toolkit with a dimensional data model, flexible query language, efficient time series database and modern alerting approach. This charm is shipped with a Prometheus exporters, alerts and support for integrating with the [Prometheus Operator](https://charmhub.io/prometheus-k8s) to automatically scrape the targets. Please follow [COS Monitoring](/how-to/monitoring-cos/enable-monitoring) setup.
 
-<a name="lld"></a>
 ## LLD (Low Level Design)
 
-Please check the charm state machines displayed on [workflow diagrams](/t/10031). The low-level logic is mostly common for both VM and K8s charms.
+Please check the charm state machines displayed on [workflow diagrams](https://charmhub.io/mysql-k8s/docs/e-flowcharts). The low-level logic is mostly common for both VM and K8s charms.
 
 <!--- TODO: Describe all possible installations? Cross-model/controller? --->
 
-### Juju Events
+### Juju events
 
 Accordingly to the [Juju SDK](https://juju.is/docs/sdk/event): “an event is a data structure that encapsulates part of the execution context of a charm”.
 
 For this charm, the following events are observed:
 
-1. [on_install](https://juju.is/docs/sdk/install-event): install the snap "charmed-mysql" and perform basic preparations to bootstrap the cluster on the first leader (or join the already configured cluster). 
-2. [leader-elected](https://juju.is/docs/sdk/leader-elected-event): generate all the secrets to bootstrap the cluster.
-3. [leader-settings-changed](https://juju.is/docs/sdk/leader-settings-changed-event): Handle the leader settings changed event.
-4. [start](https://juju.is/docs/sdk/start-event): Init/setting up the cluster node.
-5. [config_changed](https://juju.is/docs/sdk/config-changed-event): usually fired in response to a configuration change using the GUI or CLI. Create and set default cluster and cluster-set names in the peer relation databag (on the leader only).
-6. [update-status](https://juju.is/docs/sdk/update-status-event): Takes care of workload health checks.
+1. [`on_install`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#install): install the snap "charmed-mysql" and perform basic preparations to bootstrap the cluster on the first leader (or join the already configured cluster). 
+2. [`leader-elected`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#leader-elected): generate all the secrets to bootstrap the cluster.
+3. [`leader-settings-changed`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#leader-settings-changed): Handle the leader settings changed event.
+4. [`start`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#start): Init/setting up the cluster node.
+5. [`config_changed`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#config-changed): usually fired in response to a configuration change using the GUI or CLI. Create and set default cluster and cluster-set names in the peer relation databag (on the leader only).
+6. [`update-status`](https://documentation.ubuntu.com/juju/3.6/reference/hook/#update-status): Takes care of workload health checks.
 <!--- 7. database_storage_detaching: TODO: ops? event?
 8. TODO: any other events?
 --->
 
-### Charm Code Overview
+### Charm code overview
 
-The "[src/charm.py](https://github.com/canonical/mysql-operator/blob/main/src/charm.py)" is the default entry point for a charm and has the [MySQLCharmBase](https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/mysql.py) Python class which inherits from CharmBase.
+[`src/charm.py`](https://github.com/canonical/mysql-operator/blob/main/src/charm.py) is the default entry point for a charm and has the [`MySQLCharmBase`](https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/mysql.py) Python class which inherits from `CharmBase`.
 
-CharmBase is the base class from which all Charms are formed, defined by [Ops](https://juju.is/docs/sdk/ops) (Python framework for developing charms). See more information in [Charm](https://juju.is/docs/sdk/constructs#heading--charm).
+`CharmBase` is the base class from which all Charms are formed, defined by [Ops](https://ops.readthedocs.io/en/latest/) (Python framework for developing charms). See more information in the [Ops documentation for `CharmBase`](https://ops.readthedocs.io/en/latest/reference/ops.html#ops.CharmBase).
 
 The `__init__` method guarantees that the charm observes all events relevant to its operation and handles them.
 
-The VM and K8s charm flavors shares the codebase via [charm libraries](https://juju.is/docs/sdk/libraries) in '[lib/charms/mysql/v0/](https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/)':
+The VM and K8s charm flavors shares the codebase via charm libraries in [`lib/charms/mysql/v0/`](https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/):
+
 ```
 charmcraft list-lib mysql
 Library name    API    Patch                                                                                                                                                                                                                          
@@ -130,4 +129,5 @@ backups         0      7
 mysql           0      45                                                                                                                                                                                                                             
 s3_helpers      0      4                                                                                                                                                                                                                              
 tls             0      2                                     
-```
\ No newline at end of file
+```
+
diff --git a/docs/explanation/e-users.md b/docs/explanation/e-users.md
deleted file mode 100644
index 6ba1a96fd3..0000000000
--- a/docs/explanation/e-users.md
+++ /dev/null
@@ -1,141 +0,0 @@
-# Charm Users explanations
-
-There are two types of users in MySQL:
-* Internal users (used by charm operator)
-* Relation/integration users (used by related applications)
-  * Extra user roles (if default permissions are not enough)
-
-<a name="internal-users"></a>
-## Internal users explanations:
-
-The operator uses the following internal DB users:
-
-* `root` - the [initial/default](https://charmhub.io/mysql/docs/t-manage-passwords) MySQL user. Used for very initial bootstrap and restricted to local access.
-* `clusteradmin` - the user to manage replication in the MySQL InnoDB ClusterSet.
-* `serverconfig` - the user that operates MySQL instances.
-* `monitoring` - the user for [COS integration](https://charmhub.io/mysql/docs/h-enable-monitoring).
-* `backups` - the user to [perform/list/restore backups](https://charmhub.io/mysql/docs/h-create-and-list-backups).
-* `mysql_innodb_cluster_#######` - the [internal recovery users](https://dev.mysql.com/doc/mysql-shell/8.0/en/innodb-cluster-user-accounts.html#mysql-innodb-cluster-users-created) which enable connections between the servers in the cluster. Dedicated user created for each Juju unit/InnoDB Cluster member.
-* `mysql_innodb_cs_#######` - the internal recovery user which enable connections between MySQl InnoDB Clusters in ClusterSet. One user is created for entire MySQL ClusterSet.
-
-The full list of internal users is available in charm [source code](https://github.com/canonical/mysql-operator/blob/main/src/constants.py). The full dump of internal `mysql.user` table (on newly installed charm):
-
-```shell
-mysql> select Host,User,account_locked from mysql.user;
-+-----------+---------------------------------+----------------+
-| Host      | User                            | account_locked |
-+-----------+---------------------------------+----------------+
-| %         | backups                         | N              |
-| %         | clusteradmin                    | N              |
-| %         | monitoring                      | N              |
-| %         | mysql_innodb_cluster_2277159043 | N              |
-| %         | mysql_innodb_cluster_2277159122 | N              |
-| %         | mysql_innodb_cluster_2277159949 | N              |
-| %         | mysql_innodb_cs_f8ead780        | N              |
-| %         | serverconfig                    | N              |
-| localhost | mysql.infoschema                | Y              |
-| localhost | mysql.session                   | Y              |
-| localhost | mysql.sys                       | Y              |
-| localhost | root                            | N              |
-+-----------+---------------------------------+----------------+
-10 rows in set (0.00 sec)
-```
-**Note**: it is forbidden to use/manage described above users! They are dedicated to the operators logic!
-Please use [data-integrator](https://charmhub.io/mysql/docs/t-integrations) charm to generate/manage/remove an external credentials.
-
-It is allowed to rotate passwords for *internal* users using action 'set-password'
-```shell
-> juju show-action mysql set-password
-Change the system user's password, which is used by charm. It is for internal charm users and SHOULD NOT be used by applications.
-
-Arguments
-password:
-  type: string
-  description: The password will be auto-generated if this option is not specified.
-username:
-  type: string
-  description: The username, the default value 'root'. Possible values - root,
-    serverconfig, clusteradmin.
-```
-
-For example, to generate a new random password for *internal* user:
-
-```shell
-> juju run-action --wait mysql/leader set-password username=clusteradmin
-unit-mysql-3:
-  ...
-  results: {}
-  status: completed
-
-> juju run-action --wait mysql/leader get-password username=clusteradmin
-unit-mysql-3:
-  ...
-  results:
-    password: PFLIwiwy0Pn7n7xgYtXKw39H
-    username: clusteradmin
-```from ..helpers import get_leader_unit, get_primary_unit_wrapper, retrieve_database_variable_value
-
-
-To set a predefined password for the specific user, run:
-```shell
-> juju run-action --wait mysql/leader set-password username=clusteradmin password=newpassword
-unit-mysql-0:
-  ...
-  results: {}
-  status: completed
-
-> juju run-action --wait mysql/leader get-password username=clusteradmin
-unit-mysql-3:
-  UnitId: mysql/3
-  id: "14"
-  results:
-    password: newpassword
-    username: clusteradmin
-```
-**Note**: the action `set-password` must be executed on juju leader unit (to update peer relation data with new value).
-
-<a name="relation-users"></a>
-## Relation/integration users explanations:
-
-The operator created a dedicated user for every application related/integrated with database.
-The username is composed by the relation ID and truncated uuid for the model, to ensure there is no
-username clash in cross model relations. Usernames are limited to 32 chars as per [MySQL limit](https://dev.mysql.com/doc/refman/8.0/en/user-names.html).
-Those users are removed on the juju relation/integration removal request. 
-However, DB data stays in place and can be reused on re-created relations (using new user credentials):
-
-```shell
-mysql> select Host,User,account_locked from mysql.user where User like 'relation%';
-+------+----------------------------+----------------+
-| Host | User                       | account_locked |
-+------+----------------------------+----------------+
-| %    | relation-8_99200344b67b4e9 | N              |
-| %    | relation-9_99200344b67b4e9 | N              |
-+------+----------------------------+----------------+
-2 row in set (0.00 sec)
-```
-
-The extra user(s) will be created for relation with [mysql-router](https://charmhub.io/mysql-router) charm to provide necessary users for applications related via mysql-router app:
-```shell
-mysql> select Host,User,account_locked from mysql.user where User like 'mysql_router%';
-+------+----------------------------+----------------+
-| Host | User                       | account_locked |
-+------+----------------------------+----------------+
-| %    | mysql_router1_gwa0oy6xnp8l | N              |
-+------+----------------------------+----------------+
-1 row in set (0.00 sec)
-```
-
-**Note**: If password rotation is needed for users used in relations, it is needed to remove the relation and create it again:
-```shell
-> juju remove-relation mysql myclientapp
-> juju wait-for application mysql
-> juju relate mysql myclientapp
-```
-
-
-
-<a name="admin-port"></a>
-### Admin Port User Access
-
-The charm mainly uses the `serverconfig` user for internal operations. For connections with this user, a special admin port is used (port `33062`), which enables the charm to operate MySQL even when users connections are saturated.
-For further information on the administrative connection, refer to [MySQL docs](https://dev.mysql.com/doc/refman/8.0/en/administrative-connection-interface.html) on the topic.
\ No newline at end of file
diff --git a/docs/explanation/index.md b/docs/explanation/index.md
new file mode 100644
index 0000000000..0bff3ed82c
--- /dev/null
+++ b/docs/explanation/index.md
@@ -0,0 +1,34 @@
+# Explanation
+
+Additional context about key concepts behind the MySQL charm.
+
+## Core concepts and design
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Architecture <architecture>
+Interfaces and endpoints <interfaces-and-endpoints>
+Juju <juju>
+Legacy charm <legacy-charm>
+```
+
+## Operational concepts
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Users <users>
+Logs <logs/index>
+```
+
+## Security and hardening
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Security <security/index>
+```
diff --git a/docs/explanation/e-interfaces-endpoints.md b/docs/explanation/interfaces-and-endpoints.md
similarity index 82%
rename from docs/explanation/e-interfaces-endpoints.md
rename to docs/explanation/interfaces-and-endpoints.md
index f436c9a8df..8af0c03143 100644
--- a/docs/explanation/e-interfaces-endpoints.md
+++ b/docs/explanation/interfaces-and-endpoints.md
@@ -1,5 +1,4 @@
 # Interfaces/endpoints
-> **:information_source: Hint**: Use [Juju 3](/t/5064). Otherwise replace `juju integrate` with `juju relate` for Juju 2.9.
 
 Charmed MySQL VM supports modern `mysql_client` and legacy `mysql`, `mysql-shared`, `mysql-router` interfaces (in a backward compatible mode).
 
@@ -11,7 +10,7 @@ This charm provides modern [‘mysql_client’ ](https://github.com/canonical/ch
 
 ### Modern `mysql_client` interface (`database` endpoint):
 
-Adding a relation is accomplished with `juju integrate` via endpoint `database`. Read more about [Juju relations (integrations)](https://juju.is/docs/olm/relations). Example:
+Adding a relation is accomplished with `juju integrate` via endpoint `database`. Read more about [Juju relations (integrations)](https://documentation.ubuntu.com/juju/3.6/reference/relation/). Example:
 
 ```shell
 # Deploy Charmed MySQL cluster with 3 nodes
@@ -31,19 +30,19 @@ juju status --relations
 # > mysql:database      mysql-test-app:database  mysql_client  regular
 ```
 
-Find all details about default and extra DB user roles in “[Charm Users explanations](/t/10789)”.
+Find all details about default and extra DB user roles in “[Charm Users explanations](/explanation/users)”.
 
 **Note:** In order to integrate with this charm, every table created by the integrated application must have a primary key. This is required by the [group replication plugin](https://dev.mysql.com/doc/refman/8.0/en/group-replication-requirements.html) enabled in this charm.
 
 ## Legacy relations
 
-**Note:** Legacy relations are deprecated and will be discontinued on future releases. Usage should be avoided. Check the legacy interface implementation limitations in the "[Legacy charm](/t/10788)" document.
+**Note:** Legacy relations are deprecated and will be discontinued on future releases. Usage should be avoided. Check the legacy interface implementation limitations in the "[Legacy charm](/explanation/legacy-charm)" document.
 
-This charm supports several legacy interfaces, e.g. `mysql`, `mysql-shared`, `mysql-router`. They were used in some legacy charms in [cross-model relations](https://juju.is/docs/olm/cross-model-integration).
+This charm supports several legacy interfaces, e.g. `mysql`, `mysql-shared`, `mysql-router`. They were used in some legacy charms in [cross-model relations](https://documentation.ubuntu.com/juju/3.6/reference/relation/#cross-model).
 
 ### `mysql` interface (`mysql` endpoint)
 
-It was a popular interface used by some legacy charms (e.g. "[MariaDB](https://charmhub.io/mariadb)", "[OSM MariaDB](https://charmhub.io/charmed-osm-mariadb-k8s)", "[Percona Cluster](https://charmhub.io/percona-cluster)" and "[Mysql Innodb Cluster](https://charmhub.io/mysql-innodb-cluster)"), often in [cross-model relations](https://juju.is/docs/olm/cross-model-integration):
+It was a popular interface used by some legacy charms (e.g. "[MariaDB](https://charmhub.io/mariadb)", "[OSM MariaDB](https://charmhub.io/charmed-osm-mariadb-k8s)", "[Percona Cluster](https://charmhub.io/percona-cluster)" and "[Mysql Innodb Cluster](https://charmhub.io/mysql-innodb-cluster)"), often in [cross-model relations](https://documentation.ubuntu.com/juju/3.6/reference/relation/#cross-model):
 
 ```shell
 juju deploy mysql --channel 8.0
@@ -64,7 +63,7 @@ juju integrate mysql-router keystone
 juju integrate mysql:db-router mysql-router:db-router
 ```
 
-**Note:** pay attention to deploy identical [series](https://juju.is/docs/olm/deploy-an-application-with-a-specific-series) for `keystone` and `mysql-router` applications (due to the [subordinate](https://juju.is/docs/sdk/charm-types#heading--subordinate-charms) charm nature of `mysql-router`).
+**Note:** pay attention to deploy identical [series/base](https://documentation.ubuntu.com/juju/3.6/reference/machine/#machine-base) for `keystone` and `mysql-router` applications (due to the [subordinate](https://documentation.ubuntu.com/juju/3.6/reference/charm/#subordinate) charm nature of `mysql-router`).
 
 ### `mysql-shared` interface (`shared-db` endpoint)
 
@@ -74,4 +73,5 @@ It is a relation that one uses when the application needs to connect directly to
 juju deploy mysql --channel 8.0
 juju deploy keystone --series focal
 juju integrate keystone:shared-db mysql:shared-db
-```
\ No newline at end of file
+```
+
diff --git a/docs/explanation/e-juju.md b/docs/explanation/juju.md
similarity index 70%
rename from docs/explanation/e-juju.md
rename to docs/explanation/juju.md
index 47c1d117ba..16c0f50773 100644
--- a/docs/explanation/e-juju.md
+++ b/docs/explanation/juju.md
@@ -11,12 +11,7 @@ See also:
 
 This page aims to provide some context on some of the inner workings of Juju that affect this charm.
 
-## Summary
-* [Breaking changes between Juju 2.8.x and 3.x](#heading--breaking-changes)
-* [Juju upgrades](#heading--upgrades)
-
----
-<a href="#heading--breaking-changes"><h2 id="heading--breaking-changes"> Breaking changes between Juju 2.9.x and 3.x </h2></a>
+## Breaking changes between Juju 2.9.x and 3.x
 
 As this charm documentation is written for Juju 3.x, users of 2.9.x will encounter noteworthy changes when following the instructions. This section explains those changes.
 
@@ -31,7 +26,7 @@ In the context of this guide, the pertinent changes are shown here:
 |`run`|`exec`|
 |`run-action --wait`|`run`|
 
-See the [Juju 3.0 release notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022) for the comprehensive list of changes.
+See the [Juju 3.0 release notes](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022) for the comprehensive list of changes.
 
 The response is to therefore substitute the documented command with the equivalent 2.9.x command. For example:
 
@@ -47,14 +42,14 @@ juju relate mysql:database mysql-test-app
 
 juju run-action --wait mysql/leader get-password
 ```
-[note]
+```{note}
 This section is based on the [OpenStack guide.](https://docs.openstack.org/charm-guide/latest/project/support-notes.html#breaking-changes-between-juju-2-9-x-and-3-x)
-[/note]
+```
 
-<a href="#heading--upgrades"><h2 id="heading--upgrades"> Juju  upgrades </h2></a>
-Newly released charm revisions might require a new [Juju version](/t/11421). This is usually because the new revision requires new Juju features, e.g. [Juju secrets](https://juju.is/docs/juju/secret).
+## Juju  upgrades
+Newly released charm revisions might require a new Juju version. This is usually because the new revision requires new Juju features, e.g. [Juju secrets](https://juju.is/docs/juju/secret).
 
-Information about Juju requirements will be clearly indicated in the charm's [release notes](/t/11878) and in the repository's [metadata.yaml](https://github.com/canonical/mysql-operator/blob/14c06ff88c4e564cd6d098aa213bd03e78e84b52/metadata.yaml#L72-L80) file.
+Information about Juju requirements will be clearly indicated in the charm's [release notes](/reference/releases) and in the repository's [metadata.yaml](https://github.com/canonical/mysql-operator/blob/14c06ff88c4e564cd6d098aa213bd03e78e84b52/metadata.yaml#L72-L80) file.
 
 When upgrading your database charm with <code>juju refresh</code>, Juju checks that its version is compatible with the target revision. If not, it stops the upgrade and prevents further changes to keep the installation safe. 
 
@@ -67,4 +62,5 @@ ERROR Charm feature requirements cannot be met:
       - charm requires feature "juju" (version >= 3.1.5) but model currently supports version 3.1.4
 ```
 
-You must then [upgrade to the required Juju version](/t/14325) before proceeding with the charm upgrade.
\ No newline at end of file
+You must then [upgrade to the required Juju version](/how-to/upgrade/upgrade-juju) before proceeding with the charm upgrade.
+
diff --git a/docs/explanation/e-legacy-charm.md b/docs/explanation/legacy-charm.md
similarity index 58%
rename from docs/explanation/e-legacy-charm.md
rename to docs/explanation/legacy-charm.md
index 2eb7208eb6..2b27aa9441 100644
--- a/docs/explanation/e-legacy-charm.md
+++ b/docs/explanation/legacy-charm.md
@@ -1,10 +1,13 @@
+
+# Legacy charm
+
 ## Charm types "legacy" vs "modern"
 
-Historically, there were  [several](https://juju.is/docs/sdk/charm-taxonomy#heading--charm-types-by-generation) operators/charms to provide MySQL/MariaDB functionality: "[MariaDB](https://charmhub.io/mariadb)", "[OSM MariaDB](https://charmhub.io/charmed-osm-mariadb-k8s)", "[Percona Cluster](https://charmhub.io/percona-cluster)" and "[Mysql Innodb Cluster](https://charmhub.io/mysql-innodb-cluster)". All of them are named "legacy" charms.
+Historically, there were  [several](https://documentation.ubuntu.com/juju/3.6/reference/charm/#by-generation) operators/charms to provide MySQL/MariaDB functionality: "[MariaDB](https://charmhub.io/mariadb)", "[OSM MariaDB](https://charmhub.io/charmed-osm-mariadb-k8s)", "[Percona Cluster](https://charmhub.io/percona-cluster)" and "[Mysql Innodb Cluster](https://charmhub.io/mysql-innodb-cluster)". All of them are named "legacy" charms.
 
-This "Charmed MySQL" operator is a modern "[Charmed Operator SDK](https://juju.is/docs/sdk)"-based charm to replace all legacy operators [providing](/t/charmed-mysql-k8s-explanations-interfaces-endpoints/10250) all juju-interfaces of legacy charms.
+This "Charmed MySQL" operator is a modern "[Charmed Operator SDK](https://juju.is/docs/sdk)"-based charm to replace all legacy operators providing all [interfaces/endpoints](/explanation/interfaces-and-endpoints) of legacy charms.
 
-The legacy charm provided endpoints `mysql` and `mysql-root` (for the interface `mysql`). The modern charm provides old endpoints as well + new endpoint `database` (for the interface `mysql_client`). Read more detail about the available endpoints/interfaces for [VM](https://charmhub.io/mysql/docs/e-interfaces) and [K8s](https://charmhub.io/mysql-k8s/docs/e-interfaces) charms.
+The legacy charm provided endpoints `mysql` and `mysql-root` (for the interface `mysql`). The modern charm provides old endpoints as well + new endpoint `database` (for the interface `mysql_client`). Read more detail about the available endpoints/interfaces for [VM](https://charmhub.io/mysql/integrations) and [K8s](https://charmhub.io/mysql-k8s/integrations) charms.
 
 **Note**: Please choose one endpoint to use. No need to relate all of them simultaneously!
 
@@ -25,9 +28,14 @@ The "modern" charm provides temporary support for the legacy interfaces:
     trust: true
 ```
 
-* **proper migration**: migrate the application to the new interface "[mysql_client](https://github.com/canonical/charm-relation-interfaces)". The application will connect MySQL using "[data_interfaces](https://charmhub.io/data-platform-libs/libraries/data_interfaces)" library from "[data-platform-libs](https://github.com/canonical/data-platform-libs/)" via endpoint `database`.
+* **proper migration**: migrate the application to the new interface "[`mysql_client`](https://github.com/canonical/charm-relation-interfaces)". The application will connect MySQL using "[`data_interfaces`](https://charmhub.io/data-platform-libs/libraries/data_interfaces)" library from "[`data-platform-libs`](https://github.com/canonical/data-platform-libs/)" via endpoint `database`.
+
+```{caution}
+In-place upgrades from the legacy charm to the modern, Ops-based charm are **not supported**.
 
-**Warning**: NO in-place upgrades possible! Legacy charm cannot be upgraded to Operator-framework-based one. To move DB data, the second/modern DB application must be launched nearby and data should be copied from "legacy" application to the "modern" one. Canonical Data Platform team will prepare the copy&paste guide. Please [contact us](https://chat.charmhub.io/charmhub/channels/data-platform) if you need migration instructions.
+
+To migrate database data, the legacy and modern MySQL charms must both be running simultaneously. The data can then be copied from the legacy application to the modern one. Please [contact us](/reference/contacts) if you need help with data migration.
+```
 
 ## How to deploy old "legacy" mysql charm
 
@@ -46,14 +54,15 @@ Deploy the charm using the proper charm/channel `latest/stable`:
 ## Supported MySQL versions by modern charm
 
 At the moment, both K8s and VM modern charms support MySQL 8.0 (based on Jammy/22.04 series) only.
-Please [contact us](https://chat.charmhub.io/charmhub/channels/data-platform) if you need different versions/series.
+Please [contact us](/reference/contacts) if you need different versions/series.
 
 ## Supported architectures: amd64, arm64, ...
 
-Currently, the charm supports architecture `amd64` only. See the technical details in “[Supported architectures](/t/11742)”.
+Currently, the charm supports architecture `amd64` only. See the technical details in “[Supported architectures](/reference/system-requirements)”.
 
 ## How to report issues and contact authors
 
 The "modern charm" (from `8.0/stable`) is stored on [GitHub](https://github.com/canonical/mysql-operator), here is the link to report [modern charm issues](https://github.com/canonical/mysql-operator/issues/new/choose).
 
-Do you have questions? [Contact us](https://chat.charmhub.io/charmhub/channels/data-platform)!
\ No newline at end of file
+Do you have questions? [Contact us](/reference/contacts)!
+
diff --git a/docs/explanation/e-audit-logs.md b/docs/explanation/logs/audit-logs.md
similarity index 90%
rename from docs/explanation/e-audit-logs.md
rename to docs/explanation/logs/audit-logs.md
index 0fae7323cb..3db149ee8e 100644
--- a/docs/explanation/e-audit-logs.md
+++ b/docs/explanation/logs/audit-logs.md
@@ -13,7 +13,7 @@ The following is a sample of the audit logs, with format json with only logins r
 
 The logs are stored in the `/var/snap/charmed-mysql/common/var/log/mysql` directory, and it's rotated
 every minute to the `/var/snap/charmed-mysql/common/var/log/mysql/archive_audit` directory.
-It's recommended to integrate the charm with [COS](/t/9900), from where the logs can be easily persisted and queried using Loki/Grafana.
+It's recommended to integrate the charm with [COS](/how-to/monitoring-cos/enable-monitoring), from where the logs can be easily persisted and queried using Loki/Grafana.
 
 ## Configurations
 
@@ -37,4 +37,5 @@ It's recommended to integrate the charm with [COS](/t/9900), from where the logs
     ```bash
     juju config mysql plugin-audit-strategy=semi-async
     ```
-    Valid values are `async` and `semi-async`.
\ No newline at end of file
+    Valid values are `async` and `semi-async`.
+
diff --git a/docs/explanation/e-logs.md b/docs/explanation/logs/index.md
similarity index 98%
rename from docs/explanation/e-logs.md
rename to docs/explanation/logs/index.md
index 41c64de6b6..434c25b73f 100644
--- a/docs/explanation/e-logs.md
+++ b/docs/explanation/logs/index.md
@@ -7,16 +7,6 @@ The charm currently has audit and error logs enabled by default. All of these fi
 present into a separate dedicated archive folder under the logs directory.
 We do not yet support the rotation of binary logs (binlog, relay log, undo log, redo log, etc).
 
-## Summary
-
-* [Log types](#log-types)
-* [Audit logs](#audit-logs)
-* [Error logs](#error-logs)
-* [Log rotation configuration](#log-rotation-configuration)
-* [High Level Design](#high-level-design)
-
----
-
 ## Log types
 
 The charm stores its logs in `/var/snap/charmed-mysql/common/var/log/mysql`.
@@ -175,5 +165,13 @@ for the duration of the event handler.
 
 <!-- LINKS -->
 
-[COS integration]: /t/9900
-[Audit Logs explanation]: /t/15424
\ No newline at end of file
+[COS integration]: /how-to/monitoring-cos/enable-monitoring
+[Audit Logs explanation]: /explanation/logs/audit-logs
+
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Audit logs <audit-logs>
+```
diff --git a/docs/explanation/e-cryptography.md b/docs/explanation/security/cryptography.md
similarity index 99%
rename from docs/explanation/e-cryptography.md
rename to docs/explanation/security/cryptography.md
index 3ee5b2884e..3fefdbb45b 100644
--- a/docs/explanation/e-cryptography.md
+++ b/docs/explanation/security/cryptography.md
@@ -1,3 +1,4 @@
+
 # Cryptography
 
 This document describes the cryptography used by Charmed MySQL.
@@ -58,4 +59,5 @@ An internal user is used for this authentication with its hashed password stored
 
 Authentication to MySQL Router is based on the [caching_sha2_password auth plugin](https://dev.mysql.com/doc/refman/8.0/en/caching-sha2-pluggable-authentication.html).
 
-Credentials are exchanged via [Juju secrets](https://canonical-juju.readthedocs-hosted.com/en/latest/user/howto/manage-secrets/).
\ No newline at end of file
+Credentials are exchanged via [Juju secrets](https://canonical-juju.readthedocs-hosted.com/en/latest/user/howto/manage-secrets/).
+
diff --git a/docs/explanation/e-security.md b/docs/explanation/security/index.md
similarity index 94%
rename from docs/explanation/e-security.md
rename to docs/explanation/security/index.md
index 90ddb508b3..1e10e0741a 100644
--- a/docs/explanation/e-security.md
+++ b/docs/explanation/security/index.md
@@ -1,3 +1,4 @@
+
 # Security hardening guide
 
 This document provides an overview of security features and guidance for hardening the security of [Charmed MySQL](https://charmhub.io/mysql) deployments, including setting up and managing a secure environment.
@@ -16,14 +17,14 @@ Charmed MySQL can be deployed on top of several clouds and virtualisation layers
 | Cloud              | Security guides                                                                                                                                                                                                                                                                                                                                   |
 |--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | OpenStack | [OpenStack Security Guide](https://docs.openstack.org/security-guide/)                                                                                                                                                                                                                                                                    |
-| AWS           | [Best Practices for Security, Identity and Compliance](https://aws.amazon.com/architecture/security-identity-compliance), [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html#access-keys-and-secret-access-keys) | 
+| AWS           | [Best Practices for Security, Identity and Compliance](https://aws.amazon.com/architecture/security-identity-compliance), [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html) | 
 | Azure              | [Azure security best practices and patterns](https://learn.microsoft.com/en-us/azure/security/fundamentals/best-practices-and-patterns), [Managed identities for Azure resource](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/)                                                     |
 | GCP         |  [Google security overview](https://cloud.google.com/kubernetes-engine/docs/concepts/security-overview), [Harden your cluster's security](https://cloud.google.com/kubernetes-engine/docs/concepts/security-overview)                                                    |
 
 ### Juju 
 
 Juju is the component responsible for orchestrating the entire lifecycle, from deployment to Day 2 operations. For more information on Juju security hardening, see the
-[Juju security page](/t/juju-security/15684) and the [How to harden your deployment](https://juju.is/docs/juju/harden-your-deployment) guide.
+[Juju security page](https://documentation.ubuntu.com/juju/latest/explanation/juju-security/index.html) and the [How to harden your deployment](https://documentation.ubuntu.com/juju/3.6/howto/manage-your-deployment/#harden-your-deployment) guide.
 
 #### Cloud credentials
 
@@ -62,7 +63,7 @@ Charmed MySQL operator and Charmed MySQL Router operator install a pinned revisi
 
 New versions (revisions) of charmed operators can be released to upgrade workloads, the operator's code, or both. It is important to refresh the charm regularly to make sure the workload is as secure as possible.
 
-For more information on upgrading the charm, see the [How to upgrade MySQL](https://canonical.com/data/docs/mysql/iaas/h-upgrade) and [How to upgrade MySQL Router](https://charmhub.io/mysql-router/docs/h-upgrade-intro?channel=dpe/edge) guides, as well as the [Release notes](https://canonical.com/data/docs/mysql/iaas/r-releases).
+For more information on upgrading the charm, see the [How to upgrade MySQL](https://canonical.com/data/docs/mysql/iaas/h-upgrade) and [How to upgrade MySQL Router](https://charmhub.io/mysql-router/docs/h-upgrade?channel=dpe/edge) guides, as well as the [Release notes](https://canonical.com/data/docs/mysql/iaas/r-releases).
 
 ### Encryption
 
@@ -86,4 +87,13 @@ The Audit log plugin is enabled by default and produces login/logout logs. See t
 
 ## Additional Resources
 
-For details on the cryptography used by Charmed MySQL, see the [Cryptography](https://discourse.charmhub.io/t/charmed-mysql-explanations-cryptography/16785) explanation page.
\ No newline at end of file
+For details on the cryptography used by Charmed MySQL, see the [Cryptography](https://discourse.charmhub.io/t/charmed-mysql-explanations-cryptography/16785) explanation page.
+
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+:hidden:
+
+cryptography
+```
diff --git a/docs/explanation/users.md b/docs/explanation/users.md
new file mode 100644
index 0000000000..3dc949a90c
--- /dev/null
+++ b/docs/explanation/users.md
@@ -0,0 +1,100 @@
+# Users
+
+There are two main types of users in MySQL:
+
+* **Internal users**, used by the charm operator
+* **Relation users**, used by related (integrated) applications
+  * **Extra user roles** if the default permissions are not enough
+
+## Internal users
+
+The operator uses the following internal database users:
+
+* `root` - the initial/default MySQL user. Used for very initial bootstrap and restricted to local access.
+* `clusteradmin` - the user to manage replication in the MySQL InnoDB ClusterSet.
+* `serverconfig` - the user that operates MySQL instances.
+* `monitoring` - the user for [COS integration](/how-to/monitoring-cos/enable-monitoring).
+* `backups` - the user to [perform/list/restore backups](/how-to/back-up-and-restore/create-a-backup).
+* `mysql_innodb_cluster_#######` - the [internal recovery users](https://dev.mysql.com/doc/mysql-shell/8.0/en/innodb-cluster-user-accounts.html#mysql-innodb-cluster-users-created) which enable connections between the servers in the cluster. Dedicated user created for each Juju unit/InnoDB Cluster member.
+* `mysql_innodb_cs_#######` - the internal recovery user which enable connections between MySQl InnoDB Clusters in ClusterSet. One user is created for entire MySQL ClusterSet.
+
+The full list of internal users is available in charm [source code](https://github.com/canonical/mysql-operator/blob/main/src/constants.py).
+
+```{caution}
+It is forbidden to manage internal users, as they are dedicated to the operator’s logic.
+
+Use the [data-integrator](https://charmhub.io/data-integrator) charm to generate, manage, and remove external credentials.
+```
+
+Example of internal `mysql.user` table on a newly installed charm:
+
+```shell
+mysql> select Host,User,account_locked from mysql.user;
++-----------+---------------------------------+----------------+
+| Host      | User                            | account_locked |
++-----------+---------------------------------+----------------+
+| %         | backups                         | N              |
+| %         | clusteradmin                    | N              |
+| %         | monitoring                      | N              |
+| %         | mysql_innodb_cluster_2277159043 | N              |
+| %         | mysql_innodb_cluster_2277159122 | N              |
+| %         | mysql_innodb_cluster_2277159949 | N              |
+| %         | mysql_innodb_cs_f8ead780        | N              |
+| %         | serverconfig                    | N              |
+| localhost | mysql.infoschema                | Y              |
+| localhost | mysql.session                   | Y              |
+| localhost | mysql.sys                       | Y              |
+| localhost | root                            | N              |
++-----------+---------------------------------+----------------+
+10 rows in set (0.00 sec)
+```
+
+Passwords for *internal* users can be rotated using the action `set-password` on the juju leader unit.
+
+```{seealso}
+[How to manage passwords](/how-to/manage-passwords)
+```
+
+## Relation users
+
+The operator created a dedicated user for every application related/integrated with database. The username is composed by the relation ID and truncated uuid for the model, to ensure there is no username clash in cross model relations. Usernames are limited to 32 chars as per [MySQL limit](https://dev.mysql.com/doc/refman/8.0/en/user-names.html).
+
+Relation users are removed on the juju relation/integration removal request. However, database data stays in place and can be reused on re-created relations (using new user credentials):
+
+```shell
+mysql> select Host,User,account_locked from mysql.user where User like 'relation%';
++------+----------------------------+----------------+
+| Host | User                       | account_locked |
++------+----------------------------+----------------+
+| %    | relation-8_99200344b67b4e9 | N              |
+| %    | relation-9_99200344b67b4e9 | N              |
++------+----------------------------+----------------+
+2 row in set (0.00 sec)
+```
+
+The extra user(s) will be created for relation with [mysql-router](https://charmhub.io/mysql-router) charm to provide necessary users for applications related via the `mysql-router` app:
+
+```shell
+mysql> select Host,User,account_locked from mysql.user where User like 'mysql_router%';
++------+----------------------------+----------------+
+| Host | User                       | account_locked |
++------+----------------------------+----------------+
+| %    | mysql_router1_gwa0oy6xnp8l | N              |
++------+----------------------------+----------------+
+1 row in set (0.00 sec)
+```
+
+To rotate passwords for relation users, remove the relation and re-relate:
+
+```shell
+juju remove-relation mysql myclientapp
+juju wait-for application mysql
+juju relate mysql myclientapp
+```
+
+### Admin port user access
+
+The charm mainly uses the `serverconfig` user for internal operations. For connections with this user, a special admin port is used (port `33062`), which enables the charm to operate MySQL even when users connections are saturated.
+
+For further information on the administrative connection, refer to [MySQL docs](https://dev.mysql.com/doc/refman/8.0/en/administrative-connection-interface.html) on the topic.
+
diff --git a/docs/how-to.md b/docs/how-to.md
deleted file mode 100644
index 7fed0469b6..0000000000
--- a/docs/how-to.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# How-to guides
-
-Key processes and common tasks for managing and using Charmed MySQL on machines.
-
-## Deployment and setup
-
-Guidance for different cloud services:
-* [Sunbeam]
-* [LXD]
-* [MAAS]
-* [AWS EC2]
-* [GCE]
-* [Azure]
-* [Multi-AZ]
-
-Specific deployment scenarios and architectures:
-
-* [Terraform]
-* [Air-gapped]
-
-## Usage and maintenance
-* [Integrate with another application]
-* [External network access]
-* [Scale replicas]
-* [Enable TLS]
-
-## Back up and restore
-* [Configure S3 AWS]
-* [Configure S3 RadosGW]
-* [Create a backup]
-* [Restore a backup]
-* [Migrate a cluster]
-
-## Monitoring (COS)
-* [Enable monitoring]
-* [Enable alert rules]
-* [Enable tracing]
-
-## Upgrades
-See the [Upgrades landing page] for more details.
-* [Upgrade Juju]
-* [Perform a minor upgrade]
-* [Perform a minor rollback]
-
-## Cross-regional (cluster-cluster) async replication
-* [Deploy]
-* [Clients]
-* [Switchover / Failover]
-* [Recovery]
-* [Removal]
-
-## Development
-* [Integrate with your charm]
-* [Migrate data via mysqldump]
-* [Migrate data via mydumper]
-* [Migrate data via backup/restore]
-* [Troubleshooting]
-
-
-<!--Links-->
-
-[Sunbeam]: /t/15986
-[LXD]: /t/11870
-[MAAS]: /t/13900
-[AWS EC2]: /t/15718
-[GCE]: /t/15723
-[Azure]: /t/15859
-[Multi-AZ]: /t/15823
-[Terraform]: /t/14925
-[Air-gapped]: /t/15747
-
-[Integrate with another application]: /t/9902
-[External network access]: /t/15801
-[Scale replicas]: /t/9904
-[Enable TLS]: /t/9898
-
-[Configure S3 AWS]: /t/9894
-[Configure S3 RadosGW]: /t/10318
-[Create a backup]: /t/9896
-[Restore a backup]: /t/9908
-[Migrate a cluster]: /t/9906
-
-[Enable monitoring]: /t/9900
-[Enable alert rules]: /t/15486
-[Enable tracing]: /t/14350
-
-[Upgrades landing page]: /t/11745
-[Upgrade Juju]: /t/14325
-[Perform a minor upgrade]: /t/11748
-[Perform a minor rollback]: /t/11749
-
-[Integrate with your charm]: /t/11890
-[Migrate data via mysqldump]: /t/11958
-[Migrate data via mydumper]: /t/11988
-[Migrate data via backup/restore]: /t/12008
-[Troubleshooting]: /t/11891
-
-[Deploy]: /t/14169
-[Clients]: /t/14170
-[Switchover / Failover]: /t/14171
-[Recovery]: /t/14172
-[Removal]: /t/14174
\ No newline at end of file
diff --git a/docs/how-to/h-configure-s3-aws.md b/docs/how-to/back-up-and-restore/configure-s3-aws.md
similarity index 62%
rename from docs/how-to/h-configure-s3-aws.md
rename to docs/how-to/back-up-and-restore/configure-s3-aws.md
index b04317caa3..f3b0d5e52a 100644
--- a/docs/how-to/h-configure-s3-aws.md
+++ b/docs/how-to/back-up-and-restore/configure-s3-aws.md
@@ -1,12 +1,17 @@
-[note]
-**Note**: All commands are written for `juju >= v.3.0`
+# Configure S3 for AWS
 
-If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
+Charmed MySQL backups can be stored on any S3 compatible storage. S3 access and configurations are managed with the [`s3-integrator` charm](https://charmhub.io/s3-integrator). 
 
-# Configure S3 for AWS
+This guide will teach you how to deploy and configure the s3-integrator charm for [AWS S3](https://aws.amazon.com/s3/), send the configuration to a Charmed MySQL application, and update it. 
+
+```{seealso}
+[](/how-to/back-up-and-restore/configure-s3-radosgw)
+```
+
+## Set up `s3-integrator`
+
+Deploy and configure the `s3-integrator` charm for AWS S3:
 
-Charmed MySQL backup can be stored on any S3 compatible storage. The S3 access and configurations are managed with the [s3-integrator charm](https://charmhub.io/s3-integrator). Deploy and configure the s3-integrator charm for **[AWS S3](https://aws.amazon.com/s3/)** (click [here](/t/charmed-mysql-how-to-configure-s3-for-radosgw/10318) to backup on Ceph via RadosGW):
 ```shell
 juju deploy s3-integrator
 juju run s3-integrator/leader sync-s3-credentials access-key=<access-key-here> secret-key=<secret-key-here>
@@ -16,18 +21,20 @@ juju config s3-integrator \
     path="/mysql-test" \
     region="us-west-2"
 ```
-[note] 
+
+```{note} 
 The amazon S3 endpoint must be specified as `s3.<region>.amazonaws.com ` within the first 24 hours of creating the bucket. For older buckets, the endpoint `s3.amazonaws.com` can be used.
 
 See [this post](https://repost.aws/knowledge-center/s3-http-307-response) for more information. 
-[/note]
+```
 
 To pass these configurations to Charmed MySQL, relate the two applications:
+
 ```shell
 juju integrate s3-integrator mysql
 ```
 
-You can create/list/restore backups now:
+You can create, list, and restore backups now:
 
 ```shell
 juju run mysql/leader list-backups
@@ -36,9 +43,11 @@ juju run mysql/leader list-backups
 juju run mysql/leader restore backup-id=<backup-id-here>
 ```
 
-You can also update your S3 configuration options after relating, using:
+You can also update your S3 configuration options after relating:
+
 ```shell
 juju config s3-integrator <option>=<value>
 ```
 
-The s3-integrator charm [accepts many configurations](https://charmhub.io/s3-integrator/configure) - enter whatever configurations are necessary for your S3 storage.
\ No newline at end of file
+The s3-integrator charm [accepts many configurations](https://charmhub.io/s3-integrator/configure) - enter whatever configurations are necessary for your S3 storage.
+
diff --git a/docs/how-to/h-configure-s3-radosgw.md b/docs/how-to/back-up-and-restore/configure-s3-radosgw.md
similarity index 70%
rename from docs/how-to/h-configure-s3-radosgw.md
rename to docs/how-to/back-up-and-restore/configure-s3-radosgw.md
index f7e3e1ebe7..0bb878beff 100644
--- a/docs/how-to/h-configure-s3-radosgw.md
+++ b/docs/how-to/back-up-and-restore/configure-s3-radosgw.md
@@ -1,29 +1,32 @@
-[note]
-**Note**: All commands are written for `juju >= v.3.0`
-
-If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
-
 # Configure S3 for RadosGW
 
-A MySQL backup can be stored on any S3-compatible storage. S3 access and configurations are managed with the [s3-integrator charm](https://charmhub.io/s3-integrator).
+Charmed MySQL backups can be stored on any S3-compatible storage. S3 access and configurations are managed with the [s3-integrator charm](https://charmhub.io/s3-integrator).
 
 This guide will teach you how to deploy and configure the s3-integrator charm on Ceph via [RadosGW](https://docs.ceph.com/en/quincy/man/8/radosgw/), send the configuration to a Charmed MySQL application, and update it. 
-> For AWS, see the guide [How to configure S3 for AWS](/t/9681)
 
-## Configure s3-integrator
+```{seealso}
+[](/how-to/back-up-and-restore/configure-s3-aws)
+```
+
+## Configure `s3-integrator`
+
 First, install the MinIO client and create a bucket:
+
 ```shell
 mc config host add dest https://radosgw.mycompany.fqdn <access-key> <secret-key> --api S3v4 --lookup path
 mc mb dest/backups-bucket
 ```
+
 Then, deploy and run the charm:
+
 ```shell
 juju deploy s3-integrator
 juju run s3-integrator/leader sync-s3-credentials access-key=<access-key> secret-key=<secret-key>
 ```
+
 Lastly, use `juju config` to add your configuration parameters. For example:
-```
+
+```shell
 juju config s3-integrator \
     endpoint="https://radosgw.mycompany.fqdn" \
     bucket="backups-bucket" \
@@ -35,12 +38,14 @@ juju config s3-integrator \
 
 ## Integrate with Charmed MySQL
 
-To pass these configurations to Charmed PostgreSQL, integrate the two applications:
+To pass these configurations to Charmed MySQL, integrate the two applications:
+
 ```shell
 juju integrate s3-integrator mysql
 ```
 
 You can create, list, and restore backups now:
+
 ```shell
 juju run mysql/leader list-backups
 juju run mysql/leader create-backup
@@ -48,8 +53,11 @@ juju run mysql/leader list-backups
 juju run mysql/leader restore backup-id=<backup-id-here>
 ```
 
-You can also update your S3 configuration options after integrating using
+You can also update your S3 configuration options after integrating:
+
 ```shell
 juju config s3-integrator <option>=<value>
 ```
-The s3-integrator charm [accepts many configurations](https://charmhub.io/s3-integrator/configure) - enter whatever configurations are necessary for your S3 storage.
\ No newline at end of file
+
+The s3-integrator charm [accepts many configurations](https://charmhub.io/s3-integrator/configure) - enter whatever configurations are necessary for your S3 storage.
+
diff --git a/docs/how-to/h-create-backup.md b/docs/how-to/back-up-and-restore/create-a-backup.md
similarity index 74%
rename from docs/how-to/h-create-backup.md
rename to docs/how-to/back-up-and-restore/create-a-backup.md
index 0b434df93e..4dacdb2497 100644
--- a/docs/how-to/h-create-backup.md
+++ b/docs/how-to/back-up-and-restore/create-a-backup.md
@@ -1,17 +1,11 @@
-[note]
-**Note**: All commands are written for `juju >= v.3.0`
-
-If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
-
 # How to create and list backups
 
 This guide contains recommended steps and useful commands for creating and managing backups to ensure smooth restores.
 
 ## Prerequisites
-* A [deployed](/t/9904) MySQL cluster
+* A [deployed](/how-to/scale-replicas) MySQL cluster
 * Access to S3 storage
-* [Configured settings for S3 storage](/t/9894)
+* [Configured settings for S3 storage](/how-to/back-up-and-restore/configure-s3-aws)
 
 ---
 
@@ -29,4 +23,5 @@ Otherwise, you must run the `create-backup` action on a non-primary unit. To fin
 You can list your available, failed, and in progress backups by running the `list-backups` command:
 ```shell
 juju run mysql/leader list-backups
-```
\ No newline at end of file
+```
+
diff --git a/docs/how-to/back-up-and-restore/index.md b/docs/how-to/back-up-and-restore/index.md
new file mode 100644
index 0000000000..8e9cb81d1c
--- /dev/null
+++ b/docs/how-to/back-up-and-restore/index.md
@@ -0,0 +1,12 @@
+# Back up and restore
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Configure S3 AWS <configure-s3-aws>
+Configure S3 RadosGW <configure-s3-radosgw>
+Create a backup <create-a-backup>
+Restore a backup <restore-a-backup>
+Migrate a cluster <migrate-a-cluster>
+```
diff --git a/docs/how-to/h-migrate-cluster.md b/docs/how-to/back-up-and-restore/migrate-a-cluster.md
similarity index 55%
rename from docs/how-to/h-migrate-cluster.md
rename to docs/how-to/back-up-and-restore/migrate-a-cluster.md
index 7a3625fb7e..c22c5d55fa 100644
--- a/docs/how-to/h-migrate-cluster.md
+++ b/docs/how-to/back-up-and-restore/migrate-a-cluster.md
@@ -1,28 +1,27 @@
-[note]
-**Note**: All commands are written for `juju >= v.3.0`
-
-If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
-
 # How to migrate a cluster
 
-This is a How-To for how to restore a backup that was made from a different cluster, (i.e. cluster migration via restore).
+This guide describes how to restore a backup that was made from a different cluster, (i.e. cluster migration via restore).
 
-To perform a basic restore from a *local* backup, please reference the [Restore How-To](/t/9908).
+```{seealso}
+To perform a basic restore from a *local* backup, see [](/how-to/back-up-and-restore/restore-a-backup).
+```
 
 ## Prerequisites
-Restoring a backup from a previous cluster to a current cluster requires that you:
+
 - Have a single unit Charmed MySQL deployed and running
 - Access to S3 storage
-- [Have configured settings for S3 storage](/t/9894)
+- [Have configured settings for S3 storage](/how-to/back-up-and-restore/configure-s3-aws)
 - Have the backups from the previous cluster in your S3-storage
 - Have the passwords from your previous cluster
 
 ---
 
-<a href="#heading--manage-cluster-passwords"><h2 id="heading--manage-cluster-passwords">Manage cluster passwords</h2></a>
+## Manage cluster passwords
+
+When you restore a backup from an old cluster, it will restore the password from the previous cluster to your current cluster.
+
+ Set the password of your current cluster to the previous cluster’s password:
 
-When you restore a backup from an old cluster, it will restore the password from the previous cluster to your current cluster. Set the password of your current cluster to the previous cluster’s password:
 ```shell
 juju run mysql/leader set-password username=root password=<previous cluster password>
 juju run mysql/leader set-password username=clusteradmin password=<previous cluster password>
@@ -32,23 +31,27 @@ juju run mysql/leader set-password username=serverconfig password=<previous clus
 ## List backups
 
 To view the available backups to restore you can enter the command `list-backups`:
+
 ```shell
 juju run mysql/leader list-backups
 ```
 
 This shows a list of the available backups (it is up to you to identify which `backup-id` corresponds to the previous-cluster):
+
 ```shell
-    backups: |-
-      backup-id             | backup-type  | backup-status
-      ----------------------------------------------------
-      YYYY-MM-DDTHH:MM:SSZ  | physical     | finished
+backups: |-
+  backup-id             | backup-type  | backup-status
+  ----------------------------------------------------
+  YYYY-MM-DDTHH:MM:SSZ  | physical     | finished
 ```
 
 ## Restore backup
 
 To restore your current cluster to the state of the previous cluster, run the `restore` command and pass the correct `backup-id` to the command:
+
  ```shell
 juju run mysql/leader restore backup-id=YYYY-MM-DDTHH:MM:SSZ
 ```
 
-Your restore will then be in progress, once it is complete your cluster will represent the state of the previous cluster.
\ No newline at end of file
+Your restore will then be in progress, once it is complete your cluster will represent the state of the previous cluster.
+
diff --git a/docs/how-to/h-restore-backup.md b/docs/how-to/back-up-and-restore/restore-a-backup.md
similarity index 62%
rename from docs/how-to/h-restore-backup.md
rename to docs/how-to/back-up-and-restore/restore-a-backup.md
index 3671113916..15e8e1085f 100644
--- a/docs/how-to/h-restore-backup.md
+++ b/docs/how-to/back-up-and-restore/restore-a-backup.md
@@ -1,55 +1,44 @@
-[note]
-**Note**: All commands are written for `juju >= v3.0`
-
-If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
-
 # How to restore a local backup
 
-This is a How-To for performing a basic restore (restoring a locally made backup).
-To restore a backup that was made from the a *different* cluster, (i.e. cluster migration via restore), please reference the [Cluster Migration via Restore How-To](/t/9906):
+This is a guide for performing a basic restore (restoring a locally made backup).
+
+To restore a backup that was made from the a *different* cluster, (i.e. cluster migration via restore), see [](/how-to/back-up-and-restore/migrate-a-cluster).
 
 ## Prerequisites
 
-- [Scale-down to the single MySQL unit (scale it up after the backup is restored).](/t/9904)
+- [Scale-down to the single MySQL unit (scale it up after the backup is restored).](/how-to/scale-replicas)
 - Access to S3 storage
-- [Have configured settings for S3 storage](/t/9894)
-- [Have existing backups in your S3-storage](/t/9896)
+- [Have configured settings for S3 storage](/how-to/back-up-and-restore/configure-s3-aws)
+- [Have existing backups in your S3-storage](/how-to/back-up-and-restore/create-a-backup)
 - Point-in-time recovery requires the following MySQL charm revisions:
-  * 369+ for `arm64`
-  * 368+ for `amd64`
-
-## Summary
-
-* [List backups](#list-backups)
-* [Point-in-time recovery](#point-in-time-recovery)
-* [Restore backup](#restore-backup)
-
----
+  * rev369+ for `arm64`
+  * rev368+ for `amd64`
 
 ## List backups
 
 To view the available backups to restore you can enter the command `list-backups`:
+
 ```shell
 juju run mysql/leader list-backups
 ```
 
 This should show your available backups
 ```shell
-    backups: |-
-      backup-id             | backup-type  | backup-status
-      ----------------------------------------------------
-      YYYY-MM-DDTHH:MM:SSZ  | physical     | finished
+backups: |-
+  backup-id             | backup-type  | backup-status
+  ----------------------------------------------------
+  YYYY-MM-DDTHH:MM:SSZ  | physical     | finished
 ```
 
+(point-in-time-recovery)=
 ## Point-in-time recovery
 
 Point-in-time recovery (PITR) is a MySQL feature that enables restorations to the database state at specific points in time. The feature is enabled by default when there's a working relation with S3 storage.
 
-
-## Restore backup
+## Restore a backup
 
 To restore a backup from that list, run the `restore` command and pass the `backup-id` to restore:
+
  ```shell
 juju run mysql/leader restore backup-id=YYYY-MM-DDTHH:MM:SSZ
 ```
@@ -68,4 +57,5 @@ It’s also possible to restore to the latest point from a specific timeline by
 
  ```shell
 juju run mysql/leader restore restore-to-time=latest
-```
\ No newline at end of file
+```
+
diff --git a/docs/how-to/h-contribute.md b/docs/how-to/contribute.md
similarity index 76%
rename from docs/how-to/h-contribute.md
rename to docs/how-to/contribute.md
index 5bb2d0b7bc..a58933f105 100644
--- a/docs/how-to/h-contribute.md
+++ b/docs/how-to/contribute.md
@@ -1,16 +1,16 @@
-[note type="caution"]
-:construction: This page is under construction! More details for each section coming soon.
-[/note]
-
 # How to contribute
 
+```{caution}
+This page is under construction! More details for each section coming soon.
+```
+
 Charmed MySQL is an open-source project that warmly welcomes community contributions, suggestions, fixes and constructive feedback.
 
 This page explains the processes and practices recommended for contributing to this charm's code and documentation.
 
 ## Submit a bug or issue 
 * Report software issues or feature requests through [**GitHub**](https://github.com/canonical/mysql-operator/issues)
-* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
+* Report security issues through [**Launchpad**](https://launchpad.net/mysql)
 
 ## Contribute to the code
 
@@ -20,7 +20,7 @@ If you would like to chat with us about your use-cases or proposed implementatio
 
 ### Tips for a good contribution
 
-* Familliarize yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library.
+* Familiarize yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library.
 * All contributions require review before being merged. Code review typically examines
   * Code quality
   * Test coverage
@@ -30,4 +30,5 @@ If you would like to chat with us about your use-cases or proposed implementatio
 
 There are several ways to contribute to the documentation:
 * Writing a comment on Discourse
-* Submitting an [issue](https://github.com/canonical/mysql-operator/issues) on GitHub with the `documentation` label
\ No newline at end of file
+* Submitting an [issue](https://github.com/canonical/mysql-operator/issues) on GitHub with the `documentation` label
+
diff --git a/docs/how-to/h-async-clients.md b/docs/how-to/cross-regional-async-replication/clients.md
similarity index 85%
rename from docs/how-to/h-async-clients.md
rename to docs/how-to/cross-regional-async-replication/clients.md
index 2870c7ea18..af6dcc9b7f 100644
--- a/docs/how-to/h-async-clients.md
+++ b/docs/how-to/cross-regional-async-replication/clients.md
@@ -1,9 +1,11 @@
-# Clients for Async replication
+# Clients
 
 ## Pre-requisites
-Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/t/14169)!
 
-## Offer and consume DB endpoints
+Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/how-to/cross-regional-async-replication/deploy)!
+
+## Offer and consume database endpoints
+
 ```shell
 juju switch rome
 juju offer db1:database db1-database
@@ -17,6 +19,7 @@ juju consume lisbon.db2-database
 ```
 
 ## Internal Juju app/clients
+
 ```shell
 juju switch app
 
@@ -28,6 +31,7 @@ juju relate mysql-router db1-database
 ```
 
 ## External Juju clients
+
 ```shell
 juju switch app
 
@@ -38,4 +42,5 @@ juju relate data-integrator mysql-router-external
 juju relate mysql-router-external db1-database
 
 juju run data-integrator/leader get-credentials
-```
\ No newline at end of file
+```
+
diff --git a/docs/how-to/h-async-deployment.md b/docs/how-to/cross-regional-async-replication/deploy.md
similarity index 90%
rename from docs/how-to/h-async-deployment.md
rename to docs/how-to/cross-regional-async-replication/deploy.md
index 7e864cd9b4..b55fe47ad9 100644
--- a/docs/how-to/h-async-deployment.md
+++ b/docs/how-to/cross-regional-async-replication/deploy.md
@@ -1,4 +1,4 @@
-# Deploy Async replication
+# Deploy async replication
 
 The following table shows the source and target controller/model combinations that are currently supported:
 
@@ -11,6 +11,7 @@ The following table shows the source and target controller/model combinations th
 ## Deploy
 
 Deploy two MySQL Clusters, named `Rome` and `Lisbon`:
+
 ```shell
 juju add-model rome    # 1st cluster location: Rome
 juju add-model lisbon  # 2nd cluster location: Lisbon
@@ -22,19 +23,21 @@ juju switch lisbon
 juju deploy mysql db2 --channel=8.0/edge --config profile=testing --config cluster-name=lisbon --base ubuntu@22.04
 ```
 
-[note type="caution"]
-**Note**: remove profile configuration for production deployments. Check [Profiles](/t/11973) for documentation.
-[/note]
+```{caution}
+Remove profile configuration for production deployments. Check [Profiles](/reference/profiles) for documentation.
+```
 
 ## Offer
 
 Offer asynchronous replication on the Primary cluster (Rome):
+
 ```shell
 juju switch rome
 juju offer db1:replication-offer replication-offer
 ```
 
 (Optional) Offer asynchronous replication on StandBy cluster (Lisbon), for the future:
+
 ```shell
 juju switch lisbon
 juju offer db2:replication-offer replication-offer
@@ -43,6 +46,7 @@ juju offer db2:replication-offer replication-offer
 ## Consume
 
 Consume asynchronous replication on planned `StandBy` cluster (Lisbon):
+
 ```shell
 juju switch lisbon
 juju consume rome.replication-offer
@@ -58,6 +62,7 @@ juju run db1/leader create-replication
 ```
 
 (Optional) Consume asynchronous replication on the current `Primary` (Rome), for the future:
+
 ```shell
 juju switch rome
 juju consume lisbon.replication-offer
@@ -66,10 +71,12 @@ juju consume lisbon.replication-offer
 ## Status
 
 Run the `get-cluster-status` action with the `cluster-set=True` flag: 
+
 ```shell
 juju run -m rome db1/0 get-cluster-status cluster-set=True
 ```
 Results:
+
 ```shell
 status:
   clusters:
@@ -90,14 +97,18 @@ success: "True"
 ```
 
 ## Scaling
+
 The two clusters works independently, this means that it's possible to independently scaling in/out each cluster without much hassle, e.g.:
+
 ```shell
 juju add-unit db1 -n 2 -m rome
 
 juju add-unit db2 -n 2 -m lisbon
 ```
-[note type="caution"]
+
+```{caution}
 **Note**: The scaling is possible before and after the asynchronous replication established/created.
-[/note]
+```
+
+[check]: https://img.shields.io/badge/%E2%9C%93-brightgreen
 
-[check]: https://img.shields.io/badge/%E2%9C%93-brightgreen
\ No newline at end of file
diff --git a/docs/how-to/cross-regional-async-replication/index.md b/docs/how-to/cross-regional-async-replication/index.md
new file mode 100644
index 0000000000..8048c4905f
--- /dev/null
+++ b/docs/how-to/cross-regional-async-replication/index.md
@@ -0,0 +1,12 @@
+# Cross-regional asynchronous replication
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Deploy <deploy>
+Clients <clients>
+Switchover/failover <switchover-failover>
+Recovery <recovery>
+Removal <removal>
+```
diff --git a/docs/how-to/h-async-recovery.md b/docs/how-to/cross-regional-async-replication/recovery.md
similarity index 53%
rename from docs/how-to/h-async-recovery.md
rename to docs/how-to/cross-regional-async-replication/recovery.md
index f7e9d0603d..4c5747d203 100644
--- a/docs/how-to/h-async-recovery.md
+++ b/docs/how-to/cross-regional-async-replication/recovery.md
@@ -1,21 +1,24 @@
-# Recovery of Async replication
+# Recovery
 
 ## Pre-requisites
-Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/t/14169)!
 
-## Recovery detached cluster
+Make sure both `Rome` and `Lisbon` clusters are deployed following the [async deployment guide](/how-to/cross-regional-async-replication/deploy).
 
-If relation between clusters was removed and one side went into detached/blocked state: simply relate async replication back to restore ClusterSet.
+## Recover detached cluster
 
-## Recovery lost cluster
+If a relation between clusters was removed and one side went into detached/blocked state: simply relate async replication back to restore ClusterSet.
 
-If a Cluster has been lost and the ClusterSet need new member: deploy new db application and init async replication. The data will be copied automatically and the new Cluster will join ClusterSet.
+## Recover lost cluster
 
-## Recovery invalidated cluster
+If a cluster has been lost and the ClusterSet need new member: deploy new db application and init async replication. The data will be copied automatically and the new cluster will join ClusterSet.
 
-A cluster in the cluster-set gets invalidated when async replication auto-recovery fails on a disconnection event or when a failover is run against another cluster-set member while this cluster is unreachable. If the invalidated cluster connections is restored, it's status will be displayed in juju status as:
+## Recover invalidated cluster
 
-```
+A cluster in the cluster-set gets invalidated when async replication auto-recovery fails on a disconnection event or when a failover is run against another cluster-set member while this cluster is unreachable. 
+
+If the invalidated cluster connections is restored, it's status will be displayed in `juju status` as:
+
+```text
 App  Version                  Status  Scale  Charm  Channel   Rev  Address         Exposed  Message
 db2  8.0.36-0ubuntu0.22.04.1  active      3  mysql  8.0/edge  234  10.152.183.241  no
 
@@ -26,10 +29,12 @@ db2/2   active    idle   10.1.124.200
 ```
 
 Which indicates that connectivity is possible, but replication channel is stopped.
-To restore replication operation, run:
+
+To restore the replication operation, run:
 
 ```shell
 juju run db2/leader rejoin-cluster cluster-name=rome
 ```
 
-Being `rome` the name of the invalidated cluster.
\ No newline at end of file
+Where `rome` is the name of the invalidated cluster.
+
diff --git a/docs/how-to/h-async-removal.md b/docs/how-to/cross-regional-async-replication/removal.md
similarity index 74%
rename from docs/how-to/h-async-removal.md
rename to docs/how-to/cross-regional-async-replication/removal.md
index a5f536d1c2..749dde22cd 100644
--- a/docs/how-to/h-async-removal.md
+++ b/docs/how-to/cross-regional-async-replication/removal.md
@@ -1,19 +1,19 @@
-# Removal of Async replication
+# Removal
 
 ## Pre-requisites
 
-Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/t/14169)!
+Make sure both `Rome` and `Lisbon` clusters are deployed following the [async deployment guide](/how-to/cross-regional-async-replication/deploy).
 
-## Detach Cluster from ClusterSet
+## Detach cluster from ClusterSet
 
-> **Note**: It is important to [switchover](/t/14171) the `Primary` Cluster before detaching it from ClusterSet!
+```{important} 
+It is important to [switchover](/how-to/cross-regional-async-replication/switchover-failover) the `Primary` cluster before detaching it from ClusterSet!
+```
 
 Assuming the `Lisbon` is a current `Primary` and we want to detach `Rome` (for removal or reuse):
 
 ```shell
-
 juju remove-relation replication-offer db2:replication
-
 ```
 
 The command above will move cluster `Rome` into the detached state `blocked` keeping all the data in place.
@@ -27,25 +27,18 @@ From this points, there are three options, as described in the following section
 At this stage, the detached/blocked cluster `Rome` can re-join the previous ClusterSet by restoring async integration/relation:
 
 ```shell
-
 juju switch rome
-
 juju integrate replication-offer db1:replication
-
 juju switch lisbon
-
 juju run db2/leader create-replication
-
 ```
 
-## Removing detached cluster
+## Remove detached cluster
 
 Remove no-longer necessary Cluster `Rome` (and destroy storage if Rome data is no longer necessary):
 
 ```shell
-
 juju remove-application db1 # --destroy-storage
-
 ```
 
 ## New ClusterSet from detached Cluster
@@ -53,7 +46,6 @@ juju remove-application db1 # --destroy-storage
 Convert `Rome` to the new Cluster/ClusterSet keeping the current data in use:
 
 ```shell
-
 juju run -m rome db1/leader recreate-cluster
+```
 
-```
\ No newline at end of file
diff --git a/docs/how-to/cross-regional-async-replication/switchover-failover.md b/docs/how-to/cross-regional-async-replication/switchover-failover.md
new file mode 100644
index 0000000000..dbf9e24dd0
--- /dev/null
+++ b/docs/how-to/cross-regional-async-replication/switchover-failover.md
@@ -0,0 +1,33 @@
+# Switchover / Failover
+
+## Pre-requisites
+
+Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/how-to/cross-regional-async-replication/deploy)!
+
+## Switchover (safe)
+
+Assuming `Rome` is currently `Primary` and you want to promote `Lisbon` to be new primary:
+
+```shell
+juju run -m lisbon db2/leader promote-to-primary scope=cluster
+```
+
+`Rome` will be converted to `StandBy` member.
+
+## Failover (forced)
+
+```{danger}
+This is a **dangerous** operation which can cause a split-brain situation. 
+
+It should ONLY be executed if Primary cluster is no longer exist (i.e. it is lost). Otherwise please use the safe switchover procedure described above!
+```
+
+Assuming `Rome` was a `Primary` (before we lost the cluster `Rome`) and you want to promote `Lisbon` to be the new primary:
+
+```shell
+juju run -m lisbon db2/leader promote-to-primary scope=cluster force=True
+```
+
+```{caution}
+`force=True` will cause the old primary to be invalidated.
+```
diff --git a/docs/how-to/h-deploy-airgapped.md b/docs/how-to/deploy/air-gapped.md
similarity index 76%
rename from docs/how-to/h-deploy-airgapped.md
rename to docs/how-to/deploy/air-gapped.md
index c4fa111e59..19f8ccab4d 100644
--- a/docs/how-to/h-deploy-airgapped.md
+++ b/docs/how-to/deploy/air-gapped.md
@@ -1,3 +1,4 @@
+
 # Deploy in an offline or air-gapped environment
 
 An air-gapped environment refers to a system that does not have access to the public internet.
@@ -9,21 +10,22 @@ Canonical does not prescribe how you should set up your specific air-gapped envi
 
 * A VM/hardware resources available for Juju.
 * DNS is configured to the local nameservers.
-* [Juju is configured](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#configure-juju) to use local air-gapped services.
+* [Juju is configured](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#configure-juju) to use local air-gapped services.
 * The [`store-admin`](https://snapcraft.io/store-admin) tool is installed and configured.
-* [Air-gapped CharmHub](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/) is installed and running.
+* [Air-gapped CharmHub](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub) is installed and running.
 * [Air-gapped Snap Store Proxy](https://documentation.ubuntu.com/snap-store-proxy/) is installed and running.
 * Local APT and LXD Images caches are reachable.
 
 ## Air-gapped setup summary
 
-[1\. Export snaps and charms](#1-export-snaps-and-charms) <br>
-[2\. Transfer binary blobs](#2-transfer-binary-blobs) <br>
+[1\. Export snaps and charms](1-export-snaps-and-charms) <br>
+[2\. Transfer binary blobs](2-transfer-the-binary-blobs) <br>
 [3\. Import snaps and charms](3-import-snaps-and-charms) <br>
-[4\. Deploy MySQL](#4-deploy-mysql)
+[4\. Deploy MySQL](4-deploy-mysql)
 
 ## Air-gapped day-to-day example
 
+(1-export-snaps-and-charms)=
 ### 1. Export snaps and charms
 Exporting VM SNAPs and Charms and  are currently independent processes. The `store-admin` tool is designed to simplify the process. 
 
@@ -31,8 +33,8 @@ Future improvements are planned to the `store-admin` tool so that it could poten
 
 #### Charms
  The necessary charm(s) can be exported as bundle or independently (charm-by-charm). See the Snap Proxy documentation:
-* [Offline Charmhub configuration > Export charm bundle](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#export-charm-bundles)
-* [Offline Charmhub configuration > Export charms](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#export-charms)
+* [Offline Charmhub configuration > Export charm bundle](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#export-charm-bundles)
+* [Offline Charmhub configuration > Export charms](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#export-charms)
 
 The bundle export example:
 
@@ -67,7 +69,7 @@ Successfully exported charm bundle mysql-bundle: /home/ubuntu/snap/store-admin/c
 </details>
 
 #### SNAPs
-Usually charms require SNAPs (and some manually pin them). For the manual SNAP exports, follow the official Snap Store Proxy documentation: [Offline Charmhub configuration > Export SNAP](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#export-snap-resources). Data team is shipping the mapping [snap.yaml](https://github.com/canonical/mysql-bundle/blob/main/releases/latest/) to the published [bundle.yaml](https://github.com/canonical/mysql-bundle/blob/main/releases/latest/):
+Usually charms require SNAPs (and some manually pin them). For the manual SNAP exports, follow the official Snap Store Proxy documentation: [Offline Charmhub configuration > Export SNAP](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#export-snap-resources). Data team is shipping the mapping [snap.yaml](https://github.com/canonical/mysql-bundle/blob/main/releases/latest/) to the published [bundle.yaml](https://github.com/canonical/mysql-bundle/blob/main/releases/latest/):
 
 > **Warning**: always use snap.yaml and bundle.yaml from the same Git commit (to match each other)!
 
@@ -92,6 +94,7 @@ canonical-livepatch: /home/ubuntu/snap/store-admin/common/export/canonical-livep
 ```
 </details>
 
+(2-transfer-the-binary-blobs)=
 ### 2. Transfer the binary blobs 
 
 Transfer the binary blobs using the way of your choice into the air-gapped environment.
@@ -104,9 +107,10 @@ cp /media/usb/*.tar.gz /var/snap/snap-store-proxy/common/charms-to-push/
 ```
 > **Note**: always check [checksum](https://en.wikipedia.org/wiki/Checksum) for the transferred blobs!
 
+(3-import-snaps-and-charms)=
 ### 3. Import snaps and charms
 
- Import the [snap](https://documentation.ubuntu.com/snap-store-proxy/en/airgap/#importing-pushing-snaps) and [charm](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#import-packages) blobs into local air-gapped CharmHub:
+ Import the [snap](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap/#importing-pushing-snaps) and [charm](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#import-packages) blobs into local air-gapped CharmHub:
 
 > **Note**: when importing machine charms that depend on a snap for functionality, you must first manually import the required snap.
 ```shell
@@ -114,25 +118,27 @@ sudo snap-store-proxy push-snap /var/snap/snap-store-proxy/common/snaps-to-push/
 
 sudo snap-store-proxy push-charm-bundle /var/snap/snap-store-proxy/common/charms-to-push/mysql-bundle-20241003T104903.tar.gz
 ```
-> **Note**: when [re-importing](https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/#import-packages) charms or importing other revisions, make sure to provide the `--push-channel-map`.
+> **Note**: when [re-importing](https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub/#import-packages) charms or importing other revisions, make sure to provide the `--push-channel-map`.
 
+(4-deploy-mysql)=
 ### 4. Deploy MySQL
 
  Deploy and operate Juju charms normally:
 ```shell
 juju deploy mysql
 ```
-[note]
+```{note}
 **Note**: All the charms revisions and snap revisions deployed in the air-gapped environment must match the official CharmHub and SnapStore revisions.
 
-Use [the official release notes](/t/11881) as a reference.
-[/note]
+Use [the official release notes](/reference/releases) as a reference.
+```
 
 ## Additional resources
 
 * https://docs.ubuntu.com/snap-store-proxy/en/airgap
 * https://documentation.ubuntu.com/snap-store-proxy/
-* https://documentation.ubuntu.com/snap-store-proxy/en/airgap-charmhub/
+* https://documentation.ubuntu.com/enterprise-store/main/how-to/airgap-charmhub
 * https://ubuntu.com/kubernetes/docs/install-offline
-* [Charmed Kubeflow > Install in an airgapped environment](https://charmed-kubeflow.io/docs/install-in-airgapped-environment)
-*  [Wikipedia > Air gap (networking)](https://en.wikipedia.org/wiki/Air_gap_(networking))
\ No newline at end of file
+* [Charmed Kubeflow > Install in an air-gapped environment](https://documentation.ubuntu.com/charmed-kubeflow/how-to/install/install-air-gapped/)
+*  [Wikipedia > Air gap (networking)](https://en.wikipedia.org/wiki/Air_gap_(networking))
+
diff --git a/docs/how-to/h-deploy-ec2.md b/docs/how-to/deploy/aws-ec2.md
similarity index 90%
rename from docs/how-to/h-deploy-ec2.md
rename to docs/how-to/deploy/aws-ec2.md
index 19fa2fd277..07245d858c 100644
--- a/docs/how-to/h-deploy-ec2.md
+++ b/docs/how-to/deploy/aws-ec2.md
@@ -2,16 +2,6 @@
 
 [Amazon Web Services](https://aws.amazon.com/) is a popular subsidiary of Amazon that provides on-demand cloud computing platforms on a metered pay-as-you-go basis. Access the AWS web console at [console.aws.amazon.com](https://console.aws.amazon.com/).
 
-## Summary
-* [Install AWS and Juju tooling](#install-aws-and-juju-tooling)
-  * [Authenticate](#authenticate)
-* [Bootstrap Juju controller on AWS EC2](#bootstrap-juju-controller-on-aws-ec2)
-* [Deploy charms](#deploy-charms)
-* [Expose database (optional)](#expose-database-optional)
-* [Clean up](#clean-up)
-
----
-
 ## Install AWS and Juju tooling
 
 Install Juju via snap:
@@ -20,7 +10,7 @@ sudo snap install juju
 ```
 
 Follow the installation guides for:
-* [AWs CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - the Amazon Web Services CLI
+* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - the Amazon Web Services CLI
 
 To check they are all correctly installed, you can run the commands demonstrated below with sample outputs:
 
@@ -80,7 +70,7 @@ to create a new model to deploy workloads.
 ```
 [/details]
 
-You can check the [AWS EC2 instance availability](https://us-east-1.console.aws.amazon.com/ec2/home?region=us-east-1#Instances:instanceState=running) (ensure the right AWS region chosen!):
+You can check the [AWS EC2 instance availability](https://us-east-1.console.aws.amazon.com/ec2/home?region=us-east-1) (ensure the right AWS region chosen!):
 ![image|690x118](upload://putAO5NyHdaeWE6jXI8X1hZHTYv.png)
 
 Create a new Juju model:
@@ -171,11 +161,11 @@ mysql> show databases;
 3 rows in set (0.00 sec)
 ```
 
-From here you can [use/scale/backup/restore/refresh](/t/9922) your newly deployed Charmed MySQL.
+From here you can [use/scale/backup/restore/refresh](/tutorial/index) your newly deployed Charmed MySQL.
 
 ## Expose database (optional)
 
-If necessary to access DB from outside of AWS (warning: [opening ports to public is risky](https://www.beyondtrust.com/blog/entry/what-is-an-open-port-what-are-the-security-implications)) open the AWS firewall using the simple [juju expose](https://juju.is/docs/juju/juju-expose) functionality: 
+If necessary to access DB from outside of AWS (warning:opening ports to public is risky) open the AWS firewall using the simple [juju expose](https://juju.is/docs/juju/juju-expose) functionality: 
 ```shell
 juju expose mysql
 ```
@@ -207,9 +197,9 @@ juju unexpose mysql
 ```
 ## Clean up
 
-[note type="caution"]
+```{caution}
 Always clean AWS resources that are no longer necessary -  they could be costly!
-[/note]
+```
 
 To destroy the Juju controller and remove AWS instance (warning: all your data will be permanently removed):
 ```shell
@@ -256,4 +246,5 @@ Remove AWS EC2 CLI credentials from Juju:
 Finally, remove AWS CLI user credentials (to avoid forgetting and leaking):
 ```shell
 rm -f ~/.aws/credentials.yaml
-```
\ No newline at end of file
+```
+
diff --git a/docs/how-to/h-deploy-azure.md b/docs/how-to/deploy/azure.md
similarity index 93%
rename from docs/how-to/h-deploy-azure.md
rename to docs/how-to/deploy/azure.md
index 578d20b8e4..2e743f322b 100644
--- a/docs/how-to/h-deploy-azure.md
+++ b/docs/how-to/deploy/azure.md
@@ -1,22 +1,12 @@
+
 # How to deploy on Azure
 
 [Azure](https://azure.com/) is a cloud computing platform developed by Microsoft. It has management, access and development of applications and services to individuals, companies, and governments through its global infrastructure. Access the Azure web console at [portal.azure.com](https://portal.azure.com/).
 
-## Summary
-* [Set up Juju and Azure tooling](#set-up-juju-and-azure-tooling)
-  * [Install Juju and Azure CLI](#install-juju-and-azure-cli)
-  * [Authenticate](#authenticate)
-  * [Bootstrap Juju controller on Azure](#bootstrap-juju-controller)
-* [Deploy charms](#deploy-charms)
-* [Expose database (optional)](#expose-database-optional)
-* [Clean up](#clean-up)
-
----
-
 ## Set up Juju and Azure tooling
-[note type="caution"]
+```{caution}
 **Warning**: The described `Azure interactive` method (with web browser authentication `service-principal-secret-via-browser`) described here is only supported starting Juju 3.6-rc1+!
-[/note]
+```
 ### Install Juju and Azure CLI
 Install Juju via snap:
 ```shell
@@ -47,7 +37,7 @@ Your CLI is up-to-date.
 
 ### Authenticate
 
-Please follow [the official Juju Azure documentation](https://juju.is/docs/juju/microsoft-azure) and check [the extra explanation about possible options](/t/15219). Choose the authentication method which fits you best. 
+Please follow [the official Juju Azure documentation](https://juju.is/docs/juju/microsoft-azure) and check [How to use Juju with Microsoft Azure](https://discourse.charmhub.io/t/how-to-use-juju-with-microsoft-azure/15219) for more information. Choose the authentication method which fits you best. 
 
 We are describing here the currently recommended `interactive` method with web browser authentication `service-principal-secret-via-browser`. This method does not require logging in with the Azure CLI locally, but it **requires an Azure subscription**.
 
@@ -150,7 +140,7 @@ Now you can run
 to create a new model to deploy workloads.
 ```
 
-You can check the [Azure instances availability](https://portal.azure.com/#browse/Microsoft.Compute%2FVirtualMachines):
+You can check the [Azure instances availability](https://portal.azure.com/#browse/Microsoft.Compute/VirtualMachines):
 
 ![image|689x313](upload://bB5lCMIHtL1KToftKQVv7z86aoi.png)
 
@@ -215,7 +205,7 @@ At this point, you can access your DB inside Azure VM using the internal IP addr
 mysql -h 192.168.0.5 -u relation-14 -P1yGJ2KqtN4Qlf6KgeJDLOVES test123
 ```
 
-From here you can begin to use your newly deployed MySQL. Learn more about operations like scaling, enabling TLS, managing users and passwords, and more in the [Charmed MySQL tutorial](/t/9922).
+From here you can begin to use your newly deployed MySQL. Learn more about operations like scaling, enabling TLS, managing users and passwords, and more in the [Charmed MySQL tutorial](/tutorial/index).
 
 ## Expose database (optional)
 
@@ -223,7 +213,7 @@ If it is necessary to access the database from outside of Azure, open the Azure
 ```shell
 juju expose mysql
 ```
-> Be wary that [opening ports to the public is risky](https://www.beyondtrust.com/blog/entry/what-is-an-open-port-what-are-the-security-implications).
+> Be wary that opening ports to the public is risky.
 
 Once exposed, you can connect your database using the same credentials as above. This time use the Azure VM public IP assigned to the MySQL instance. You can see this with `juju status`:
 ```shell
@@ -255,9 +245,9 @@ juju unexpose mysql
 
 ## Clean up
 
-[note type="caution"]
+```{caution}
 Always clean Azure resources that are no longer necessary -  they could be costly!
-[/note]
+```
 
 See all controllers in your machine with the following command:
 ```
@@ -317,4 +307,5 @@ az role definition delete --name azure-test-role1
 Finally, log out of the Azure CLI user credentials to prevent any credential leakage:
 ```shell
 az logout 
-```
\ No newline at end of file
+```
+
diff --git a/docs/how-to/h-deploy-gce.md b/docs/how-to/deploy/gce.md
similarity index 92%
rename from docs/how-to/h-deploy-gce.md
rename to docs/how-to/deploy/gce.md
index d89992d01b..0d284b28c4 100644
--- a/docs/how-to/h-deploy-gce.md
+++ b/docs/how-to/deploy/gce.md
@@ -1,17 +1,8 @@
+
 # How to deploy on GCE
 
 [Google Compute Engine](https://cloud.google.com/products/compute) is a popular subsidiary of Google that provides on-demand cloud computing platforms on a metered pay-as-you-go basis. Access the GCloud web console at [console.cloud.google.com](https://console.cloud.google.com/compute/instances).
 
-## Summary
-* [Install GCloud and Juju tooling](#install-gcloud-and-juju-tooling)
-  * [Authenticate](#authenticate)
-* [Bootstrap Juju controller on GCE](#bootstrap-juju-controller-on-gce)
-* [Deploy charms](#deploy-charms)
-* [Expose database (optional)](#expose-database-optional)
-* [Clean up](#clean-up)
-
----
-
 ## Install GCloud and Juju tooling
 
 Install Juju via snap:
@@ -201,11 +192,11 @@ mysql> show databases;
 3 rows in set (0.13 sec)
 ```
 
-From here you can [use/scale/backup/restore/refresh](/t/9922) your newly deployed Charmed MySQL.
+From here you can [use/scale/backup/restore/refresh](/tutorial/index) your newly deployed Charmed MySQL.
 
 ## Expose database (optional)
 
-To access the database from outside of GCloud (warning: [opening ports to public is risky](https://www.beyondtrust.com/blog/entry/what-is-an-open-port-what-are-the-security-implications)) open the GCloud firewall using the simple [juju expose](https://juju.is/docs/juju/juju-expose) functionality: 
+To access the database from outside of GCloud (warning: opening ports to public is risky) open the GCloud firewall using the simple [juju expose](https://juju.is/docs/juju/juju-expose) functionality: 
 ```shell
 juju expose mysql
 ```
@@ -237,9 +228,9 @@ juju unexpose mysql
 ```
 ## Clean up
 
-[note type="caution"]
+```{caution}
 Always clean GCE resources that are no longer necessary -  they could be costly!
-[/note]
+```
 
 To destroy the Juju controller and remove GCE instance, run: 
 >**Warning**: all your data will be permanently removed
@@ -281,4 +272,5 @@ Remove GCloud credentials from Juju:
 Finally, remove the GCloud json file user credentials (to avoid forgetting and leaking):
 ```shell
 rm -f /var/snap/juju/common/sa-private-key.json
-```
\ No newline at end of file
+```
+
diff --git a/docs/how-to/deploy/index.md b/docs/how-to/deploy/index.md
new file mode 100644
index 0000000000..ba42e5ce8f
--- /dev/null
+++ b/docs/how-to/deploy/index.md
@@ -0,0 +1,17 @@
+# Deploy
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Sunbeam <sunbeam>
+LXD <lxd>
+MAAS <maas>
+AWS EC2 <aws-ec2>
+GCE <gce>
+Azure <azure>
+Multi-AZ <multi-az>
+Terraform <terraform>
+Air-gapped <air-gapped>
+Juju spaces <juju-spaces>
+```
diff --git a/docs/how-to/h-deploy-spaces.md b/docs/how-to/deploy/juju-spaces.md
similarity index 98%
rename from docs/how-to/h-deploy-spaces.md
rename to docs/how-to/deploy/juju-spaces.md
index e43a3bfe67..9463a6e03a 100644
--- a/docs/how-to/h-deploy-spaces.md
+++ b/docs/how-to/deploy/juju-spaces.md
@@ -1,3 +1,4 @@
+
 # Deploy on Juju spaces
 
 The Charmed MySQL operator supports [Juju spaces](https://documentation.ubuntu.com/juju/latest/reference/space/index.html) to separate network traffic for:
@@ -32,9 +33,9 @@ juju deploy mysql --channel 8.0/edge \
   --bind "database-peers=peers database=client"
 ```
 
-[note type=caution]
+```{caution}
 Currently there's no support for the juju `bind` command. Network space binding must be defined at deploy time only.
-[/note]
+```
 
 Consequently, a client application must use the `client` space on the model, or a space for the same subnet in another model, for example:
 ```text
@@ -60,6 +61,7 @@ The Charmed MySQL operator endpoints are:
 | s3-parameters                  | Backup               |
 
 
-[note]
+```{note}
 If using a network space for the backup traffic, the user is responsible for ensuring that the target object storage URL traffic is routed via the specified network space.
-[/note]
\ No newline at end of file
+```
+
diff --git a/docs/how-to/h-deploy-lxd.md b/docs/how-to/deploy/lxd.md
similarity index 94%
rename from docs/how-to/h-deploy-lxd.md
rename to docs/how-to/deploy/lxd.md
index 00ea99ca99..b74027b906 100644
--- a/docs/how-to/h-deploy-lxd.md
+++ b/docs/how-to/deploy/lxd.md
@@ -1,8 +1,9 @@
+
 # Deploy on LXD
 
 This guide assumes you have a running Juju and LXD environment. 
 
-For a detailed walkthrough of setting up an environment and deploying the charm on LXD, refer to the [Tutorial](/t/9922).
+For a detailed walkthrough of setting up an environment and deploying the charm on LXD, refer to the [Tutorial](/tutorial/index).
 
 ---
 
@@ -32,4 +33,5 @@ mysql/0*  active    idle   1        10.234.188.135  3306,33060/tcp  Primary
 
 Machine  State    Address         Inst id        Base          AZ  Message
 1        started  10.234.188.135  juju-ff9064-0  ubuntu@22.04      Running
-```
\ No newline at end of file
+```
+
diff --git a/docs/how-to/h-deploy-maas.md b/docs/how-to/deploy/maas.md
similarity index 82%
rename from docs/how-to/h-deploy-maas.md
rename to docs/how-to/deploy/maas.md
index cbb4e13c47..c1e6d4f842 100644
--- a/docs/how-to/h-deploy-maas.md
+++ b/docs/how-to/deploy/maas.md
@@ -2,20 +2,9 @@
 
 This guide aims to provide a quick start to deploying Charmed MySQL on MAAS. It summarizes the instructions from the [Build a MAAS and LXD environment with Multipass Tutorial](https://discourse.maas.io/t/5360) to set up and tear down a **playground environment**.
 
-If you want to deploy MySQL on MAAS in a **production environment**, refer to the official [Bootstrap MAAS Tutorial](https://maas.io/docs/tutorial-bootstrapping-maas) followed by the [Charmed MySQL Tutorial](/t/9912).
+If you want to deploy MySQL on MAAS in a **production environment**, refer to the official [Bootstrap MAAS Tutorial](https://maas.io/docs/tutorial-bootstrapping-maas) followed by the [Charmed MySQL Tutorial](/tutorial/index).
 
-## Summary
- * [Bootstrap a Multipass VM](#heading--bootstrap-multipass-vm)
- * [Configure MAAS](#heading--configure-maas)
- * [Register MAAS with Juju](#heading--register-maas-juju)
- * [Deploy Charmed MySQL on MAAS](#heading--deploy-mysql-maas)
- * [Test Charmed MySQL deployment](#heading--test-mysql)
- * [Clean up the environment](#heading--clean-up)
-
-For further details and explanation about each step, remember you can refer to the [original tutorial](https://discourse.maas.io/t/5360). 
-
----
- <a href="#heading--bootstrap-multipass-vm"><h2 id="heading--bootstrap-multipass-vm"> Bootstrap a Multipass VM </h2></a>
+## Bootstrap a Multipass VM
 
 Install Multipass and launch a VM:
 ```shell
@@ -26,7 +15,7 @@ wget -qO- https://raw.githubusercontent.com/canonical/maas-multipass/main/maas.y
 ```
 > The wget command provides a [cloud-init](https://github.com/canonical/maas-multipass/blob/main/maas.yml) file that will set up the VM's LXD and MAAS environment.
 
- <a href="#heading--configure-maas"><h2 id="heading--configure-maas"> Configure MAAS </h2></a>
+## Configure MAAS
 
 **1.** Find your MAAS IP with
 ```shell
@@ -45,9 +34,9 @@ multipass list
 </details>
 </br>
 
-[note]
+```{note}
 Make sure you are downloading 22.04 images as well (20.04 is the current default).
-[/note]
+```
 
 The LXD machine will be up and running after the images downloading and sync is completed.
 <details>
@@ -71,7 +60,7 @@ The LXD machine will be up and running after the images downloading and sync is
 multipass exec maas -- sudo maas apikey --username admin
 ```
 
- <a href="#heading--register-maas-juju"><h2 id="heading--register-maas-juju"> Register MAAS with Juju </h2></a>
+## Register MAAS with Juju
 
 **1.** Enter the Multipass shell and install juju:
 ```shell
@@ -118,7 +107,7 @@ Add the flags `--credential` if you registered several MAAS credentials, and `--
 juju bootstrap --constraints tags=juju maas-cloud maas-controller
 ```
 
-# Deploy Charmed MySQL on MAAS
+## Deploy Charmed MySQL on MAAS
 ```shell
 juju add-model mysql maas-cloud
 juju deploy mysql --channel 8.0/candidate # MAAS supported since charm revision 234+
@@ -138,24 +127,25 @@ Machine  State    Address     Inst id       Base          AZ       Message
 1        started  10.10.10.7  pumped-racer  ubuntu@22.04  default  Deployed
 ```
 
-# Test your Charmed MySQL deployment
+## Test your Charmed MySQL deployment
 
-Check the [Testing](/t/11770) reference to test your deployment.
+Check the [Testing](/reference/software-testing) reference to test your deployment.
 
- <a href="#heading--clean-up"><h2 id="heading--clean-up"> Clean up the environment </h2></a>
+## Clean up the environment
 To stop your VM, run: 
 ```shell
 multipass stop maas
 ```
 If you're done with testing and would like to free up resources on your machine, you can remove the VM entirely.
 
-[note type="caution"]
+```{caution}
 **Warning**: When you remove the VM as shown below, **you will lose all the data** in MySQL and any other applications inside it! 
 
 For more information, see the docs for [`multipass delete`](https://multipass.run/docs/delete-command).
-[/note]
+```
 
 To completely delete your VM and all its data, run:
 ```shell
 multipass delete --purge maas
-```
\ No newline at end of file
+```
+
diff --git a/docs/how-to/h-deploy-multi-az.md b/docs/how-to/deploy/multi-az.md
similarity index 90%
rename from docs/how-to/h-deploy-multi-az.md
rename to docs/how-to/deploy/multi-az.md
index 68a69a50aa..43b122c407 100644
--- a/docs/how-to/h-deploy-multi-az.md
+++ b/docs/how-to/deploy/multi-az.md
@@ -1,3 +1,4 @@
+
 # Deploy on multiple availability zones (AZ) 
 
 During the deployment to hardware/VMs, it is important to spread all the
@@ -6,28 +7,20 @@ or even better, to the different [availability zones](https://en.wikipedia.org/w
 
 This guide will take you through deploying a MySQL cluster on GCE using 3 available zones. All Juju units will be set up to sit in their dedicated zones only, which effectively guarantees database copy survival across all available AZs.
 
-[note]
+```{note}
 This documentation assumes that your cloud supports and provides availability zones concepts. This is enabled by default on EC2/GCE and supported by LXD/MicroCloud.
-
-See the [Additional resources](#additional-resources) section for more details about AZ on specific clouds.
-[/note]
-
-## Summary
-* [Set up GCE on Google Cloud](#set-up-gce-on-google-cloud)
-* [Deploy MySQL with Juju zones constraints](#deploy-mysql-with-juju-zones-constraints)
-  * [Simulation: A node gets drained](#simulation-a-node-gets-drained)
-* [Additional resources](#additional-resources)
----
+```
 
 ## Set up GCE on Google Cloud
 
-Let's deploy the [MySQL Cluster on GKE (us-east4)](/t/9912) using all 3 zones there (`us-east4-a`, `us-east4-b`, `us-east4-c`) and make sure all pods always sits in the dedicated zones only.
+Let's deploy the [MySQL Cluster on GCE (us-east4)](/how-to/deploy/gce) using all 3 zones there (`us-east4-a`, `us-east4-b`, `us-east4-c`) and make sure all pods always sits in the dedicated zones only.
+
+```{caution}
+Creating the following GKE resources may cost you money - be sure to monitor your GCloud costs.
+```
 
-[note type="caution"]
-**Warning**: Creating the following GKE resources may cost you money - be sure to monitor your GCloud costs.
-[/note]
+Log into Google Cloud and [bootstrap GCE on Google Cloud](/how-to/deploy/gce):
 
-Log into Google Cloud and [bootstrap GCE on Google Cloud](/t/15722):
 ```shell
 gcloud auth login
 gcloud iam service-accounts keys create sa-private-key.json  --iam-account=juju-gce-account@[your-gcloud-project-12345].iam.gserviceaccount.com
@@ -41,9 +34,9 @@ juju add-model mymodel
 
 ## Deploy MySQL with Juju zones constraints
 
-Juju provides the support for availability zones using **constraints**. Read more about zones in [Juju documentation](https://juju.is/docs/juju/constraint#heading--zones).
+Juju provides the support for availability zones using **constraints**. Read more about zones in [Juju documentation](https://juju.is/docs/juju/constraint#zones).
 
-The command below demonstrates how Juju automatically deploys Charmed MySQL VM using [Juju constraints](https://juju.is/docs/juju/constraint#heading--zones):
+The command below demonstrates how Juju automatically deploys Charmed MySQL VM using [Juju constraints](https://juju.is/docs/juju/constraint#zones):
 
 ```shell
 juju deploy mysql -n 3 \
@@ -51,6 +44,7 @@ juju deploy mysql -n 3 \
 ```
 
 After a successful deployment, `juju status` will show an active application:
+
 ```shell
 Model    Controller  Cloud/Region     Version    SLA          Timestamp
 mymodel  gce         google/us-east1  3.6-rc1.1  unsupported  00:59:53+02:00
@@ -163,9 +157,9 @@ Machine  State    Address        Inst id        Base          AZ          Messag
 
 ## Remove GCE setup
 
-[note type="caution"]
+```{caution}
 **Warning**: Do not forget to remove your test setup - it can be costly!
-[/note]
+```
 
 Check the list of currently running GCE instances:
 ```shell
@@ -185,4 +179,5 @@ juju destroy-controller gce --no-prompt --force --destroy-all-models
 Re-check that there are no running GCE instances left (it should be empty):
 ```shell
 gcloud compute instances list
-```
\ No newline at end of file
+```
+
diff --git a/docs/how-to/h-deploy-sunbeam.md b/docs/how-to/deploy/sunbeam.md
similarity index 83%
rename from docs/how-to/h-deploy-sunbeam.md
rename to docs/how-to/deploy/sunbeam.md
index 77a293a19c..fcc1ee8593 100644
--- a/docs/how-to/h-deploy-sunbeam.md
+++ b/docs/how-to/deploy/sunbeam.md
@@ -1,3 +1,4 @@
+
 # How to deploy on Sunbeam
 
 > **Duration** : Up to 60 minutes depending on internet download speed.
@@ -6,17 +7,11 @@ This guide goes through the steps for setting up Sunbeam and deploying Charmed M
 
 ## Prerequisites
 * A physical or virtual machine running Ubuntu 22.04+
-  * If you'd like to follow this guide in an isolated test environment, you can [launch a Multipass](/t/9924#set-up-multipass) instance.
+  * If you'd like to follow this guide in an isolated test environment, you can [launch a Multipass](create-multipass-vm) instance.
 * Hardware requirements depend on planned deployment size.
   * Recommended: 8 CPU cores, 32GB RAM, 100GB of storage
   * Minimum: See the requirements listed in the [Sunbeam documentation][Single-node guided]
 
-## Steps
-* [Install and bootstrap Sunbeam](#install-and-bootstrap-sunbeam)
-* [Enable OpenStack Images Auto-sync](#enable-openstack-images-auto-sync)
-* [Set up Juju inside an OpenStack bastion](set-up-juju-inside-an-openstack-bastion)
-* [Deploy Charmed MySQL](#deploy-charmed-mysql)
-* [(Optional) Access the OpenStack dashboard](#optional-access-the-openstack-dashboard)
 ---
 
 ## Install and bootstrap Sunbeam
@@ -63,13 +58,13 @@ Machine  State    Address          Inst id                               Base
 
 ## (Optional) Access the OpenStack dashboard 
 Follow the official guide: [Accessing the OpenStack dashboard].
-[note]
+```{note}
 When using a Multipass VM, you may need to manually route OpenStack IPs. For example:
 ```
 sudo ip route add 10.10.10.0/24 via 10.76.203.210 
 ```
 where `10.76.203.210` is the IP of the Multipass VM and  `10.10.10.0` is the network returned by `sunbeam dashboard-url`. 
-[/note]
+```
 
 The image below is an example of the OpenStack dashboard view (bastion + juju controller + 3 `mysql` nodes):
 
@@ -78,8 +73,9 @@ The image below is an example of the OpenStack dashboard view (bastion + juju co
 > To learn more about deploying and operating MySQL, see the [Charmed MySQL tutorial][Tutorial].
 
 <!-- LABELS-->
-[Tutorial]: /t/9922
+[Tutorial]: /tutorial/index
 [Single-node guided]: https://microstack.run/docs/single-node-guided
-[Accessing the OpenStack dashboard]: https://microstack.run/docs/dashboard
-[Images Sync]: https://microstack.run/docs/images
-[Manage workloads with Juju]: https://microstack.run/docs/juju-workloads
\ No newline at end of file
+[Accessing the OpenStack dashboard]: https://canonical-openstack.readthedocs-hosted.com/en/latest/how-to/misc/using-the-openstack-dashboard/
+[Images Sync]: https://canonical-openstack.readthedocs-hosted.com/en/latest/how-to/features/images-sync/
+[Manage workloads with Juju]: https://canonical-openstack.readthedocs-hosted.com/en/latest/how-to/misc/manage-workloads-with-juju/
+
diff --git a/docs/how-to/h-deploy-terraform.md b/docs/how-to/deploy/terraform.md
similarity index 86%
rename from docs/how-to/h-deploy-terraform.md
rename to docs/how-to/deploy/terraform.md
index 4883e8d743..e5ce41145f 100644
--- a/docs/how-to/h-deploy-terraform.md
+++ b/docs/how-to/deploy/terraform.md
@@ -1,3 +1,4 @@
+
 # How to deploy using Terraform
 
 [Terraform](https://www.terraform.io/) is an infrastructure automation tool to provision and manage resources in clouds or data centers. To deploy Charmed MySQL using Terraform and Juju, you can use the [Juju Terraform Provider](https://registry.terraform.io/providers/juju/juju/latest). 
@@ -6,21 +7,13 @@ The easiest way is to start from [these examples of terraform modules](https://g
 
 For an in-depth introduction to the Juju Terraform Provider, read [this Discourse post](https://discourse.charmhub.io/t/6939).
 
-[note]
-**Note**: Storage support was added in [Juju Terraform Provider version 0.13+](https://github.com/juju/terraform-provider-juju/releases/tag/v0.13.0).
-[/note]
-
-## Summary
-* [Install Terraform tooling](#install-terraform-tooling)
-* [Verify the deployment](#verify-the-deployment)
-* [Apply the deployment](#apply-the-deployment)
-* [Check deployment status](#check-deployment-status)
-* [Clean up](#clean-up)
----
+```{note}
+Storage support was added in [Juju Terraform Provider version 0.13+](https://github.com/juju/terraform-provider-juju/releases/tag/v0.13.0).
+```
 
 ## Install Terraform tooling
 
-This guide assumes Juju is installed and you have an LXD controller already bootstrapped. For more information, check the [Set up the environment](/t/9924) tutorial page.
+This guide assumes Juju is installed and you have an LXD controller already bootstrapped. For more information, check the [Charmed MySQL tutorial](/tutorial/index).
 
 Let's install Terraform Provider and example modules:
 ```shell
@@ -103,7 +96,7 @@ Continue to operate the charm as usual from here or apply further Terraform chan
 
 ## Clean up
 
-To keep the house clean, remove the newly deployed Charmed PostgreSQL by running
+To keep the house clean, remove the newly deployed Charmed MySQL by running
 ```shell
 terraform destroy -var "juju_model_name=my-model"
 ```
@@ -161,8 +154,9 @@ juju_application.machine_mysql: Destruction complete after 0s
 Destroy complete! Resources: 1 destroyed.
 ```
 ---
-[note]
+```{note}
 For more examples of Terraform modules for VM, see the other directories in the [`terraform-modules` repository](https://github.com/canonical/terraform-modules/tree/main/modules/machine).
-[/note]
+```
+
+Feel free to [contact us](/reference/contacts) if you have any question and [collaborate with us on GitHub](https://github.com/canonical/terraform-modules)!
 
-Feel free to [contact us](/t/11867) if you have any question and [collaborate with us on GitHub](https://github.com/canonical/terraform-modules)!
\ No newline at end of file
diff --git a/docs/how-to/development/index.md b/docs/how-to/development/index.md
new file mode 100644
index 0000000000..c13d3eceb0
--- /dev/null
+++ b/docs/how-to/development/index.md
@@ -0,0 +1,11 @@
+# Development
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Integrate with your charm <integrate-with-your-charm>
+Migrate data via mysqldump <migrate-data-via-mysqldump>
+Migrate data via mydumper <migrate-data-via-mydumper>
+Migrate data via backup/restore <migrate-data-via-backup-restore>
+```
diff --git a/docs/how-to/development/integrate-with-your-charm.md b/docs/how-to/development/integrate-with-your-charm.md
new file mode 100644
index 0000000000..330b44945d
--- /dev/null
+++ b/docs/how-to/development/integrate-with-your-charm.md
@@ -0,0 +1,46 @@
+# How to integrate a database with your charm
+
+Charmed MySQL can be integrated with any charmed application that supports its interfaces. This page provides some guidance and resources for charm developers to develop, integrate, and troubleshoot their charm so that it may connect with MySQL.
+
+## Check supported interfaces
+
+First, we recommend that you check [the supported interfaces](/explanation/interfaces-and-endpoints) of the current charm. You have the option to use modern (preferred) or legacy interfaces. 
+
+Most existing charms currently use [ops-lib-pgsql](https://github.com/canonical/ops-lib-pgsql) interface (legacy). 
+
+For new charms, **Canonical recommends using [data-platform-libs](https://github.com/canonical/data-platform-libs).**
+
+```{seealso}
+[MySQL K8s legacy charm explanation](/explanation/legacy-charm)
+```
+
+## Integrate your charm with MySQL
+
+Refer to [mysql-test-app](https://github.com/canonical/mysql-test-app) as a practical example of implementing data-platform-libs interfaces to integrate a charm with Charmed MySQL.
+
+```{seealso}
+[Juju > Integration](https://documentation.ubuntu.com/juju/3.6/reference/relation/)
+```
+
+## Troubleshooting and testing
+
+* To learn the basics of charm debugging, start with [Juju > How to debug a charm](https://juju.is/docs/sdk/debug-a-charm)
+* To troubleshoot Charmed MySQL, see the [Troubleshooting](/reference/troubleshooting/index) page.
+* To test the charm, check the [Testing](/reference/software-testing) reference
+
+## FAQ
+
+> *Does the requirer need to set anything in relation data?*
+
+It depends on the interface. Check the `mysql_client` [interface requirements](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/mysql_client/v0/README.md).
+
+> *Is there a charm library available, or does my charm need to compile the mysql relation data on its own?*
+
+Yes, a library is available: [data-platform-libs](https://github.com/canonical/data-platform-libs).
+
+> *How do I obtain the database URL/URI?*
+
+This feature is [planned](https://warthogs.atlassian.net/browse/DPE-2278) but currently missing.
+
+[Contact us](/reference/contacts) if you have any questions, issues and/or ideas!
+
diff --git a/docs/how-to/development/migrate-data-via-backup-restore.md b/docs/how-to/development/migrate-data-via-backup-restore.md
new file mode 100644
index 0000000000..311bd9f942
--- /dev/null
+++ b/docs/how-to/development/migrate-data-via-backup-restore.md
@@ -0,0 +1,27 @@
+# Migrate data via backup/restore
+
+```{note}
+Use ['mysqldump' manual](/how-to/development/migrate-data-via-mysqldump) to migrate [legacy charms](/explanation/legacy-charm) data.
+```
+
+This Charmed MySQL operator is able to restore [it's own backups](/how-to/back-up-and-restore/restore-a-backup) stored on [S3-compatible storage](/how-to/back-up-and-restore/configure-s3-aws). The same restore approach is applicable to restore [foreign backups](/how-to/back-up-and-restore/migrate-a-cluster) made by different Charmed MySQL installation or even another MySQL charms. The backup have to be created manually using Percona XtraBackup!
+
+```{warning}
+Canonical Data team describes here the general approach and does NOT support nor guarantees the restoration results. Always test migration in a test environment before performing it in Production!
+```
+
+Before the data migration check all [limitations of the modern Charmed MySQL](/reference/system-requirements) charm!
+Please check [your application compatibility](/explanation/legacy-charm) with Charmed MySQL before migrating production data from legacy charm!
+
+The approach:
+
+* retrieve root/admin level credentials from legacy charm. See examples [here](/how-to/development/migrate-data-via-mysqldump).
+* install [Percona XtraBackup for MySQL](https://www.percona.com/software/mysql-database/percona-xtrabackup) inside the old charm OR remotely. Ensure version is compatible with xtrabackup in `Charmed MySQL` revision you are going to deploy! See [examples](https://docs.percona.com/percona-xtrabackup/8.0/installation.html). BTW, you can use `charmed-mysql` [SNAP](https://snapcraft.io/charmed-mysql)/[ROCK](https://github.com/canonical/charmed-mysql-rock) directly (more details [here](/explanation/architecture)).
+* configure storage for database backup (local or remote, S3-based is recommended).
+* create a first full logical backup during the off-peak, [example of backup command](https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/mysql.py#L2160-L2185).
+* [restore the foreign backup](/how-to/back-up-and-restore/migrate-a-cluster) to Charmed MySQL Lab installation.
+* perform all the necessary tests to make sure your application accepted new DB.
+* schedule and perform the final production migration re-using the last steps above.
+
+Do you have questions? [Contact us](/reference/contacts) if you are interested in such a data migration!
+
diff --git a/docs/how-to/h-migrate-mydumper.md b/docs/how-to/development/migrate-data-via-mydumper.md
similarity index 86%
rename from docs/how-to/h-migrate-mydumper.md
rename to docs/how-to/development/migrate-data-via-mydumper.md
index 529fd4beae..d873170019 100644
--- a/docs/how-to/h-migrate-mydumper.md
+++ b/docs/how-to/development/migrate-data-via-mydumper.md
@@ -1,6 +1,8 @@
-# DB data migration using 'mydumper'
+# Migrate data via mydumper
 
-> :information_source: **Tip**: use ['mysqldump' manual](/t/11958) to migrate [legacy charms](/t/10788) data.
+```{note}
+Use ['mysqldump' manual](/how-to/development/migrate-data-via-mysqldump) to migrate [legacy charms](/explanation/legacy-charm) data.
+```
 
 The [mydumper](https://github.com/mydumper/mydumper) tool is a powerful MySQL logical data-migration tool, including:
 
@@ -9,8 +11,8 @@ The [mydumper](https://github.com/mydumper/mydumper) tool is a powerful MySQL lo
 
 Both tools use multi-threading capabilities and support S3 storage to write/read dumps. MyDumper is Open Source and maintained by the community, it is not a Percona, MariaDB, MySQL or Canonical product.
 
-Before the data migration check all [limitations of the modern Charmed MySQL](/t/11742#mysql-gr-limits) charm!
-Please check [your application compatibility](/t/10788) with Charmed MySQL before migrating production data from legacy charm!
+Before the data migration check all [limitations of the modern Charmed MySQL](/reference/system-requirements) charm!
+Please check [your application compatibility](/explanation/legacy-charm) with Charmed MySQL before migrating production data from legacy charm!
 
 ## Installation:
 Install the latest version from [GitHub](https://github.com/mydumper/mydumper/releases):
@@ -57,4 +59,5 @@ NEW_DB_USER=serverconfig
 NEW_DB_PASS=...
 
 myloader -h ${NEW_DB_IP} -u ${NEW_DB_USER} -p ${NEW_DB_PASS} --directory=export-20230927-123337 --overwrite-tables
-```
\ No newline at end of file
+```
+
diff --git a/docs/how-to/h-migrate-mysqldump.md b/docs/how-to/development/migrate-data-via-mysqldump.md
similarity index 84%
rename from docs/how-to/h-migrate-mysqldump.md
rename to docs/how-to/development/migrate-data-via-mysqldump.md
index f7f4f99e13..25659c078c 100644
--- a/docs/how-to/h-migrate-mysqldump.md
+++ b/docs/how-to/development/migrate-data-via-mysqldump.md
@@ -1,14 +1,8 @@
-[note]
-**Note**: All commands are written for `juju >= v.3.0`
-
-For more information, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
-
 # Migrate database data via `mysqldump`
 
 This document describes database **data** migration only!
 
-> For information about integrating charms via juju interfaces, see [How to integrate a database with my charm](/t/11890).
+> For information about integrating charms via juju interfaces, see [How to integrate a database with my charm](/how-to/development/integrate-with-your-charm).
 
 ## Do you need to migrate?
 
@@ -21,11 +15,11 @@ DB_CHARM= < mariadb | percona-cluster | mysql-innodb-cluster >
 juju show-application ${DB_CHARM} | yq '.[] | .charm'
 ```
 
-[note type=caution]
+```{caution}
 No migration is necessary if the output above is `mysql`! 
 
-Still, this manual can be used to copy data between different installations of the same (modern) charm `mysql`. The [backup/restore method](/t/9906) is recommended for migrations between modern charms.
-[/note]
+Still, this manual can be used to copy data between different installations of the same (modern) charm `mysql`. The [backup/restore method](/how-to/back-up-and-restore/migrate-a-cluster) is recommended for migrations between modern charms.
+```
 
 ## Summary
 
@@ -33,8 +27,8 @@ The list of MariaDB/MySQL **legacy VM charms**:
 
 * [MariaDB](https://charmhub.io/mariadb)
 * [Percona Cluster](https://charmhub.io/percona-cluster)
-* [MySQL Innodb Cluster](https://charmhub.io/mysql-innodb-cluster)
-* <s>[OSM MariaDB K8s](https://charmhub.io/charmed-osm-mariadb-k8s)</s> (K8s flavour, use [separate manual](https://charmhub.io/mysql-k8s/docs/h-develop-mysqldump))
+* [MySQL InnoDB Cluster](https://charmhub.io/mysql-innodb-cluster)
+* <s>[OSM MariaDB K8s](https://charmhub.io/charmed-osm-mariadb-k8s)</s> (K8s flavour, use [separate manual](https://charmhub.io/mysql-k8s/docs/h-migrate-mysqldump))
 
 There is a minor difference in commands for each of the legacy charms, but the general logic is common:
 
@@ -46,22 +40,24 @@ There is a minor difference in commands for each of the legacy charms, but the g
 * Add relation to modern charm
 * Validate results and remove legacy charm
 
-Before the data migration check all [limitations of the modern Charmed MySQL](/t/11742#mysql-gr-limits) charm!<br/>Please check [your application compatibility](/t/10788) with Charmed MySQL before migrating production data from legacy charm!
+Before the data migration check all [limitations of the modern Charmed MySQL](/reference/system-requirements) charm!<br/>Please check [your application compatibility](/explanation/legacy-charm) with Charmed MySQL before migrating production data from legacy charm!
 
-> :warning: Always perform the migration in a test environment before performing it in production!
+```{warning}
+Always perform the migration in a test environment before performing it in production!
+```
 
 ## Prerequisites
 
 - Client machine with access to deployed legacy charm
-- Juju version 2.9 or later (check the [Juju tech details](/t/11959) for the different Juju versions)
+- Juju version 2.9 or later (check the [Juju tech details](/explanation/juju) for the different Juju versions)
 - Enough storage in the cluster to support backup/restore of the databases.
 - `mysql-client` on client machine (install by running `sudo apt install mysql-client`).
 
-[note type=caution]
-Most legacy database charms support old Ubuntu series only, while Juju 3.x does [NOT support](https://discourse.charmhub.io/t/roadmap-releases/5064#heading--juju-3-0-0---22-oct-2022) Ubuntu Bionic.
+```{caution}
+Most legacy database charms support old Ubuntu series only, while Juju 3.x does [NOT support](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-3-0-0-22-oct-2022) Ubuntu Bionic.
 
 It is recommended to use the latest stable revision of the charm on Ubuntu Jammy and Juju 3.x
-[/note]
+```
 
 ## Obtain existing database credentials
 
@@ -165,7 +161,7 @@ diff "${OLD_DB_DUMP}" "${NEW_DB_DUMP}"
 
 The difference between two SQL backup files should be limited to server versions, IP addresses, timestamps and other non data related information. Example of difference:
 
-```python
+```text
 < -- Host: 10.1.45.226 Database: katib
 ---
 > -- Host: 10.1.46.40 Database: katib
@@ -214,6 +210,5 @@ juju remove-application --destroy-storage < mariadb | percona-cluster | mysql-in
 
 ## Links
 
-Database data migration is also possible using [`mydumper`](/t/11988).
+Database data migration is also possible using [`mydumper`](/how-to/development/migrate-data-via-mydumper).
 
-> :tipping_hand_man: This manual based on [Kubeflow DB migration guide](https://github.com/canonical/bundle-kubeflow/blob/main/docs/db-migration-guide.md).
\ No newline at end of file
diff --git a/docs/how-to/h-enable-tls.md b/docs/how-to/enable-tls.md
similarity index 78%
rename from docs/how-to/h-enable-tls.md
rename to docs/how-to/enable-tls.md
index 44b494e4b7..20a5202f94 100644
--- a/docs/how-to/h-enable-tls.md
+++ b/docs/how-to/enable-tls.md
@@ -1,19 +1,12 @@
-[note]
-**Note**: All commands are written for `juju >= v.3.1`
-
-If you're using `juju 2.9`, check the [`juju 3.0` Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
-
 # How to enable TLS encryption
-This guide will show how to enable TLS using the [`self-signed-certificates` operator](https://github.com/canonical/self-signed-certificates-operator) as an example.
 
-[note type="caution"]
-**[Self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) are not recommended for a production environment.**
+This guide describes how to enable TLS using the [`self-signed-certificates` operator](https://github.com/canonical/self-signed-certificates-operator) as an example.
 
-Check [this guide](/t/11664) for an overview of the TLS certificates charms available. 
-[/note]
+```{caution}
+**[Self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) are not recommended for a production environment.**
 
----
+Check [this guide](https://discourse.charmhub.io/t/11664) for an overview of the TLS certificates charms available. 
+```
 
 ## Enable TLS
 
@@ -55,4 +48,5 @@ juju run mysql/2 set-tls-private-key
 Disable TLS by removing the integration:
 ```shell
 juju remove-relation self-signed-certificates mysql
-```
\ No newline at end of file
+```
+
diff --git a/docs/how-to/h-external-access.md b/docs/how-to/external-network-access.md
similarity index 55%
rename from docs/how-to/h-external-access.md
rename to docs/how-to/external-network-access.md
index 781d359855..38a0915866 100644
--- a/docs/how-to/h-external-access.md
+++ b/docs/how-to/external-network-access.md
@@ -1,13 +1,16 @@
-# How to connect DB from outside of DB LAN
+# How to connect to your database outside the local network
+
+This page summarises resources for setting up deployments where an external application must connect to a MySQL database from outside the local area network.
 
 ## External application (non-Juju)
 
-[u]Use case[/u]: the client application is a non-Juju application outside of Juju / DB LAN.
+**Use case**: the client application is a non-Juju application outside of Juju / DB LAN.
 
 There are many possible ways to connect the Charmed MySQL database from outside of the LAN the DB cluster is located. The available options are heavily depend on the cloud/hardware/virtualization in use. One of the possible options is to use [virtual IP addresses (VIP)](https://en.wikipedia.org/wiki/Virtual_IP_address) which the charm MySQL Router provides with assist of the charm/interface `hacluster`. Please follow the [MySQL Router documentation](https://charmhub.io/mysql-router/docs/h-external-access?channel=dpe/candidate) for such configuration.
 
 ## External relation (Juju)
 
-[u]Use case[/u]: the client application is a Juju application outside of DB deployment (e.g. hybrid Juju deployment with different VM clouds/controllers).
+**Use case**: the client application is a Juju application outside of DB deployment (e.g. hybrid Juju deployment with different VM clouds/controllers).
+
+In this case the the cross-controllers-relation is necessary. Please [contact](/reference/contacts) the Data team to discuss the possible option for your use case.
 
-In this case the the cross-controllers-relation is necessary. Please [contact](/t/11867) Data team to discuss the possible option for your use case.
\ No newline at end of file
diff --git a/docs/how-to/h-async-failover.md b/docs/how-to/h-async-failover.md
deleted file mode 100644
index 002c81f32a..0000000000
--- a/docs/how-to/h-async-failover.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# Switchover / Failover of Async replication
-
-## Pre-requisites
-
-Make sure both `Rome` and `Lisbon` Clusters are deployed using the [Async Deployment manual](/t/14169)!
-
-## Switchover (safe)
-
-Assuming `Rome` is currently `Primary` and you want to promote `Lisbon` to be new primary<br/>(`Rome` will be converted to `StandBy` member):
-
-```shell
-
-juju run -m lisbon db2/leader promote-to-primary
-
-```
-
-## Failover (forced)
-
-[note type="caution"]
-
-**Warning**: this is a **dangerous** operation which can cause the split-brain situation. It should be executed if Primary cluster is no longer exist (lost) ONLY! Otherwise please use safe switchover procedure above!
-
-[/note]
-
-Assuming `Rome` was a `Primary` (before we lost the cluster `Rome`) and you want to promote `Lisbon` to be the new primary:
-
-```shell
-
-juju run -m lisbon db2/leader promote-to-primary force=True
-
-```
-
-> **Warning**: The `force` will cause the old primary to be invalidated.
\ No newline at end of file
diff --git a/docs/how-to/h-development-integrate.md b/docs/how-to/h-development-integrate.md
deleted file mode 100644
index 089759ea5e..0000000000
--- a/docs/how-to/h-development-integrate.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# How to integrate a database with your charm
-
-Charmed MySQL can be integrated with any charmed application that supports its interfaces. This page provides some guidance and resources for charm developers to develop, integrate, and troubleshoot their charm so that it may connect with MySQL.
-
-## Summary
-* Check supported interfaces 
-* Integrate your charm with MySQL
-* Troubleshooting & testing
-* FAQ
-
----
-
-## Check supported interfaces
-
-First, we recommend that you check [the supported interfaces](/t/10250) of the current charm. You have the option to use modern (preferred) or legacy interfaces. 
-
-Most existing charms currently use [ops-lib-pgsql](https://github.com/canonical/ops-lib-pgsql) interface (legacy). 
-> See also: [MySQL legacy charm explanation](/t/10788)
-
- For new charms, **Canonical recommends using [data-platform-libs](https://github.com/canonical/data-platform-libs).**
-
-## Integrate your charm with MySQL
-
-> See also: 
-> * [Juju documentation | Integration](https://juju.is/docs/juju/integration)
-> * [Juju documentation | Integrate your charm with PostgreSQL](https://juju.is/docs/sdk/integrate-your-charm-with-postgresql)
-
-Refer to [mysql-test-app](https://github.com/canonical/mysql-test-app) as a practical example of implementing data-platform-libs interfaces to integrate a charm with Charmed MySQL.
-
-## Troubleshooting and testing
-* To learn the basics of charm debugging, start with [Juju | How to debug a charm](https://juju.is/docs/sdk/debug-a-charm)
-* To troubleshoot Charmed MySQL, see the [Troubleshooting](/t/11891) page.
-* To test the charm, check the [Testing](/t/11770) reference
-
-## FAQ
-**Does the requirer need to set anything in relation data?**
-> It depends on the interface. Check the `mysql_client` [interface requirements](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/mysql_client/v0/README.md).
-
-**Is there a charm library available, or does my charm need to compile the mysql relation data on its own?**
-> Yes, a library is available: [data-platform-libs](https://github.com/canonical/data-platform-libs).
-
-**How do I obtain the database url/uri?**
->This feature is [planned](https://warthogs.atlassian.net/browse/DPE-2278) but currently missing.
-
-[Contact us](/t/11867) if you have any questions, issues and/or ideas!
\ No newline at end of file
diff --git a/docs/how-to/h-migrate-backup-restore.md b/docs/how-to/h-migrate-backup-restore.md
deleted file mode 100644
index 00d99413dc..0000000000
--- a/docs/how-to/h-migrate-backup-restore.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# DB data migration using ‘backup/restore’
-
-> :information_source: **Tip**: use ['mysqldump' manual](/t/11958) to migrate [legacy charms](/t/10788) data.
-
-This Charmed MySQL operator is able to restore [it's own backups](/t/9908) stored on [S3-compatible storage](/t/9894). The same restore approach is applicable to restore [foreign backups](/t/9906) made by different Charmed MySQL installation or even another MySQL charms. The backup have to be created manually using Percona XtraBackup!
-
-> :warning: Canonical Data team describes here the general approach and does NOT support nor guaranties the restoration results. Always test migration in LAB before performing it in Production!
-
-Before the data migration check all [limitations of the modern Charmed MySQL](/t/11742#mysql-gr-limits) charm!
-Please check [your application compatibility](/t/10788) with Charmed MySQL before migrating production data from legacy charm!
-
-The approach:
-
-* retrieve root/admin level credentials from legacy charm. See examples [here](/t/11958).
-* install [Percona XtraBackup for MySQL](https://www.percona.com/software/mysql-database/percona-xtrabackup) inside the old charm OR remotely. Ensure version is compatible with xtrabackup in `Charmed MySQL` revision you are going to deploy! See [examples](https://docs.percona.com/percona-xtrabackup/8.0/installation.html). BTW, you can use `charmed-mysql` [SNAP](https://snapcraft.io/charmed-mysql)/[ROCK](https://github.com/canonical/charmed-mysql-rock) directly (more details [here](/t/11756#hld)).
-* configure storage for database backup (local or remote, S3-based is recommended).
-* create a first full logical backup during the off-peak, [example of backup command](https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/mysql.py#L2160-L2185).
-* [restore the foreign backup](/t/9906) to Charmed MySQL Lab installation.
-* perform all the necessary tests to make sure your application accepted new DB.
-* schedule and perform the final production migration re-using the last steps above.
-
-Do you have questions? [Contact us](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in such a data migration!
\ No newline at end of file
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
new file mode 100644
index 0000000000..2d2fd75e4f
--- /dev/null
+++ b/docs/how-to/index.md
@@ -0,0 +1,83 @@
+# How-to guides
+
+Key processes and common tasks for managing and using Charmed MySQL on machines.
+
+## Deployment and setup
+
+Guidance for different cloud services and special deployments.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Deploy <deploy/index>
+```
+
+## Usage and maintenance
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Integrate with another application <integrate-with-another-application>
+Scale replicas <scale-replicas>
+Manage passwords <manage-passwords>
+Enable TLS <enable-tls>
+External network access <external-network-access>
+Primary Switchover <primary-switchover>
+```
+
+## Back up and restore
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Back up and restore <back-up-and-restore/index>
+```
+
+## Monitoring (COS)
+
+Integrate with observability services like Grafana, Prometheus, and Tempo.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Monitoring (COS) <monitoring-cos/index>
+```
+
+## Upgrades
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Upgrade <upgrade/index>
+```
+
+## Cross-regional (cluster-cluster) async replication
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Cross-regional async replication <cross-regional-async-replication/index>
+```
+
+## Development
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Development <development/index>
+```
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+:hidden:
+
+Contribute <contribute>
+```
\ No newline at end of file
diff --git a/docs/how-to/h-integrate.md b/docs/how-to/integrate-with-another-application.md
similarity index 79%
rename from docs/how-to/h-integrate.md
rename to docs/how-to/integrate-with-another-application.md
index 872f5a106d..977645105e 100644
--- a/docs/how-to/h-integrate.md
+++ b/docs/how-to/integrate-with-another-application.md
@@ -1,25 +1,10 @@
-[note]
-**Note**: All commands are written for `juju >= v.3.0`
-
-If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
-
 # How to integrate with another application
 
 [Integrations](https://juju.is/docs/juju/relation) (formerly “relations”) are connections between two applications with compatible endpoints. These connections simplify the creation and management of users, passwords, and other shared data.
 
 This guide shows how to integrate Charmed MySQL with both charmed and non-charmed applications.
 
-> For developer information about how to integrate your own charmed application with MySQL, see [Development > How to integrate with your charm](/t/11890).
-
-## Summary
-* [Integrate with a charmed application](#integrate-with-a-charmed-application)
-  * [Modern interface](#modern-interface)
-  * [Legacy interface](#legacy-interface)
-* [Integrate with a non-charmed application](#integrate-with-a-non-charmed-application)
-* [Rotate application passwords](#rotate-application-passwords)
-
----
+> For developer information about how to integrate your own charmed application with MySQL, see [Development > How to integrate with your charm](/how-to/development/integrate-with-your-charm).
 
 ## Integrate with a charmed application
 
@@ -38,10 +23,10 @@ juju remove-relation mysql <charm>
 ```
 
 ### Legacy `mysql` interface
-[note type="caution"]
+```{caution}
 Note that this interface is **deprecated**.
-See more information in [Explanation > Legacy charm](/t/10788).
-[/note]
+See more information in [Explanation > Legacy charm](/explanation/legacy-charm).
+```
 
 To integrate via the legacy interface, run
  ```shell
@@ -95,4 +80,5 @@ To randomly generate a password for the `operator` user, run
 
 ```shell
 juju run mysql/leader set-password
-```
\ No newline at end of file
+```
+
diff --git a/docs/how-to/manage-passwords.md b/docs/how-to/manage-passwords.md
new file mode 100644
index 0000000000..44a8636df2
--- /dev/null
+++ b/docs/how-to/manage-passwords.md
@@ -0,0 +1,41 @@
+# Manage passwords
+
+Charmed MySQL user credentials are managed with Juju's `get-password` and `set-password` actions.
+
+```{seealso}
+[](/explanation/users)
+```
+
+## Get password
+
+To retrieve user credentials for the `root` user, run the `get-password` action on the leader unit as follows:
+
+```shell
+juju run mysql/leader get-password
+```
+
+To retrieve credentials for a different user:
+
+```shell
+juju run mysql/leader get-password username=<username>
+```
+
+### Set password
+
+To change the `root` user's password to a new, randomized password:
+
+```shell
+juju run mysql/leader set-password
+```
+
+To set a manual password for the `root` user:
+
+```shell
+juju run mysql/leader set-password password=<password>
+```
+
+To set a manual password for another user:
+
+```shell
+juju run mysql/leader set-password username=<username> password=<password>
+```
\ No newline at end of file
diff --git a/docs/how-to/monitoring-cos/alert-rules-grafana.png b/docs/how-to/monitoring-cos/alert-rules-grafana.png
new file mode 100644
index 0000000000..9a64d01494
Binary files /dev/null and b/docs/how-to/monitoring-cos/alert-rules-grafana.png differ
diff --git a/docs/how-to/h-enable-alert-rules.md b/docs/how-to/monitoring-cos/enable-alert-rules.md
similarity index 64%
rename from docs/how-to/h-enable-alert-rules.md
rename to docs/how-to/monitoring-cos/enable-alert-rules.md
index ac04769a52..3f35b61a4e 100644
--- a/docs/how-to/h-enable-alert-rules.md
+++ b/docs/how-to/monitoring-cos/enable-alert-rules.md
@@ -1,30 +1,41 @@
-# How to enable COS Alert Rules
+# How to enable Alert Rules
 
 This guide will show how to set up [Pushover](https://pushover.net/) to receive alert notifications from the COS Alert Manager with [Awesome Alert Rules](https://samber.github.io/awesome-prometheus-alerts/).
 
-Charmed MySQL VM ships a pre-configured and pre-enabled [list of Awesome Alert Rules].
+Charmed MySQL K8s ships a pre-configured and pre-enabled list of Awesome Alert Rules.
 
-<details><summary>Screenshot of alert rules in the Grafana web interface</summary>
+```{seealso}
+* [](/reference/alert-rules)
+* [Observability documentation > Add alert rules](https://documentation.ubuntu.com/observability/how-to/adding-alert-rules/)
+```
 
-![Screenshot from 2024-01-18 20-05-52|690x439](upload://j6WSPQ1BzoFzqIg2jm1mTq79SMo.png)
-</details>
+<details><summary>Screenshot of MySQL alert rules in Grafana web interface
+</summary>
 
-For information about accessing and managing COS Alert Rules, refer to the [COS documentation](https://charmhub.io/cos-lite).
+![MySQL alert rules in the Grafana web interface](alert-rules-grafana.png)
+</details>
 
 ## Prerequisites
-* A deployed [Charmed MySQL VM operator]
-* A deployed [`cos-lite` bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
-* Fully configured [COS Monitoring]
+
+* `cos-lite` bundle deployed in a Kubernetes environment
+  * See the [COS Microk8s tutorial](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
+* Fully configured COS monitoring
+  * See [](/how-to/monitoring-cos/enable-monitoring)
+
+---
 
 ## Enable COS alerts for Pushover
+
 The following section is an example of the [Pushover](https://pushover.net/) alerts aggregator.
 
 The first step is to create a new account on Pushover (or use an existing one). The goal is to have the 'user key' and 'token' to authorize alerts for the Pushover application. Follow this straightforward [Pushover guide](https://support.pushover.net/i175-how-to-get-a-pushover-api-or-pushover-application-token).
 
 Next, create a new [COS Alert Manager](https://charmhub.io/alertmanager-k8s) config (replace `user_key` and `token` with yours):
+
 ```shell
 cat > myalert.yaml << EOF
 ```
+
 ```yaml
 global:
   resolve_timeout: 5m
@@ -52,26 +63,24 @@ receivers:
 templates: []
 EOF
 ```
+
 Upload and apply newly the created alert manager config:
-```
+
+```shell
 juju switch <k8s_cos_controller>:<cos_model_name>
 juju config alertmanager config_file=@myalert.yaml
 ```
 
 At this stage, the COS Alert Manager will start sending alert notifications to Pushover. Users can receive them on all supported [Pushover clients/apps](https://pushover.net/clients). 
 
-The image below shows an example of the Pushover web client:
-
-![image|690x439](upload://vqUcKpZ5R4wQLmY2HYGV5fz5pNU.jpeg)
+<details><summary>Screenshot of Pushover web client
+</summary>
 
-## Alert receivers
+![Pushover web client](pushover-web-client.jpeg)
+</details>
 
-The similar way as above, COS alerts can be send to the long [list of supported receivers](https://prometheus.io/docs/alerting/latest/configuration/#receiver-integration-settings).
+## Other alert receivers
 
-Do you have questions? [Contact us]!
+In a similar way to the COS Alert Manager, alerts can be send to [several other supported receivers](https://prometheus.io/docs/alerting/latest/configuration/#receiver-integration-settings).
 
-<!-- Links -->
-[Contact us]: /t/11867
-[Charmed MySQL VM operator]: /t/11870
-[COS Monitoring]: /t/9900
-[list of Awesome Alert Rules]: /t/15839
\ No newline at end of file
+Do you have questions? [Contact us](/reference/contacts)!
diff --git a/docs/how-to/h-enable-monitoring.md b/docs/how-to/monitoring-cos/enable-monitoring.md
similarity index 81%
rename from docs/how-to/h-enable-monitoring.md
rename to docs/how-to/monitoring-cos/enable-monitoring.md
index e5587bf3ae..180289abf2 100644
--- a/docs/how-to/h-enable-monitoring.md
+++ b/docs/how-to/monitoring-cos/enable-monitoring.md
@@ -1,26 +1,26 @@
-[note]
-**Note**: All commands are written for `juju >= v.3.0`
-
-If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
-
 # How to enable monitoring (COS)
 
 This guide will show you how to deploy and configure the [COS Lite bundle](https://charmhub.io/cos-lite) to monitor your deployment with Grafana.
 
 ## Prerequisites
-* [Have a Charmed MySQL deployed](/t/9904)
-* [Deploy 'cos-lite' bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
+
+* `cos-lite` bundle deployed in a Kubernetes environment
+  * See the [COS Microk8s tutorial](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
 
 ---
 
+## Offer interfaces via the COS controller
+
 First, switch to COS K8s environment and offer COS interfaces to be cross-model integrated (related) with Charmed MySQL VM model.
 
 To switch to the Kubernetes controller for the COS model, run
+
 ```shell
 juju switch <k8s_controller>:<cos_model_name>
 ```
+
 To offer the COS interfaces, run
+
 ```shell
 juju offer grafana:grafana-dashboard
 juju offer loki:logging
@@ -28,18 +28,23 @@ juju offer prometheus:receive-remote-write
 ```
 
 ## Consume offers via the MySQL model
+
 Next, we will switch to Charmed MySQL VM model, find offers and integrate (relate) with them.
 
 We are on the Kubernetes controller for the COS model. To switch to the MySQL model, run
+
 ```shell
 juju switch <machine_controller_name>:<mysql_model_name>
 ```
-To find offers, run
+
+To find offers, run the following command (make sure not to miss the colon `:` at the end!):
+
 ```shell
-juju find-offers <k8s_controller>: # Do not miss ':' here!
+juju find-offers <k8s_controller>:
 ```
 
-A similar output should appear, if `k8s` is the k8s controller name and `cos` the model where `cos-lite` has been deployed:
+A similar output should appear, where `k8s` is the k8s controller name and `cos` the model where `cos-lite` has been deployed:
+
 ```shell
 Store  URL                    Access  Interfaces
 k8s    admin/cos.grafana      admin   grafana:grafana-dashboard
@@ -48,7 +53,8 @@ k8s    admin/cos.prometheus   admin   prometheus:receive-remote-write
 ...
 ```
 
-To consume offers to be reachable in the current model, run
+Consume offers to be reachable in the current model:
+
 ```shell
 juju consume k8s:admin/cos.grafana
 juju consume k8s:admin/cos.loki
@@ -56,15 +62,21 @@ juju consume k8s:admin/cos.prometheus
 ```
 
 ## Deploy and integrate Grafana
-First, deploy the [grafana-agent](https://charmhub.io/grafana-agent) subordinate charm.
+
+First, deploy the [grafana-agent](https://charmhub.io/grafana-agent) subordinate charm:
+
 ```shell
 juju deploy grafana-agent
 ```
+
 Then, integrate (relate) it with Charmed MySQL
+
 ```shell
 juju integrate grafana-agent mysql:cos-agent
 ```
+
 Finally, integrate (relate) `grafana-agent` with consumed COS offers:
+
 ```shell
 juju integrate grafana-agent grafana
 juju integrate grafana-agent loki
@@ -73,8 +85,10 @@ juju integrate grafana-agent prometheus
 
 After this is complete, Grafana will show the new dashboards: `MySQL Exporter` and allows access for Charmed MySQL logs on Loki.
 
-### Sample outputs
-The example of `juju status` on Charmed MySQL VM model:
+### Example `juju status` outputs
+
+````{dropdown} Charmed MySQL K8s model
+
 ```shell
 ubuntu@localhost:~$ juju status
 Model      Controller  Cloud/Region         Version  SLA          Timestamp
@@ -97,7 +111,10 @@ Machine  State    Address        Inst id        Series  AZ  Message
 4        started  10.85.186.140  juju-fcde9e-4  jammy       Running
 ```
 
-The example of `juju status` on COS K8s model:
+````
+
+````{dropdown} COS K8s model
+
 ```shell
 ubuntu@localhost:~$ juju status
 Model  Controller   Cloud/Region        Version  SLA          Timestamp
@@ -125,8 +142,17 @@ loki         loki         loki-k8s        60   1/1        logging
 prometheus   prometheus   prometheus-k8s  103  1/1        receive-remote-write  prometheus_remote_write  provider
 ```
 
-### Connect Grafana web interface
-To connect Grafana web interface, follow the COS section "[Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)":
+````
+
+## Connect Grafana web interface
+
+To connect the Grafana web interface, follow the [Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)" section of the COS MicroK8s tutorial:
+
 ```shell
 juju run grafana/leader get-admin-password --model <k8s_controller>:<cos_model_name>
-```
\ No newline at end of file
+```
+
+## Full example of COS integration (MySQL K8s)
+
+[![asciicast](https://asciinema.org/a/580608.svg)](https://asciinema.org/a/580608)
+
diff --git a/docs/how-to/h-enable-tracing.md b/docs/how-to/monitoring-cos/enable-tracing.md
similarity index 63%
rename from docs/how-to/h-enable-tracing.md
rename to docs/how-to/monitoring-cos/enable-tracing.md
index 122705535a..47b2b5c01a 100644
--- a/docs/how-to/h-enable-tracing.md
+++ b/docs/how-to/monitoring-cos/enable-tracing.md
@@ -1,35 +1,21 @@
-[note]
-**Note**: All commands are written for `juju >= v3.1`
-
-If you're using `juju 2.9`, check the [`juju 3.0` Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
-
 # Enable tracing
-This guide contains the steps to enable tracing with [Grafana Tempo](https://grafana.com/docs/tempo/latest/) for your MySQL application. 
 
-To summarize:
-* [Deploy the Tempo charm in a COS K8s environment](#heading--deploy)
-* [Offer interfaces for cross-model integrations](#heading--offer)
-* [Consume and integrate cross-model integrations](#heading--consume)
-* [View MySQL traces on Grafana](#heading--view)
-
-
-[note type="caution"]
-**Warning:** This is feature is in development. It is **not recommended** for production environments. 
+This guide contains the steps to enable tracing with [Grafana Tempo](https://grafana.com/docs/tempo/latest/) for your MySQL application. 
 
-This feature is available for Charmed MySQL revision 237+ only.
-[/note]
+```{caution}
+This is feature is in development. It is **not recommended** for production environments. 
+```
 
 ## Prerequisites
-Enabling tracing with Tempo requires that you:
-- Have deployed a Charmed MySQL application
-  - See [How to manage units](https://discourse.charmhub.io/t/charmed-mysql-how-to-manage-units/9904)
-- Have deployed a 'cos-lite' bundle in a Kubernetes environment
-  - See [Getting started on MicroK8s](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
+
+* Charmed MySQL revision 237 or higher 
+  * See [](/how-to/upgrade/index)
+* `cos-lite` bundle deployed in a Kubernetes environment
+  * See the [COS Microk8s tutorial](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
 
 ---
 
-<a href="#heading--deploy"><h2 id="heading--deploy"> Deploy Tempo </h2></a>
+## Deploy Tempo
 
 First, switch to the Kubernetes controller where the COS model is deployed:
 
@@ -37,15 +23,17 @@ First, switch to the Kubernetes controller where the COS model is deployed:
 juju switch <k8s_controller_name>:<cos_model_name>
 ```
 
-Then, deploy the dependencies of Tempo following [this tutorial](https://discourse.charmhub.io/t/tutorial-deploy-tempo-ha-on-top-of-cos-lite/15489). In particular, we would want to:
-- Deploy the minio charm
+Then, deploy the dependencies of Tempo following [this tutorial](https://discourse.charmhub.io/t/tutorial-deploy-tempo-ha-on-top-of-cos-lite/15489). 
+
+To summarize:
+- Deploy the MinIO charm
 - Deploy the s3 integrator charm
-- Add a bucket in minio using a python script
-- Configure s3 integrator with the minio credentials
+- Add a bucket in MinIO using a python script
+- Configure s3 integrator with the MinIO credentials
 
-Finally, deploy and integrate with Tempo HA in [a monolithic setup](https://discourse.charmhub.io/t/tutorial-deploy-tempo-ha-on-top-of-cos-lite/15489#heading--deploy-monolithic-setup).
+Finally, deploy and integrate with Tempo HA in [a monolithic setup](https://discourse.charmhub.io/t/tutorial-deploy-tempo-ha-on-top-of-cos-lite/15489).
 
-<a href="#heading--offer"><h2 id="heading--offer"> Offer interfaces </h2></a>
+## Offer interfaces
 
 Next, offer interfaces for cross-model integrations from the model where Charmed MySQL is deployed.
 
@@ -62,7 +50,7 @@ juju switch <machine_controller_name>:<mysql_model_name>
 
 juju find-offers <k8s_controller_name>:  
 ```
-> :exclamation: Do not miss the "`:`" in the command above.
+> Do not miss the "`:`" in the command above!
 
 Below is a sample output where `k8s` is the K8s controller name and `cos` is the model where `cos-lite` and `tempo-k8s` are deployed:
 
@@ -77,9 +65,10 @@ Next, consume this offer so that it is reachable from the current model:
 juju consume k8s:admin/cos.tempo
 ```
 
-<a href="#heading--consume"><h2 id="heading--consume"> Consume interfaces </h2></a>
+## Consume interfaces
 
 First, deploy [Grafana Agent](https://charmhub.io/grafana-agent) from the `1/stable` channel:
+
 ```shell
 juju deploy grafana-agent --channel 1/stable
 ```
@@ -124,16 +113,19 @@ mysql:upgrade         mysql:upgrade            upgrade                peer
 tempo:tracing         grafana-agent:tracing    tracing                regular  
 ```
 
-[note]
-**Note:** All traces are exported to Tempo using HTTP. Support for sending traces via HTTPS is an upcoming feature.
-[/note]
+```{note}
+All traces are exported to Tempo using HTTP. Support for sending traces via HTTPS is an upcoming feature.
+```
+
+## View traces
 
-<a href="#heading--view"><h2 id="heading--view"> View traces </h2></a>
+The Tempo traces will be accessible from Grafana under the `Explore` section with `tempo-k8s` as the data source. You will be able to select `mysql` as the `Service Name` under the `Search` tab to view traces belonging to Charmed MySQL.
 
-After this is complete, the Tempo traces will be accessible from Grafana under the `Explore` section with `tempo-k8s` as the data source. You will be able to select `mysql` as the `Service Name` under the `Search` tab to view traces belonging to Charmed MySQL.
+<details><summary>Screenshot of a Charmed MySQL trace
+</summary>
 
-Below is a screenshot demonstrating a Charmed MySQL trace:
+![MySQL trace with Grafana Tempo](mysql-vm-trace.png)
+</details>
 
-![Example MySQL trace with Grafana Tempo|690x378](upload://nzIU9vclqmeqwFSF1eV1xKhK6fY.png)
+Feel free to read through the [Tempo HA documentation](https://discourse.charmhub.io/t/charmed-tempo-ha/15531) at your leisure to explore its deployment and its integrations.
 
-Feel free to read through the [Tempo HA documentation](https://discourse.charmhub.io/t/charmed-tempo-ha/15531) at your leisure to explore its deployment and its integrations.
\ No newline at end of file
diff --git a/docs/how-to/monitoring-cos/index.md b/docs/how-to/monitoring-cos/index.md
new file mode 100644
index 0000000000..6e8747775e
--- /dev/null
+++ b/docs/how-to/monitoring-cos/index.md
@@ -0,0 +1,10 @@
+# Monitoring (COS)
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Enable monitoring <enable-monitoring>
+Enable alert rules <enable-alert-rules>
+Enable tracing <enable-tracing>
+```
diff --git a/docs/how-to/monitoring-cos/mysql-k8s-trace.jpeg b/docs/how-to/monitoring-cos/mysql-k8s-trace.jpeg
new file mode 100644
index 0000000000..5a3ca1d9d7
Binary files /dev/null and b/docs/how-to/monitoring-cos/mysql-k8s-trace.jpeg differ
diff --git a/docs/how-to/monitoring-cos/mysql-vm-trace.png b/docs/how-to/monitoring-cos/mysql-vm-trace.png
new file mode 100644
index 0000000000..4a9b36defa
Binary files /dev/null and b/docs/how-to/monitoring-cos/mysql-vm-trace.png differ
diff --git a/docs/how-to/monitoring-cos/pushover-web-client.jpeg b/docs/how-to/monitoring-cos/pushover-web-client.jpeg
new file mode 100644
index 0000000000..1c34bae0cb
Binary files /dev/null and b/docs/how-to/monitoring-cos/pushover-web-client.jpeg differ
diff --git a/docs/how-to/primary-switchover.md b/docs/how-to/primary-switchover.md
new file mode 100644
index 0000000000..0d577c8a26
--- /dev/null
+++ b/docs/how-to/primary-switchover.md
@@ -0,0 +1,20 @@
+# How to do a primary switchover
+
+A user may want to change the primary in a MySQL cluster to improve
+performance, enable maintenance, recover from failure, or balance load across
+nodes.
+
+On a healthy cluster, the primary can be changed by running the `promote-to-primary` action with
+parameter `scope` set to `unit` on the unit that should become the new primary.
+
+```shell
+juju run-action mysql/1 promote-to-primary scope=unit
+```
+
+In this example, the unit `mysql/1` will become the new primary. The previous primary will become a
+secondary.
+
+```{caution}
+The `promote-to-primary` action can be used in cluster scope, when using async replication.
+Check [Switchover / Failover](cross-regional-async-replication/switchover-failover) for more information.
+```
\ No newline at end of file
diff --git a/docs/how-to/h-scale.md b/docs/how-to/scale-replicas.md
similarity index 59%
rename from docs/how-to/h-scale.md
rename to docs/how-to/scale-replicas.md
index e879006586..4a1cea9369 100644
--- a/docs/how-to/h-scale.md
+++ b/docs/how-to/scale-replicas.md
@@ -1,10 +1,4 @@
-[note]
-**Note**: All commands are written for `juju >= v.3.0`
-
-If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
-
-# How to scale units
+# How to scale replicas (units)
 
 Replication in MySQL is the process of creating copies of the stored data. This provides redundancy, which means the application can provide self-healing capabilities in case one replica fails. In this context, each replica is equivalent to one juju unit.
 
@@ -12,47 +6,55 @@ This guide will show you how to establish and change the amount of juju units us
 
 ## Deploy MySQL with replicas
 
-To deploy MySQL with multiple replicas, specify the number of desired units with the `-n` option.
+To deploy MySQL with multiple replicas, specify the number of desired units with the `-n` option:
+
 ```shell
 juju deploy mysql -n <number_of_cluster_members>
 ```
-> It is recommended to use an odd number to prevent a [split-brain](https://en.wikipedia.org/wiki/Split-brain_(computing) scenario.
+
+```{tip}
+It is recommended to use an odd number to prevent a [split-brain](https://en.wikipedia.org/wiki/Split-brain_(computing)) scenario.
+```
 
 ### Primary vs. leader unit 
 
-The MySQL primary server unit may or may not be the same as the [juju leader unit](https://juju.is/docs/juju/leader).
+The MySQL primary server unit is not always the same as the [juju leader unit](https://juju.is/docs/juju/leader).
 
 The juju leader unit is the represented in `juju status` by an asterisk (*) next to its name. 
 
 To retrieve the juju unit that corresponds to the MySQL primary, use the action `get-primary` on any of the units running ` mysql`:
+
 ```shell
 juju run mysql/leader get-primary
 ```
 
 Similarly, the primary replica is displayed as a status message in `juju status`. However, one should note that this hook gets called on regular time intervals and the primary may be outdated if the status hook has not been called recently.
 
-[note]
-**We highly suggest configuring the `update-status` hook to run frequently.** In addition to reporting the primary, secondaries, and other statuses, the [status hook](https://juju.is/docs/sdk/update-status-event) performs self-healing in the case of a network cut. 
+````{note}
+**We highly suggest configuring the `update-status` hook to run frequently.** In addition to reporting the primary, secondaries, and other statuses, the [status hook](https://documentation.ubuntu.com/juju/3.6/reference/hook/#update-status) performs self-healing in the case of a network cut. 
 
 To change the frequency of the `update-status` hook, run
+
 ```shell
 juju model-config update-status-hook-interval=<time(s/m/h)>
 ```
-<!--Note that this hook executes a read query to PostgreSQL. On a production level server, this should be configured to occur at a frequency that doesn't overload the server with read requests. Similarly, the hook should not be configured at too quick of a frequency, as this can delay other hooks from running. -->
-[/note]
+````
 
 ## Scale replicas on an existing application
 
 To scale up the cluster, use `juju add-unit`:
+
 ```shell
 juju add-unit mysql --num-units <amount_of_units_to_add>
 ```
 
 To scale down the cluster, use `juju remove-unit`:
+
 ```shell
 juju remove-unit mysql/<unit_id_to_remove>
 ```
 
-[note type=negative]
-**Warning**: Do not remove the last unit, it will destroy your data!
-[/note]
\ No newline at end of file
+```{attention}
+Do not remove the last unit, it will destroy your data!
+```
+
diff --git a/docs/how-to/h-upgrade.md b/docs/how-to/upgrade/index.md
similarity index 58%
rename from docs/how-to/h-upgrade.md
rename to docs/how-to/upgrade/index.md
index 19e87281fb..fdda0f1b04 100644
--- a/docs/how-to/h-upgrade.md
+++ b/docs/how-to/upgrade/index.md
@@ -1,25 +1,36 @@
 # Upgrade
 
 This section contains documentation about performing upgrades (and rollbacks) on:
-* [MySQL Server (workload)](#mysql-upgrades-workload)
+* [MySQL Server (workload)](mysql-upgrades)
 * [Juju version](#juju-upgrades)
 
-## MySQL upgrades (workload)
+(mysql-upgrades)=
+## MySQL upgrades
 There are two types of in-place workload upgrades:
 * **Major upgrades** -  E.g. MySQL `8.0` -> MySQL `9.0`
   * *Not supported*
 * **Minor upgrades** -  E.g. MySQL `8.0.33` -> `8.0.34` (includes charm revision bump)
-  * See: [How to perform a minor upgrade](/t/11748)
-  * See: [How to perform a minor rollback](/t/11749)
+  * See: [How to perform a minor upgrade](/how-to/upgrade/perform-a-minor-upgrade)
+  * See: [How to perform a minor rollback](/how-to/upgrade/perform-a-minor-rollback)
 
-[note type="caution"]
+```{caution}
 This charm only supports in-place **minor** upgrades. 
 
 To upgrade to a major MySQL version, one must install a new cluster separately and migrate the data from the old to the new installation. This documentation will be updated with the migration instructions when a new MySQL version becomes available.
-[/note]
-
+```
+(juju-upgrades)=
 ## Juju upgrades
 
 New revisions of the charm may require that you do a major or minor Juju upgrade.
 
-See the guide: [How to upgrade Juju](/t/14325)
\ No newline at end of file
+See the guide: [How to upgrade Juju](/how-to/upgrade/upgrade-juju)
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+:hidden:
+
+Upgrade Juju <upgrade-juju>
+Perform a minor rollback <perform-a-minor-rollback>
+Perform a minor upgrade <perform-a-minor-upgrade>
+```
diff --git a/docs/how-to/h-rollback-minor.md b/docs/how-to/upgrade/perform-a-minor-rollback.md
similarity index 85%
rename from docs/how-to/h-rollback-minor.md
rename to docs/how-to/upgrade/perform-a-minor-rollback.md
index 888d41d75f..ddee68647e 100644
--- a/docs/how-to/h-rollback-minor.md
+++ b/docs/how-to/upgrade/perform-a-minor-rollback.md
@@ -1,10 +1,5 @@
-[note]
-**Note**: All commands are written for `juju >= v.3.0`
+# How to perform a minor rollback
 
-If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
-
-# Perform a minor rollback
 **Example**: MySQL 8.0.34 -> MySQL 8.0.33<br/>
 (including charm revision bump: e.g Revision 43 -> Revision 42)
 
@@ -12,11 +7,12 @@ After a `juju refresh`, if there are any version incompatibilities in charm revi
 
 Even if the underlying MySQL cluster continue to work, it’s important to roll back the charm to a previous revision so that an update can be attempted after further inspection of the failure.
 
-[note type="caution"]
+```{caution}
 **Warning:** Do NOT trigger `rollback` during the running `upgrade` action! It may cause an  unpredictable MySQL cluster state!
-[/note]
+```
 
 ## Summary of the rollback steps
+
 1. **Prepare** the Charmed MySQL application for the in-place rollback.
 2. **Roll back**. Once started, all units in a cluster will be executed sequentially. The rollback will be aborted (paused) if the unit rollback has failed.
 3. **Check**. Make sure the charm and cluster are in healthy state again.
@@ -49,4 +45,5 @@ The first unit will be rolled out and should rejoin the cluster after settling d
 
 Future [improvements are planned](https://warthogs.atlassian.net/browse/DPE-2621) to check the state on pods/clusters on a low level. 
 
-For now, check `juju status` to make sure the cluster [state](/t/10624) is OK.
\ No newline at end of file
+For now, check `juju status` to make sure the cluster [state](/reference/charm-statuses) is OK.
+
diff --git a/docs/how-to/h-upgrade-minor.md b/docs/how-to/upgrade/perform-a-minor-upgrade.md
similarity index 84%
rename from docs/how-to/h-upgrade-minor.md
rename to docs/how-to/upgrade/perform-a-minor-upgrade.md
index 7eb435609d..a312be7211 100644
--- a/docs/how-to/h-upgrade-minor.md
+++ b/docs/how-to/upgrade/perform-a-minor-upgrade.md
@@ -1,17 +1,12 @@
-[note]
-**Note**: All commands are written for `juju >= v.3.0`
-
-If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
-
-# Perform a minor upgrade
+# How to perform a minor upgrade
 
 **Example**: MySQL 8.0.33 -> MySQL 8.0.34<br/>
 (including charm revision bump: e.g. Revision 193 -> Revision 196)
 
-This is part of the [Upgrade section](/t/11745). Refer to the landing page for more information and an overview of the content.
+This is part of the [Upgrade section](/how-to/upgrade/index). Refer to the landing page for more information and an overview of the content.
 
 ## Important information
+
 We strongly recommend to **NOT** perform any other extraordinary operations on a Charmed MySQL cluster while upgrading. These may be (but not limited to) the following:
 
 1. Adding or removing units
@@ -21,28 +16,29 @@ We strongly recommend to **NOT** perform any other extraordinary operations on a
 
 Concurrency with other operations is not supported, and it can lead the cluster into inconsistent states.
 
-[note type=caution]
+```{caution}
 Make sure to have a backup of your data when running any type of upgrades!
-See: [How to create a backup](/t/9896)
-[/note]
+See: [How to create a backup](/how-to/back-up-and-restore/create-a-backup)
+```
 
 It is recommended to deploy your application in conjunction with [Charmed MySQL Router](https://charmhub.io/mysql-router). This will ensure minimal service disruption, if any.
 
 ## Summary of the upgrade steps
 
-1. [**Collect**](#step-1-collect) all necessary pre-upgrade information. It will be necessary for the rollback (if requested). Do not skip this step!
-2. [**Prepare**](#step-2-prepare) the Charmed MySQL application for the in-place upgrade
-3. [**Upgrade**](#step-3-upgrade). Once started all units in a cluster will be executed sequentially. The upgrade will be aborted (paused) if the unit upgrade has failed.
-4. Consider a [**rollback**](#step-4-rollback-optional) in case of disaster. Please inform and include us in your case scenario troubleshooting to trace the source of the issue and prevent it in the future. [Contact us](https://chat.charmhub.io/charmhub/channels/data-platform)!
-5. [Post-upgrade **check**](#step-5-check). Make sure all units are in a healthy state.
+1. [**Collect**](step-1-collect) all necessary pre-upgrade information. It will be necessary for the rollback (if requested). Do not skip this step!
+2. [**Prepare**](step-2-prepare) the Charmed MySQL application for the in-place upgrade
+3. [**Upgrade**](step-3-upgrade). Once started all units in a cluster will be executed sequentially. The upgrade will be aborted (paused) if the unit upgrade has failed.
+4. Consider a [**rollback**](step-4-rollback-optional) in case of disaster. Please inform and include us in your case scenario troubleshooting to trace the source of the issue and prevent it in the future. [Contact us](/reference/contacts)!
+5. [Post-upgrade **check**](step-5-check). Make sure all units are in a healthy state.
 
+(step-1-collect)=
 ## Step 1: Collect
 
-[note]
+```{note}
 This step is only valid when deploying from [charmhub](https://charmhub.io/). 
 
 If a [local charm](https://juju.is/docs/sdk/deploy-a-charm) is deployed (revision is small, e.g. 0-10), make sure the proper/current local revision of the `.charm` file is available BEFORE going further. You might need it for a rollback.
-[/note]
+```
 
 The first step is to record the revision of the running application as a safety measure for a rollback action. To accomplish this, run the `juju status` command and look for the deployed Charmed MySQL revision in the command output, e.g:
 
@@ -66,6 +62,7 @@ Machine  State    Address         Inst id         Series  AZ  Message
 
 For this example, the current revision is `182`. Store it safely to use in case of rollback!
 
+(step-2-prepare)=
 ## Step 2: Prepare
 
 Before running the [`juju refresh`](https://juju.is/docs/juju/juju-refresh) command, it’s necessary to run the `pre-upgrade-check` action against the leader unit:
@@ -86,19 +83,25 @@ unit-mysql-10:
 
 The action will configure the charm to minimize the amount of primary switchover, among other preparations for a safe upgrade process. After successful execution, the charm is ready to be upgraded.
 
+(step-3-upgrade)=
 ## Step 3: Upgrade
 
 Use the [`juju refresh`](https://juju.is/docs/juju/juju-refresh) command to trigger the charm upgrade process.
 
 Example with channel selection
+
 ```shell
 juju refresh mysql --channel 8.0/edge
 ```
+
 Example with specific revision selection
+
 ```shell
 juju refresh mysql --revision=183
 ```
+
 Example with a local charm file
+
 ```shell
 juju refresh mysql --path ./mysql_ubuntu-22.04-amd64.charm
 ```
@@ -158,19 +161,21 @@ Each unit should recover shortly after the upgrade, but time can vary depending
 **Incompatible charm revisions or dependencies will halt the process.**
 After a `juju refresh`, if there are any version incompatibilities in charm revisions, its dependencies, or any other unexpected failure in the upgrade process, the upgrade process will be halted and enter a failure state.
 
+(step-4-rollback-optional)=
 ## Step 4: Rollback (optional)
 
 The step must be skipped if the upgrade went well! 
 
 If there was an issue with the upgrade, even if the underlying MySQL cluster continues to work, it’s important to roll back the charm to the previous revision. That way, the update can be attempted again after a further inspection of the failure. 
 
-> See: [How to perform a minor rollback](/t/11749) 
+> See: [How to perform a minor rollback](/how-to/upgrade/perform-a-minor-rollback) 
 
+(step-5-check)=
 ## Step 5: Check
 
 Future improvements are [planned](https://warthogs.atlassian.net/browse/DPE-2621) to check the state of a cluster on a low level. 
 
-For now, use `juju status` to make sure the cluster [state](/t/10624) is OK.
+For now, use `juju status` to make sure the cluster [state](/reference/charm-statuses) is OK.
 
 <!---
 **TODOs:**
@@ -180,4 +185,5 @@ For now, use `juju status` to make sure the cluster [state](/t/10624) is OK.
 * Hints how to fix failed upgrade? mysql-shell hints....
 * Describe pre-upgrade check: free space, etc.
 * Hint to add extra unit to upgrade first keeping cluster "safe".
---->
\ No newline at end of file
+--->
+
diff --git a/docs/how-to/h-upgrade-juju.md b/docs/how-to/upgrade/upgrade-juju.md
similarity index 86%
rename from docs/how-to/h-upgrade-juju.md
rename to docs/how-to/upgrade/upgrade-juju.md
index 6e841bf52b..b1a4eafbc5 100644
--- a/docs/how-to/h-upgrade-juju.md
+++ b/docs/how-to/upgrade/upgrade-juju.md
@@ -2,19 +2,10 @@
 
 This guide contains instructions to perform a patch or major/minor Juju upgrade to a controller and model containing a database charm. 
 
-For more background about Juju upgrades in the context of database charms, check  [Explanation > Juju > Juju upgrades](/t/11959#heading--upgrades).
+For more background about Juju upgrades in the context of database charms, check  [Explanation > Juju > Juju upgrades](/explanation/juju).
 
-## Summary
 
-* [**Patch version upgrade**](#heading--patch-upgrade)
-* [**Major/minor version upgrade**](#heading--major-minor-upgrade)
-  * [Commands summary](#heading--major-minor-summary)
-  * [Example](#heading--major-minor-example)
-* [Resources](#heading--resources)
-
----
-
-<a href="#heading--patch-upgrade"><h2 id="heading--patch-upgrade"> Patch version upgrade </h2></a>
+## Patch version upgrade
 A [PATCH](https://semver.org/#summary) Juju upgrade (e.g. Juju `3.1.5` → `3.1.8`) can be easily applied in-place.
 
 
@@ -27,13 +18,13 @@ juju upgrade-controller
 juju upgrade-model 
 # wait until complete
 ```
-Once the model has finished upgrading, you can proceed with the [charm upgrade](/t/11748).
+Once the model has finished upgrading, you can proceed with the [charm upgrade](/how-to/upgrade/perform-a-minor-upgrade).
 
 
-<a href="#heading--major-minor-upgrade"><h2 id="headingm--major-minor-upgrade"> Major/minor version upgrade </h2></a>
+## Major/minor version upgrade
 The easiest way to perform a [MAJOR/MINOR](https://semver.org/#summary) Juju version upgrade (e.g. Juju `3.1.8` → `3.5.1`),  is to update the controller and model to the new version, then [migrate](https://juju.is/docs/juju/juju-migrate) the model.
 
-<a href="#heading--major-minor-summary"><h3 id="heading--major-minor-summary"> Commands summary </h3></a>
+### Commands summary
 The following is a summary of commands that upgrade Juju to `3.5/stable`:
 
 ```text
@@ -47,9 +38,9 @@ juju upgrade-model -m lxd_3.5.1:mydatabase
 # wait until complete
 ```
 
-Once the model has finished upgrading, you can proceed with the [charm upgrade](/t/11748).
+Once the model has finished upgrading, you can proceed with the [charm upgrade](/how-to/upgrade/perform-a-minor-upgrade).
 
-<a href="#heading--major-minor-example"><h3 id="heading--major-minor-example"> Example </h3></a>
+### Example
 This section goes over the commands listed in the summary above with more details and sample outputs.
 
 <details><summary>In this example scenario, we have <code>mysql</code> deployed in model <code>mydatabase</code> on the Juju controller <code>lxd_3.1.8</code>.</summary> 
@@ -190,15 +181,16 @@ mydatabase  lxd_3.5.1   localhost/localhost  3.5.1    unsupported  22:59:01+02:0
 
 At this stage, the application continues running under the supervision of the new controller version and is ready to be refreshed to the new charm revision.
 
-You can now proceed with the [charm upgrade](/t/11748).
+You can now proceed with the [charm upgrade](/how-to/upgrade/perform-a-minor-upgrade).
 
-<a href="#heading--resources"><h2 id="heading--resources"> Resources </h2></a>
+## Resources
 Further documentation about Juju upgrades: 
-* [MySQL | Explanation > Juju > Juju upgrades](/t/11959#heading--upgrades)
-* [Juju | Upgrade a controller](https://juju.is/docs/juju/manage-controllers#heading--upgrade-a-controller)
+* [MySQL | Explanation > Juju > Juju upgrades](/explanation/juju)
+* [Juju | Upgrade a controller](https://juju.is/docs/juju/manage-controllers#upgrade-a-controller)
 * [Juju | `upgrade-controller`](https://juju.is/docs/juju/juju-upgrade-controller)
 * [Juju | `upgrade-model`](https://juju.is/docs/juju/juju-upgrade-model)
 
 <!-- LINKS -->
 
-[bootstrap]: https://juju.is/docs/juju/juju-bootstrap
\ No newline at end of file
+[bootstrap]: https://juju.is/docs/juju/juju-bootstrap
+
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000000..9454ae6ab6
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,43 @@
+---
+relatedlinks: "[Charmhub](https://charmhub.io/mysql)"
+---
+
+# Charmed MySQL documentation
+
+Charmed MySQL is an open-source software operator that deploys and operates [MySQL Community Edition](https://www.mysql.com/products/community/) relational databases on IAAS/VM via [Juju](https://juju.is/). 
+
+This new operator built with the [charm SDK](https://juju.is/docs/sdk) replaces [**MariaDB**](https://charmhub.io/mariadb), [**OSM MariaDB**](https://charmhub.io/charmed-osm-mariadb-k8s), [**Percona cluster**](https://charmhub.io/percona-cluster) and [**MySQL InnoDB cluster**](https://charmhub.io/mysql-innodb-cluster) operators.
+
+Charmed MySQL includes features such as cluster-to-cluster replication, TLS encryption, password rotation, backups, and easy integration with other applications both inside and outside of Juju. It meets the need of deploying MySQL in a structured and consistent manner while allowing the user flexibility in configuration, simplifying reliable management of MySQL in production environments.
+
+```{note}
+This is a **IAAS/VM** operator. To deploy on Kubernetes, see [Charmed MySQL K8s](https://charmhub.io/mysql-k8s)
+```
+
+## In this documentation
+
+| | |
+|--|--|
+|  [Tutorials](/tutorial/index)</br>  Get started - a hands-on introduction to using Charmed MySQL operator for new users </br> |  [How-to guides](/how-to/scale-replicas) </br> Step-by-step guides covering key operations and common tasks |
+| [Reference](https://charmhub.io/mysql/actions) </br> Technical information - specifications, APIs, architecture | [Explanation](/explanation/index) </br> Concepts - discussion and clarification of key topics  |
+
+## Project and community
+
+Charmed MySQL is an official distribution of MySQL. It’s an open-source project that welcomes community contributions, suggestions, fixes and constructive feedback.
+- [Read our Code of Conduct](https://ubuntu.com/community/code-of-conduct)
+- [Join the Discourse forum](https://discourse.charmhub.io/tag/mysql)
+- [Contribute](https://github.com/canonical/mysql-operator/blob/main/CONTRIBUTING.md) and report [issues](https://github.com/canonical/mysql-operator/issues/new/choose)
+- Explore [Canonical Data Fabric solutions](https://canonical.com/data)
+- [Contacts us](/reference/contacts) for all further questions
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+:hidden:
+
+Home <self>
+tutorial/index
+how-to/index
+reference/index
+explanation/index
+```
diff --git a/docs/overview.md b/docs/overview.md
deleted file mode 100644
index 72afe7c093..0000000000
--- a/docs/overview.md
+++ /dev/null
@@ -1,121 +0,0 @@
-> This is a **IAAS/VM** operator. To deploy in Kubernetes , see [Charmed MySQL K8s](https://charmhub.io/mysql-k8s).
-
-# Charmed MySQL documentation
-
-Charmed MySQL is an open-source software operator that deploys and operates [MySQL Community Edition](https://www.mysql.com/products/community/) relational databases on IAAS/VM via [Juju](https://juju.is/). 
-
-This new operator built with the [charm SDK](https://juju.is/docs/sdk) replaces [**MariaDB**](https://charmhub.io/mariadb), [**OSM MariaDB**](https://charmhub.io/charmed-osm-mariadb-k8s), [**Percona cluster**](https://charmhub.io/percona-cluster) and [**MySQL InnoDB cluster**](https://charmhub.io/mysql-innodb-cluster) operators.
-
-Charmed MySQL includes features such as cluster-to-cluster replication, TLS encryption, password rotation, backups, and easy integration with other applications both inside and outside of Juju. It meets the need of deploying MySQL in a structured and consistent manner while allowing the user flexibility in configuration, simplifying reliable management of MySQL in production environments.
-
-![image|690x424](upload://vpevillwv3S9C44LDFBxkGCxpGq.png)
-
-<!--MySQL is the world’s most popular open source database. A relational database stores data in separate tables rather than putting all the data in one big storeroom. The database structure is organized into physical files optimized for speed. The logical data model, with objects such as data tables, views, rows, and columns, offers a flexible programming environment.-->
-
-## In this documentation
-
-| | |
-|--|--|
-|  [Tutorials](/t/charmed-mysql-tutorial-overview/9922)</br>  Get started - a hands-on introduction to using Charmed MySQL operator for new users </br> |  [How-to guides](/t/charmed-mysql-how-to-manage-units/9904) </br> Step-by-step guides covering key operations and common tasks |
-| [Reference](https://charmhub.io/mysql/actions) </br> Technical information - specifications, APIs, architecture | [Explanation](/t/charmed-mysql-k8s-explanations-interfaces-endpoints/10250) </br> Concepts - discussion and clarification of key topics  |
-
-## Project and community
-
-Charmed MySQL is an official distribution of MySQL. It’s an open-source project that welcomes community contributions, suggestions, fixes and constructive feedback.
-- [Read our Code of Conduct](https://ubuntu.com/community/code-of-conduct)
-- [Join the Discourse forum](/tag/mysql)
-- [Contribute](https://github.com/canonical/mysql-operator/blob/main/CONTRIBUTING.md) and report [issues](https://github.com/canonical/mysql-operator/issues/new/choose)
-- Explore [Canonical Data Fabric solutions](https://canonical.com/data)
-- [Contacts us](/t/11867) for all further questions
-
-# Navigation
-
-[details=Navigation]
-
-| Level | Path | Navlink |
-|---------|---------|-------------|
-| 1 | tutorial | [Tutorial](/t/9922) |
-| 2 | t-set-up | [1. Set up the environment](/t/9924) |
-| 2 | t-deploy | [2. Deploy MySQL](/t/9912) |
-| 2 | t-scale | [3. Scale replicas](/t/9920) |
-| 2 | t-manage-passwords | [4. Manage passwords](/t/9918) |
-| 2 | t-integrate | [5. Integrate applications](/t/9916) |
-| 2 | t-enable-tls | [6. Enable TLS encryption](/t/9914) |
-| 2 | t-clean-up | [7. Clean up the environment](/t/9910) |
-| 1 | how-to | [How-to guides](/t/17233) |
-| 2 | h-setup | [Deploy]() |
-| 3 | h-deploy-sunbeam | [Sunbeam](/t/15986) |
-| 3 | h-deploy-lxd | [LXD](/t/11870) |
-| 3 | h-deploy-maas | [MAAS](/t/13900) |
-| 3 | h-deploy-ec2 | [AWS EC2](/t/15718) |
-| 3 | h-deploy-gce | [GCE](/t/15723) |
-| 3 | h-deploy-azure | [Azure](/t/15859) |
-| 3 | h-deploy-multi-az | [Multi-AZ](/t/15823) |
-| 3 | h-deploy-terraform | [Terraform](/t/14925) |
-| 3 | h-deploy-airgapped | [Air-gapped](/t/15747) |
-| 3 | h-deploy-spaces | [Juju spaces](/t/18084) |
-| 2 | h-integrate| [Integrate with another application](/t/9902) |
-| 2 | h-external-access | [External network access](/t/15801) |
-| 2 | h-scale | [Scale replicas](/t/9904) |
-| 2 | h-enable-tls | [Enable TLS](/t/9898) |
-| 2 | h-backups | [Back up and restore]() |
-| 3 | h-configure-s3-aws | [Configure S3 AWS](/t/9894) |
-| 3 | h-configure-s3-radosgw | [Configure S3 RadosGW](/t/10318) |
-| 3 | h-create-backup | [Create a backup](/t/9896) |
-| 3 | h-restore-backup | [Restore a backup](/t/9908) |
-| 3 | h-migrate-cluster| [Migrate a cluster](/t/9906) |
-| 2 | h-monitoring | [Monitoring (COS)]() |
-| 3 | h-enable-monitoring | [Enable monitoring](/t/9900) |
-| 3 | h-enable-alert-rules | [Enable alert rules](/t/15486) |
-| 3 | h-enable-tracing | [Enable tracing](/t/14350) |
-| 2 | h-upgrade | [Upgrade](/t/11745) |
-| 3 | h-upgrade-juju | [Upgrade Juju](/t/14325) |
-| 3 | h-upgrade-minor | [Perform a minor upgrade](/t/11748) |
-| 3 | h-rollback-minor | [Perform a minor rollback](/t/11749) |
-| 2 | h-async | [Cross-regional async replication]() |
-| 3 | h-async-deployment | [Deploy](/t/14169) |
-| 3 | h-async-clients | [Clients](/t/14170) |
-| 3 | h-async-failover | [Switchover / Failover](/t/14171) |
-| 3 | h-async-recovery | [Recovery](/t/14172) |
-| 3 | h-async-removal | [Removal](/t/14174) |
-| 2 | h-development| [Development]() |
-| 3 | h-development-integrate | [Integrate with your charm](/t/11890) |
-| 3 | h-migrate-mysqldump | [Migrate data via mysqldump](/t/11958) |
-| 3 | h-migrate-mydumper | [Migrate data via mydumper](/t/11988) |
-| 3 | h-migrate-backup-restore | [Migrate data via backup/restore](/t/12008) |
-| 3 | h-troubleshooting | [Troubleshooting](/t/11891) |
-| 4 | r-sos-report | [SOS report](/t/17245) |
-| 2 | h-contribute | [Contribute](/t/14654) |
-| 1 | reference | [Reference](/t/17235) |
-| 2 | r-releases | [Releases](/t/11881) |
-| 2 | r-system-requirements | [System requirements](/t/11742) |
-| 2 | r-testing | [Software testing](/t/11770) |
-| 2 | r-profiles | [Profiles](/t/11973) |
-| 2 | r-plugins-extensions | [Plugins/extensions](/t/15481) |
-| 2 | r-alert-rules | [Alert rules](/t/15839) |
-| 2 | r-statuses | [Charm statuses](/t/10624) |
-| 2 | r-contacts | [Contacts](/t/11867) |
-| 1 | explanation | [Explanation](/t/17237) |
-| 2 | e-architecture | [Architecture](/t/11756) |
-| 2 | e-interfaces-endpoints | [Interfaces and endpoints](/t/10250) |
-| 2 | e-juju | [Juju](/t/11959) |
-| 2 | e-legacy-charm | [Legacy charm](/t/10788) |
-| 2 | e-users | [Users](/t/10789) |
-| 2 | e-logs | [Logs](/t/11993) |
-| 3 | e-audit-logs | [Audit Logs](/t/15424) |
-| 2 | e-security | [Security](/t/16784) |
-| 3 | e-cryptography | [Cryptography](/t/16785) |
-| 1 | search | [Search](https://canonical.com/data/docs/mysql/iaas) |
-
-[/details]
-
-<!--Archived
-| 2 | h-development| [Development](/t/11889) |
-| 3 | h-upgrade-major | [Perform a major upgrade](/t/11746) |
-| 3 | h-rollback-major | [Perform a major rollback](/t/11747) |
-
-| 3 | r-revision-312-313 | [Revision 312/313](/t/15275) |
-| 3 | r-revision-240 | [Revision 240](/t/14071) |
-| 3 | r-revision-196 | [Revision 196](/t/11883) |
-| 3 | r-revision-151 | [Revision 151](/t/11882) |
--->
\ No newline at end of file
diff --git a/docs/reference.md b/docs/reference.md
deleted file mode 100644
index 0182116eea..0000000000
--- a/docs/reference.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Reference
-
-Technical specifications, APIs, release notes, and other reference material for fast lookup.
-
-| Page                      | Description                                       |
-|-------------------------|-------------------------------------------------|
-| [Releases](/t/11881) | Overview of all Charmed MySQL releases |
-| [System requirements](/t/11742) | Software and hardware requirements  |
-| [Software testing](/t/11770) | Software tests performed on this charm |
-| [Profiles](/t/11973) | Configurations related to performance |
-| [Plugins/extensions](/t/15481) |  Supported plugins/extensions |
-| [Alert rules](/t/15839) | Pre-configured Prometheus alert rules |
-| [Charm statuses](/t/10624) | Juju application statuses |
-| [Contacts](/t/11867) | Contact information |
-
-
-In the tabs at the top of this charm's [CharmHub page](https://charmhub.io/mysql/), you will find the following automatically generated references:
-
-| Page  | Description |
-|----------|-------------------|
-| [Integrations](https://charmhub.io/mysql/integrations) | Integration/relation interfaces supported by this charm |
-| [Configuration](https://charmhub.io/mysql/configuration) | Configuration parameters specific to this charm |
-| [Actions](https://charmhub.io/mysql/actions) | Juju actions supported by this charm |
\ No newline at end of file
diff --git a/docs/reference/r-alert-rules.md b/docs/reference/alert-rules.md
similarity index 94%
rename from docs/reference/r-alert-rules.md
rename to docs/reference/alert-rules.md
index 137585eecb..f64154135d 100644
--- a/docs/reference/r-alert-rules.md
+++ b/docs/reference/alert-rules.md
@@ -14,10 +14,11 @@ This page contains a markdown version of the alert rules described in the `mysql
 | MySQLHighThreadsRunning | ![warning] | MySQL instance is actively using > 80% of `max_connections`.<br>Consider reviewing the value of the `max-connections` config parameter or allocate more resources to your database server.  |
 | MySQLHighPreparedStatementsUtilization(>80%) | ![warning] | MySQL instance is using > 80% of `max_prepared_stmt_count`.<br>Too many prepared statements might consume a lot of memory.  |
 | MySQLSlowQueries | ![info] | MySQL instance has a slow query.<br>Consider optimizing the query by reviewing its execution plan, then rewrite the query and add any relevant indexes.  |
-| MySQLInnoDBLogWaits | ![warning] | MySQL instance has long InnoDB log waits.<br>MySQL InnoDB log writes might be stalling. Check I/O activity on your nodes to find the responsible process or query. Consider using iotop and the performance_schema.  |
+| MySQLInnoDBLogWaits | ![warning] | MySQL instance has long InnoDB log waits.<br>MySQL InnoDB log writes might be stalling. Check I/O activity on your nodes to find the responsible process or query. Consider using `iotop` and the `performance_schema`.  |
 | MySQLRestarted | ![info] | MySQL instance restarted.<br>MySQL restarted less than one minute ago. If the restart was unplanned or frequent, check Loki logs (e.g. `error.log`).  |
 
 <!-- Badges -->
 [info]: https://img.shields.io/badge/info-blue
 [warning]: https://img.shields.io/badge/warning-yellow
-[critical]: https://img.shields.io/badge/critical-red
\ No newline at end of file
+[critical]: https://img.shields.io/badge/critical-red
+
diff --git a/docs/reference/r-statuses.md b/docs/reference/charm-statuses.md
similarity index 80%
rename from docs/reference/r-statuses.md
rename to docs/reference/charm-statuses.md
index ed909551b1..fff40863fe 100644
--- a/docs/reference/r-statuses.md
+++ b/docs/reference/charm-statuses.md
@@ -1,10 +1,10 @@
 # Charm statuses
 
-[note type="caution"]
-This is an work-in-progress article. Do **not** use it in production! Contact [Canonical Data Platform team](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in the topic.
-[/note]
+```{caution}
+This is an work-in-progress article. Do **not** use it in production! Contact [Canonical Data Platform team](/reference/contacts) if you are interested in the topic.
+```
 
-The charm follows [standard Juju applications statuses](https://juju.is/docs/olm/status-values#heading--application-status). Here you can find the expected end-users reaction on different statuses:
+The charm follows [standard Juju applications statuses](https://documentation.ubuntu.com/juju/3.6/reference/status/#application-status). Here you can find the expected end-users reaction on different statuses:
 
 | Juju Status | Message | Expectations | Actions |
 |-------|-------|-------|-------|
@@ -13,18 +13,18 @@ The charm follows [standard Juju applications statuses](https://juju.is/docs/olm
 | **maintenance** | any | Charm is performing the internal maintenance (e.g. cluster re-configuration) | No actions required |
 | **blocked** | any | The manual user activity is required! | Follow the message hints (see below) |
 | **blocked** | Failed to set up relation | The relation between two applications failed to be created. Most probably it is a regression of the recent changes in applications | Check Juju [debug-log](https://juju.is/docs/olm/juju-debug-log). Increase debug level and reproduce the issue. Report as an issue with debug logs attached (if reproducible). Consider to try previous revision for both applications |
-| **blocked** | Failed to initialize mysql relation | The same as "Failed to set up relation" | See "Failed to set up relation" |
+| **blocked** | Failed to initialize MySQL relation | The same as "Failed to set up relation" | See "Failed to set up relation" |
 | **blocked** | Failed to remove relation user | TODO: clean manually? How to unblock? | |
 | **blocked** | Failed to install and configure MySQL | TODO |  |
 | **blocked** | Failed to initialize MySQL users | TODO | |
 | **blocked** | Failed to configure instance for InnoDB | TODO | |
-| **blocked** | Failed to create custom mysqld config | TODO | |
+| **blocked** | Failed to create custom `mysqld` config | TODO | |
 | **blocked** | Failed to connect to MySQL exporter | TODO | |
 | **blocked** | Failed to create the InnoDB cluster | TODO | |
 | **blocked** | Failed to initialize juju units operations table | TODO | |
 | **blocked** | failed to recover cluster. | TODO | |
 | **blocked** | Failed to remove relation user | TODO | |
-| **blocked** | Failed to initialize shared_db relation | Try to remove and add relations. Report as an issue (with debug logs) if reproducible | |
+| **blocked** | Failed to initialize `shared_db` relation | Try to remove and add relations. Report as an issue (with debug logs) if reproducible | |
 | **blocked** | Failed to create app user or scoped database | TODO | |
 | **blocked** | Failed to delete users for departing unit | TODO | |
 | **blocked** | Failed to set TLS configuration | Problems with TLS certifications generation| Remove and add relations with TLS operator. Report as an issue (with debug logs) if reproducible |
@@ -35,7 +35,8 @@ The charm follows [standard Juju applications statuses](https://juju.is/docs/olm
 | **blocked** | Failed to re-configure instance for InnoDB | TODO | |
 | **blocked** | Failed to purge data dir | TODO | |
 | **blocked** | Failed to reset root password | TODO | |
-| **blocked** | Failed to create custom mysqld config | TODO | |
+| **blocked** | Failed to create custom `mysqld` config | TODO | |
 | **error** | any | An unhanded internal error happened | Read the message hint. Execute `juju resolve <error_unit/0>` after addressing the root of the error state |
 | **terminated** | any | The unit is gone and will be cleaned by Juju soon | No actions possible |
-| **unknown** | any | Juju doesn't know the charm app/unit status. Possible reason: K8s charm termination in progress. | Manual investigation required if status is permanent |
\ No newline at end of file
+| **unknown** | any | Juju doesn't know the charm app/unit status. Possible reason: K8s charm termination in progress. | Manual investigation required if status is permanent |
+
diff --git a/docs/reference/r-contacts.md b/docs/reference/contacts.md
similarity index 75%
rename from docs/reference/r-contacts.md
rename to docs/reference/contacts.md
index da3e002363..aa41c1039f 100644
--- a/docs/reference/r-contacts.md
+++ b/docs/reference/contacts.md
@@ -2,17 +2,15 @@
 
 Charmed MySQL is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.
 * Raise software issues or feature requests on [**GitHub**](https://github.com/canonical/mysql-operator/issues/new/choose)
-* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
+* Report security issues through [**Launchpad**](https://launchpad.net/mysql)
 * Contact the Canonical Data Platform team through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel.
-[note]
-Our legacy [Mattermost](https://chat.charmhub.io/charmhub/channels/data-platform) channel is read-only until January 31, 2025.
-[/note]
-
 
 ## Useful links
+
 * [Canonical Data Fabric](https://ubuntu.com/data/)
 * [Charmed MySQL](https://charmhub.io/mysql)
 * [Git sources for Charmed MySQL](https://github.com/canonical/mysql-operator)
 * [Canonical Data on Launchpad](https://launchpad.net/~data-platform)
 * [Canonical Data on Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) 
-* [Mailing list on Launchpad](https://lists.launchpad.net/data-platform/)
\ No newline at end of file
+* [Mailing list on Launchpad](https://lists.launchpad.net/data-platform/)
+
diff --git a/docs/reference/index.md b/docs/reference/index.md
new file mode 100644
index 0000000000..b840675ac2
--- /dev/null
+++ b/docs/reference/index.md
@@ -0,0 +1,29 @@
+
+# Reference
+
+Technical specifications, APIs, release notes, and other reference material for fast lookup.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+Releases <releases>
+System requirements <system-requirements>
+Profiles <profiles>
+Plugins/extensions <plugins-extensions>
+Alert rules <alert-rules>
+Charm statuses <charm-statuses>
+Software testing <software-testing>
+Troubleshooting <troubleshooting/index>
+Contacts <contacts>
+```
+
+In the tabs at the top of this charm's [CharmHub page](https://charmhub.io/mysql/), you will find the following automatically generated references:
+
+| Page  | Description |
+|----------|-------------------|
+| [Integrations](https://charmhub.io/mysql/integrations) | Integration/relation interfaces supported by this charm |
+| [Configuration](https://charmhub.io/mysql/configuration) | Configuration parameters specific to this charm |
+| [Actions](https://charmhub.io/mysql/actions) | Juju actions supported by this charm |
+
+
diff --git a/docs/reference/r-plugins-extensions.md b/docs/reference/plugins-extensions.md
similarity index 75%
rename from docs/reference/r-plugins-extensions.md
rename to docs/reference/plugins-extensions.md
index c5d73a6e0e..679e99124e 100644
--- a/docs/reference/r-plugins-extensions.md
+++ b/docs/reference/plugins-extensions.md
@@ -2,8 +2,9 @@
 
 The following list contains all plugins/extensions supported by Charmed MySQL in alphabetical order. The **revision** column indicates which charm revision introduced support for the extension.
 
-If you need support for other extensions, feel free to [reach out to us](/t/11867).
+If you need support for other extensions, feel free to [reach out to us](/reference/contacts).
 
 | Plugin/extension name          | Revision                                                                     |
 |--------------------------------|------------------------------------------------------------------------------|
-| [plugin-audit-enabled](/t/15424)         | [272+](https://github.com/canonical/mysql-operator/releases/tag/rev273) |
\ No newline at end of file
+| [plugin-audit-enabled](/explanation/logs/audit-logs)         | [272+](https://github.com/canonical/mysql-operator/releases/tag/rev273) |
+
diff --git a/docs/reference/profiles.md b/docs/reference/profiles.md
new file mode 100644
index 0000000000..9b1a9a773d
--- /dev/null
+++ b/docs/reference/profiles.md
@@ -0,0 +1,50 @@
+# Profiles
+
+> **Warning:** The feature is currently available in the channel `8.0/candidate` only (revision 186+) and will be released to the channel `8.0/stable` soon.
+
+Charmed MySQL resource utilization depends on the chosen profile:
+
+```shell
+juju deploy mysql --config profile=testing
+```
+
+## Profile values
+
+|Value|Description|Tech details|
+| --- | --- | ----- |
+|`production`<br>(default)|[Maximum performance]| ~75% of [unit] memory granted for MySQL<br/>`max_connections`= [RAM / 12MiB] (max safe value)|
+|`testing`|[Minimal resource usage]| `innodb_buffer_pool_size` = 20MB<br/> `innodb_buffer_pool_chunk_size`=1MB<br/> `group_replication_message_cache_size`=128MB<br/>`max_connections`=100<br/> `performance-schema-instrument`='memory/%=OFF' |
+
+## Config change
+
+> **Note**: Pre-deployed application profile change is [planned](https://warthogs.atlassian.net/browse/DPE-2404) but currently is NOT supported.
+
+To change the profile, use `juju config` ([see all charm configs](https://charmhub.io/mysql/configure#profile)):
+```shell
+juju deploy mysql --config profile=testing && \
+juju config mysql profile=production
+```
+
+## Juju Constraints
+
+[Juju constraints](https://juju.is/docs/juju/constraint) allows RAM/CPU limits for [Juju units](https://juju.is/docs/juju/unit):
+
+```shell
+juju deploy mysql --constraints cores=8 mem=16G
+```
+
+Juju constraints can be used together with charm profile:
+
+```shell
+juju deploy mysql --constraints cores=8 mem=16G --config profile=testing
+```
+
+<!-- Links -->
+
+[Maximum performance]: https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/mysql.py#L766-L775
+
+[unit]: https://juju.is/docs/juju/unit
+
+[RAM / 12MiB]: https://github.com/canonical/mysql-operator/blob/53e54745f47b6d2184c54386ee984792cb939152/lib/charms/mysql/v0/mysql.py#L2092
+
+[Minimal resource usage]: https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/mysql.py#L759-L764
diff --git a/docs/reference/r-profiles.md b/docs/reference/r-profiles.md
deleted file mode 100644
index a293ecd217..0000000000
--- a/docs/reference/r-profiles.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# Profiles
-
-> **Warning:** The feature is currently available in the channel `8.0/candidate` only (revision 186+) and will be released to the channel `8.0/stable` soon.
-
-Charmed MySQL resource utilization depends on the chosen profile:
-
-```shell
-juju deploy mysql --config profile=testing
-```
-
-## Profile values
-
-|Value|Description|Tech details|
-| --- | --- | ----- |
-|`production`<br>(default)|[Maximum performance](https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/mysql.py#L766-L775)| ~75% of [unit memory](https://juju.is/docs/juju/unit) granted for MySQL<br/>max_connections=[RAM/12MiB](https://github.com/canonical/mysql-operator/blob/53e54745f47b6d2184c54386ee984792cb939152/lib/charms/mysql/v0/mysql.py#L2092) (max safe value)|
-|`testing`|[Minimal resource usage](https://github.com/canonical/mysql-operator/blob/main/lib/charms/mysql/v0/mysql.py#L759-L764)| innodb_buffer_pool_size = 20MB<br/>innodb_buffer_pool_chunk_size=1MB<br/>group_replication_message_cache_size=128MB<br/>max_connections=100<br/>performance-schema-instrument='memory/%=OFF' |
-
-## Config change
-
-> :warning: **Note**: Pre-deployed application profile change is [planned](https://warthogs.atlassian.net/browse/DPE-2404) but currently is NOT supported.
-
-To change the profile, use `juju config` ([see all charm configs](https://charmhub.io/mysql/configure#profile)):
-```shell
-juju deploy mysql --config profile=testing && \
-juju config mysql profile=production
-```
-
-## Juju Constraints
-
-[Juju constraints](https://juju.is/docs/juju/constraint) allows RAM/CPU limits for [Juju units](https://juju.is/docs/juju/unit):
-
-```shell
-juju deploy mysql --constraints cores=8 mem=16G
-```
-
-Juju constraints can be used together with charm profile:
-
-```shell
-juju deploy mysql --constraints cores=8 mem=16G --config profile=testing
-```
\ No newline at end of file
diff --git a/docs/reference/r-releases.md b/docs/reference/releases.md
similarity index 80%
rename from docs/reference/r-releases.md
rename to docs/reference/releases.md
index 8d66c78a1f..d1e676789d 100644
--- a/docs/reference/r-releases.md
+++ b/docs/reference/releases.md
@@ -2,7 +2,7 @@
 
 This page provides high-level overviews of the dependencies and features that are supported by each revision in every stable release.
 
-To learn more about the different release tracks and channels, see the [Juju documentation about channels](https://juju.is/docs/juju/channel#heading--risk).
+To learn more about the different release tracks and channels, see the [Juju documentation about channels](https://documentation.ubuntu.com/juju/3.6/reference/charm/#risk).
 
 To see all releases and commits, check the [Charmed MySQL Releases page on GitHub](https://github.com/canonical/mysql-operator/releases).
 
@@ -11,10 +11,10 @@ To see all releases and commits, check the [Charmed MySQL Releases page on GitHu
 For a given release, this table shows:
 * The MySQL version packaged inside
 * The minimum Juju version required to reliably operate **all** features of the release
-   > This charm still supports older versions of Juju down to 2.9. See the [Juju section of the system requirements](/t/11742) for more details.
+   > This charm still supports older versions of Juju down to 2.9. See the [Juju section of the system requirements](/reference/system-requirements) for more details.
 * Support for specific features
 
-| Release | MySQL version | Juju version | [TLS encryption](/t/9898)* | [COS monitoring](/t/9900) | [Minor version upgrades](/t/11748) | [Cross-regional async replication](/t/14169) |
+| Release | MySQL version | Juju version | [TLS encryption](/how-to/enable-tls)* | [COS monitoring](/how-to/monitoring-cos/enable-monitoring) | [Minor version upgrades](/how-to/upgrade/perform-a-minor-upgrade) | [Cross-regional async replication](/how-to/cross-regional-async-replication/deploy) |
 |:---:|:---:|:---:|:---:|:---:|:---:|:---:|
 | [366], [367] | 8.0.41 | `3.4.3+` | ![check] | ![check] | ![check] | ![check] |
 | [312], [313] | 8.0.39 | `3.4.3+` | ![check] | ![check] | ![check] | ![check] |
@@ -28,7 +28,7 @@ For a given release, this table shows:
 For more details about each feature/interface, refer to the documentation linked in the column headers.
 
 ## Architecture and base
-Several [revisions](https://juju.is/docs/sdk/revision) are released simultaneously for different [bases/series](https://juju.is/docs/juju/base) using the same charm code. In other words, one release contains multiple revisions.
+Several [revisions](https://documentation.ubuntu.com/juju/3.6/reference/charm/#charm-revision) are released simultaneously for different [bases/series](https://juju.is/docs/juju/base) using the same charm code. In other words, one release contains multiple revisions.
 
 > If you do not specify a revision on deploy time, Juju will automatically choose the revision that matches your base and architecture.
 
@@ -72,9 +72,9 @@ Several [revisions](https://juju.is/docs/sdk/revision) are released simultaneous
 
 [/details]
 
-[note]
+```{note}
  Our release notes are an ongoing work in progress. If there is any additional information about releases that you would like to see or suggestions for other improvements, don't hesitate to contact us on [Matrix ](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) or leave a comment.
-[/note]
+```
 
 <!-- LINKS -->
 
@@ -87,4 +87,5 @@ Several [revisions](https://juju.is/docs/sdk/revision) are released simultaneous
 [151]: https://github.com/canonical/mysql-operator/releases/tag/rev151
 
 <!--BADGES-->
-[check]: https://img.icons8.com/color/20/checkmark--v1.png
\ No newline at end of file
+[check]: https://img.icons8.com/color/20/checkmark--v1.png
+
diff --git a/docs/reference/r-testing.md b/docs/reference/software-testing.md
similarity index 80%
rename from docs/reference/r-testing.md
rename to docs/reference/software-testing.md
index 32e6f186f2..5a5b78fe9d 100644
--- a/docs/reference/r-testing.md
+++ b/docs/reference/software-testing.md
@@ -1,6 +1,4 @@
-# Charm Testing reference
-
-> **:information_source: Hint**: Use [Juju 3](/t/5064). Otherwise replace `juju run ...` with `juju run-action --wait ...` for Juju 2.9.
+# Charm testing reference
 
 There are [a lot of test types](https://en.wikipedia.org/wiki/Software_testing) available and most of them are well applicable for Charmed MySQL. Here is a list prepared by Canonical:
 
@@ -12,11 +10,12 @@ There are [a lot of test types](https://en.wikipedia.org/wiki/Software_testing)
 
 ## Smoke test
 
-[u]Complexity[/u]: trivial<br/>
-[u]Speed[/u]: fast<br/>
-[u]Goal[/u]: ensure basic functionality works over short amount of time.
+Complexity: trivial
+Speed: fast
+Goal: ensure basic functionality works over short amount of time.
+
+Create a Juju model for testing, deploy a database with a test application and start the "continuous write" test:
 
-[Setup an Juju 3.x environment](/t/9924), deploy DB with test application and start "continuous write" test:
 ```shell
 juju add-model smoke-test
 
@@ -36,12 +35,12 @@ watch -n1 -x juju ssh mysql/leader "mysql -h 127.0.0.1 -uroot -p${password} -e \
 
 # Watch the counter is growing!
 ```
-[u]Expected results[/u]:
+Expected results:
 
 * mysql-test-app continuously inserts records in database `continuous_writes_database` table `data`.
 * the counters (amount of records in table) are growing on all cluster members
 
-[u]Hints[/u]:
+Hints:
 ```shell
 # Stop "continuous write" test
 juju run mysql-test-app/leader stop-continuous-writes
@@ -63,4 +62,5 @@ Please check the "[Contributing](https://github.com/canonical/mysql-operator/blo
 Please check/deploy the charm [mysql-bundle](https://charmhub.io/mysql-bundle) ([Git](https://github.com/canonical/mysql-bundle)). It deploy and test all the necessary parts at once.
 
 ## Performance test
-Refer to the [sysbench documentation](https://discourse.charmhub.io/t/charmed-sysbench-documentation-home/13945).
\ No newline at end of file
+Refer to the [sysbench documentation](https://discourse.charmhub.io/t/charmed-sysbench-documentation-home/13945).
+
diff --git a/docs/reference/r-system-requirements.md b/docs/reference/system-requirements.md
similarity index 73%
rename from docs/reference/r-system-requirements.md
rename to docs/reference/system-requirements.md
index 5d7a4281c8..c4cf43a375 100644
--- a/docs/reference/r-system-requirements.md
+++ b/docs/reference/system-requirements.md
@@ -1,24 +1,15 @@
 # System requirements
 
-The following are the minimum software and hardware requirements to run Charmed PostgreSQL on IAAS/VM.
-
-## Summary
-
-* [Software](#software)
-  * [Juju](#juju)
-  * [MySQL Group replication requirements](#mysql-group-replication-requirements)
-* [Hardware](#hardware)
-* [Networking](#networking)
-
----
+The following are the minimum software and hardware requirements to run Charmed MySQL on IAAS/VM.
 
 ## Software
+
 * Ubuntu 22.04 (Jammy) or later
 
 ### Juju
 
-The charm supports several Juju releases from [2.9 LTS](https://juju.is/docs/juju/roadmap#juju-juju-29) onwards. The table below shows which minor versions of each major Juju release are supported by the stable Charmhub releases of MySQL. 
-> Always check the [charm release notes](/t/11881) to find the minimum Juju version for your deployment.
+The charm supports several Juju releases from [2.9 LTS](https://documentation.ubuntu.com/juju/3.6/reference/juju/juju-roadmap-and-releases/#juju-2-9) onwards. The table below shows which minor versions of each major Juju release are supported by the stable Charmhub releases of MySQL. 
+> Always check the [charm release notes](/reference/releases) to find the minimum Juju version for your deployment.
 
 | Juju major release | Supported minor versions | Compatible charm revisions |Comment |
 |:--------|:-----|:-----|:-----|
@@ -28,7 +19,7 @@ The charm supports several Juju releases from [2.9 LTS](https://juju.is/docs/juj
 | ![3.1] | `3.1.6+` | [196]+ |     |
 | ![2.9 LTS] | `2.9.32+` | [151]+ |     |
 
-See the guide [How to upgrade Juju for a new database revision](/t/14325).
+See the guide [How to upgrade Juju for a new database revision](/how-to/upgrade/upgrade-juju).
 
 ### MySQL Group replication requirements
 * In order to integrate with this charm, every table created by the integrated application **must have a primary key**. This is required by the [group replication plugin](https://dev.mysql.com/doc/refman/8.0/en/group-replication-requirements.html) enabled in this charm.
@@ -45,14 +36,14 @@ The charm is based on the [charmed-mysql snap](https://snapcraft.io/charmed-mysq
 * `amd64`
 * `arm64` (from revision 274+)
 
- [Contact us](/t/11867) if you are interested in new architecture!
+ [Contact us](/reference/contacts) if you are interested in new architecture!
 
 ## Networking
 * Access to the internet for downloading the required snaps and charms.
-  * For air-gapped environments, see our [offline deployment guide](/t/15747)
+  * For air-gapped environments, see our [offline deployment guide](/how-to/deploy/air-gapped)
 * Only IPv4 is supported at the moment
   * See more information about this limitation in [this Jira issue](https://warthogs.atlassian.net/browse/DPE-4695)
-  * [Contact us](/t/11867) if you are interested in IPv6!
+  * [Contact us](/reference/contacts) if you are interested in IPv6!
 
 
 <!-- BADGES -->
@@ -63,6 +54,7 @@ The charm is based on the [charmed-mysql snap](https://snapcraft.io/charmed-mysq
 [3.6 LTS]: https://img.shields.io/badge/3.6_LTS-%23E95420?label=Juju
 
 <!-- LINKS -->
-[240]: /t/14071
-[196]: /t/11883
-[151]: /t/11882
\ No newline at end of file
+[240]: https://github.com/canonical/mysql-operator/releases/tag/rev240
+[196]: https://github.com/canonical/mysql-operator/releases/tag/rev196
+[151]: https://github.com/canonical/mysql-operator/releases/tag/rev151
+
diff --git a/docs/how-to/h-troubleshooting.md b/docs/reference/troubleshooting/index.md
similarity index 81%
rename from docs/how-to/h-troubleshooting.md
rename to docs/reference/troubleshooting/index.md
index ae4fe32a11..2890c9c5c3 100644
--- a/docs/how-to/h-troubleshooting.md
+++ b/docs/reference/troubleshooting/index.md
@@ -1,8 +1,10 @@
 # Troubleshooting
 
-> :warning: **WARNING**: at the moment, there is NO ability to [pause operator](https://warthogs.atlassian.net/browse/DPE-2545)!<br/>Make sure your activity will not interfere with the operator itself!
+```{warning}
+At the moment, there is NO ability to [pause operator](https://warthogs.atlassian.net/browse/DPE-2545)!<br/>Make sure your activity will not interfere with the operator itself!
+```
 
-Ensure you went into the real issue which requires the manual activity. Run `juju status` and check the [list of charm statuses](/t/10624) and recommended activities there.
+Ensure you went into the real issue, which requires manual activity. Run `juju status` and check the [list of charm statuses](/reference/charm-statuses) and recommended activities there.
 
 ## Logs
 
@@ -39,7 +41,7 @@ The MySQL logs are located inside SNAP:
 
 ## SNAP-based Charm
 
-Check the operator [architecture](/t/11756) first to be familiar with SNAP content, operator building blocks and running Juju units.
+Check the operator [architecture](/explanation/architecture) first to be familiar with SNAP content, operator building blocks and running Juju units.
 
 To enter the unit, use:
 ```shell
@@ -102,9 +104,9 @@ ubuntu      6244  0.0  0.0  10460  3312 pts/1    R+   22:08   0:00 ps auxww
 ubuntu@juju-6692b6-0:~$ 
 ```
 
-The list of running SNAP/Systemd services will depends on configured (enabled) [COS integration](/t/9900) and/or [Backup](/t/9896) functionality. The SNAP service `charmed-mysql.mysqld` must always be active and currently running (the Linux processes `snapd`, `mysqld_safe` and `mysqld`).
+The list of running SNAP/Systemd services will depends on configured (enabled) [COS integration](/how-to/monitoring-cos/enable-monitoring) and/or [Backup](/how-to/back-up-and-restore/create-a-backup) functionality. The SNAP service `charmed-mysql.mysqld` must always be active and currently running (the Linux processes `snapd`, `mysqld_safe` and `mysqld`).
 
-To connect inside the MySQL, check the [charm users concept](/t/10789) and request `root` credentials to use `mysql`:
+To connect inside the MySQL, check the [charm users concept](/explanation/users) and request `root` credentials to use `mysql`:
 ```shell
 > juju run mysql/leader get-password username=root
 password: I6ToMBOJKEPKwQG5wwUpuCcg
@@ -126,16 +128,20 @@ username: root
 ```
 Continue troubleshooting your DB/SQL related issues from here.
 
-> :warning: **WARNING**: please do NOT manage users, credentials, databases, schema directly to avoid a split bran situation with the operator and/or related (integrated) applications.
+```{warning}
+Please do NOT manage users, credentials, databases, schema directly to avoid a split bran situation with the operator and/or related (integrated) applications.
+```
 
-It is NOT recommended to restart services directly as it might create a split brain situation with operator internal state. If you see the problem with a unit, consider to [remove failing unit and add-new-unit](/t/9920) to recover the cluster state.
+It is NOT recommended to restart services directly as it might create a split brain situation with operator internal state. If you see the problem with a unit, consider to [remove failing unit and add-new-unit](scale-replicas) to recover the cluster state.
 
-As a last resort, [contact us](/t/11867) If you cannot determinate the source of your issue.
+As a last resort, [contact us](/reference/contacts) If you cannot determinate the source of your issue.
 Also, feel free to improve this document!
 
 ## Installing extra software:
 
-> :warning: **WARNING**: please do NOT install any additionally software as it may affect the stability and produce anomalies which is hard to troubleshoot and fix! Otherwise always remove manually installed components at the end of troubleshooting. Keep the house clean!
+```{warning}
+Please do NOT install any additionally software as it may affect the stability and produce anomalies which is hard to troubleshoot and fix! Otherwise always remove manually installed components at the end of troubleshooting. Keep the house clean!
+```
 
 Sometimes it is necessary to install some extra troubleshooting software. Use the common approach:
 ```shell
@@ -143,4 +149,12 @@ ubuntu@juju-6692b6-0:~$ sudo apt update && sudo apt install gdb
 ...
 Setting up gdb (12.1-0ubuntu1~22.04) ...
 ubuntu@juju-6692b6-0:~$
-```
\ No newline at end of file
+```
+
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+SoS report <sos-report>
+```
diff --git a/docs/reference/troubleshooting/recover_from_quorum_loss.md b/docs/reference/troubleshooting/recover_from_quorum_loss.md
new file mode 100644
index 0000000000..2a9d696bea
--- /dev/null
+++ b/docs/reference/troubleshooting/recover_from_quorum_loss.md
@@ -0,0 +1,98 @@
+# Recovering from quorum loss
+
+Quorum loss in MySQL here the majority of nodes (the quorum) required to make decisions and
+maintain consistency is no longer available. This can happen due to network issues, node failures,
+or other disruptions. When this occurs, the cluster may become unavailable or enter a read-only
+state.
+
+Although the charm cannot automatically recover from quorum loss, you can take the following steps
+to manually recover the cluster.
+
+```{warning}
+Recovery from quorum loss should be performed with caution, as it can impact the availability and
+cause loss of data.
+```
+
+## Ensure the cluster is in no-quorum state
+
+A quorum loss will typically look like this in the juju status output:
+
+```
+Model   Controller  Cloud/Region             Version  SLA          Timestamp
+mymodel localhost   default                  3.6.8    unsupported  17:52:19Z
+
+App    Version                  Status   Scale  Charm      Channel           Rev  Address        Exposed  Message
+mysql  8.0.42-0ubuntu0.22.04.2  waiting      3  mysql-k8s  8.0/edge/dpe7704  279  10.152.183.61  no       waiting for units to settle down
+
+Unit      Workload     Agent  Address     Ports  Message
+mysql/0*  maintenance  idle   10.1.2.48          offline
+mysql/1   maintenance  idle   10.1.0.195         offline
+mysql/2   active       idle   10.1.1.81
+```
+From an active unit, check the cluster status with:
+
+```shell
+juju run mysql/2 get-cluster-status
+```
+Which will output the current status of the cluster.
+
+```
+Running operation 17 with 1 task
+  - task 18 on unit-mysql-2
+
+Waiting for task 18...
+status:
+  clustername: cluster-3eab807dee6797402ecfc52b5a84d15b
+  clusterrole: primary
+  defaultreplicaset:
+    name: default
+    primary: mysql-0.mysql-endpoints.m3.svc.cluster.local.:3306
+    ssl: required
+    status: no_quorum
+    statustext: cluster has no quorum as visible from 'mysql-2.mysql-endpoints.m3.svc.cluster.local.:3306'
+      and cannot process write transactions. 2 members are not active.
+    topology:
+      mysql-0:
+        address: mysql-0.mysql-endpoints.m3.svc.cluster.local.:3306
+        instanceerrors: '[''note: group_replication is stopped.'']'
+        memberrole: primary
+        memberstate: offline
+        mode: n/a
+        role: ha
+        status: unreachable
+        version: 8.0.42
+      mysql-1:
+        address: mysql-1.mysql-endpoints.m3.svc.cluster.local.:3306
+        instanceerrors: '[''note: group_replication is stopped.'']'
+        memberrole: secondary
+        memberstate: offline
+        mode: n/a
+        role: ha
+        status: unreachable
+        version: 8.0.42
+      mysql-2:
+        address: mysql-2.mysql-endpoints.m3.svc.cluster.local.:3306
+        memberrole: secondary
+        mode: r/o
+        replicationlagfromimmediatesource: ""
+        replicationlagfromoriginalsource: ""
+        role: ha
+        status: online
+        version: 8.0.42
+    topologymode: single-primary
+  domainname: cluster-set-3eab807dee6797402ecfc52b5a84d15b
+  groupinformationsourcemember: mysql-2.mysql-endpoints.m3.svc.cluster.local.:3306
+success: "True"
+```
+Note from the output, we can see that the cluster is in a no-quorum state, with `status:
+no_quorum`.
+
+## Recover the cluster from the active unit
+
+Using the available active unit, run the action:
+
+```shell
+juju run mysql/2 promote-to-primary scope=unit force=true
+```
+
+The unit will become the new primary. Other offline units will rejoin automatically.
diff --git a/docs/reference/r-sos-report.md b/docs/reference/troubleshooting/sos-report.md
similarity index 91%
rename from docs/reference/r-sos-report.md
rename to docs/reference/troubleshooting/sos-report.md
index 85e3bb8cea..55b4b87df0 100644
--- a/docs/reference/r-sos-report.md
+++ b/docs/reference/troubleshooting/sos-report.md
@@ -1,20 +1,22 @@
+
 # SoS report
 
 SoS is an extensible, portable, support data collection tool primarily aimed at Linux distributions and other UNIX-like operating systems.
 
-You can use the [built-in version of SoS](#use-built-in-sos-recommended), or [retrieve the latest version from GitHub](#use-the-latest-sos-plugins-from-git). 
+You can use the [built-in version of SoS](use-built-in-sos-recommended), or [retrieve the latest version from GitHub](use-the-latest-sos-plugins-from-git). 
 
-[note type=caution]
+```{caution}
 Always review the collected data before sharing it! 
 
 The generated archive may contain sensitive data. Its content should be reviewed by the originating organization before being passed to any third party.
-[/note]
+```
 
+(use-built-in-sos-recommended)=
 ## Use built-in SoS (recommended)
 
-[note type=caution]
+```{caution}
 The newly created SOS plugin [charmed_mysql](https://github.com/sosreport/sos/blob/main/sos/report/plugins/charmed_mysql.py) might still be missing on your installation, consider to update [sosreport](http://packages.ubuntu.com/sosreport) apt  package to version 4.10+ or use the latest sos plugins from Git (described below).
-[/note]
+```
 
 Charmed MySQL shipped with built-in [SoS](https://github.com/sosreport/sos) reporting tool. You can use it to collect logs on a specific unit or multiple units at once.
 
@@ -101,10 +103,10 @@ Run the following command from outside the Juju units:
 ```shell
 sos collect --cluster-type juju --no-local -c "juju.units=<UNIT_A>,<UNIT_B>,<...>" --batch -o system,systemd,snap,charmed_mysql --low-priority
 ```
+(use-the-latest-sos-plugins-from-git)=
+## Use the latest SoS plugins from Git
 
-## Use the latest sos plugins from Git
-
-The latest version of [sos plugins](https://github.com/sosreport/sos/tree/main/sos/report/plugins) can be retrieved from Git easily:
+The latest version of [SoS plugins](https://github.com/sosreport/sos/tree/main/sos/report/plugins) can be retrieved from Git easily:
 ```shell
 git clone https://github.com/sosreport/sos.git
 cd sos
@@ -115,4 +117,5 @@ The output will be the same to the example above providing archive with all logs
 ```shell
 Your sos report has been generated and saved in:
 	/tmp/sosreport-juju-d4c067-1-2025-04-07-egosqmi.tar.xz
-```
\ No newline at end of file
+```
+
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000000..77ec006202
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,5 @@
+canonical-sphinx[full]
+packaging
+sphinxcontrib-svg2pdfconverter[CairoSVG]
+sphinx-last-updated-by-git
+sphinx-sitemap
diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt
new file mode 100644
index 0000000000..738011e887
--- /dev/null
+++ b/docs/reuse/links.txt
@@ -0,0 +1,43 @@
+.. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en
+.. _Canonical Reference Library: https://library.canonical.com/
+.. _Canonical Sphinx: https://github.com/canonical/canonical-sphinx
+.. _change log: https://github.com/canonical/sphinx-docs-starter-pack/wiki/Change-log
+.. _Diátaxis: https://diataxis.fr/
+.. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/
+.. _Example product documentation repository: https://github.com/canonical/example-product-documentation
+.. _`file-wide metadata`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
+.. _Five golden rules for compliant alt text: https://abilitynet.org.uk/news-blogs/five-golden-rules-compliant-alt-text
+.. _`Furo documentation`: https://pradyunsg.me/furo/quickstart/
+.. _grid tables: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables
+.. _`Hiding Contents sidebar`: https://pradyunsg.me/furo/customisation/toc/
+.. _How to connect your Read the Docs account to your Git provider: https://docs.readthedocs.com/platform/stable/guides/connecting-git-account.html
+.. _How to manually configure a Git repository integration: https://docs.readthedocs.io/en/stable/guides/setup/git-repo-manual.html
+.. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs
+.. _Level AA conformance: https://www.w3.org/WAI/WCAG2AA-Conformance
+.. _list tables: https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table
+.. _manual import: https://readthedocs.com/dashboard/import/manual/
+.. _Markdown: https://commonmark.org/
+.. _MyST: https://myst-parser.readthedocs.io/
+.. _Open Graph: https://ogp.me/
+.. _Pa11y: https://pa11y.org/
+.. _Pa11y readme: https://github.com/pa11y/pa11y#command-line-configuration
+.. _Pygments documentation: https://pygments.org/languages/
+.. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs-at-canonical
+.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
+.. _`Sphinx`: https://www.sphinx-doc.org/
+.. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html
+.. _Sphinx design: https://sphinx-design.readthedocs.io/en/latest/
+.. _Sphinx documentation starter pack:
+.. _Sphinx documentation starter pack repository: https://github.com/canonical/starter-pack
+.. _Sphinx documentation starter pack documentation: https://canonical-starter-pack.readthedocs-hosted.com/
+.. _`Sphinx extensions`: https://www.sphinx-doc.org/en/master/usage/extensions/index.html
+.. _Sphinx tabs: https://sphinx-tabs.readthedocs.io/en/latest/
+.. _tables: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-directives
+.. _toctree: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree
+.. _Vale: https://vale.sh/
+.. _Vale rules: https://github.com/canonical/documentation-style-guide
+.. _Web Content Accessibility Guidelines (WCAG) 2.2: https://www.w3.org/TR/WCAG22/
+
+
+.. SHORTCUTS
+.. |RST| replace:: :abbr:`reST (reStructuredText)`
diff --git a/docs/reuse/substitutions.txt b/docs/reuse/substitutions.txt
new file mode 100644
index 0000000000..307b5f2ec4
--- /dev/null
+++ b/docs/reuse/substitutions.txt
@@ -0,0 +1,7 @@
+.. |version_number| replace:: 0.1.0
+
+.. |rest_text| replace:: *Multi-line* text
+                         that uses basic **markup**.
+
+.. |site_link| replace:: Website link
+.. _site_link: https://example.com
\ No newline at end of file
diff --git a/docs/reuse/substitutions.yaml b/docs/reuse/substitutions.yaml
new file mode 100644
index 0000000000..0c2958d2cd
--- /dev/null
+++ b/docs/reuse/substitutions.yaml
@@ -0,0 +1,4 @@
+# Key/value substitutions to use within the Sphinx doc.
+{version_number: "0.1.0",
+ formatted_text: "*Multi-line* text\n that uses basic **markup**.",
+ site_link: "[Website link](https://example.com)"}
\ No newline at end of file
diff --git a/docs/tutorial.md b/docs/tutorial.md
deleted file mode 100644
index f0ceeaf342..0000000000
--- a/docs/tutorial.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# Charmed MySQL Tutorial
-
-This section of our documentation contains comprehensive, hands-on tutorials to help you learn how to deploy Charmed MySQL on machines and become familiar with its available operations.
-
-## Prerequisites
-
-While this tutorial intends to guide you as you deploy Charmed MySQL for the first time, it will be most beneficial if:
-- You have some experience using a Linux-based CLI
-- You are familiar with MySQL concepts such as replication and users.
-- Your computer fulfils the [minimum system requirements](/t/11742)
-
-## Tutorial contents
-
-| Step | Details |
-| ------- | ---------- |
-| 1. **[Set up your environment]** | Set up a cloud environment for your deployment using [Multipass](https://multipass.run/) with [LXD](https://ubuntu.com/lxd) and [Juju](https://juju.is/).
-| 2. **[Deploy MySQL]** | Learn to deploy MySQL using a single command and access the database directly.
-| 3. **[Scale your replicas]** | Learn how to enable high availability with [MySQL InnoDB Cluster](https://dev.mysql.com/doc/refman/8.0/en/mysql-innodb-cluster-introduction.html)
-| 4. **[Manage passwords]** | Learn how to request and change passwords.
-| 5. **[Integrate MySQL with other applications]** | Learn how to integrate with other applications using the Data Integrator Charm, access the integrated database, and manage users.
-| 6. **[Enable TLS encryption]** | Learn how to enable TLS encryption on your MySQL cluster
-| 7. **[Clean up your environment]** | Free up your machine's resources.
-
-<!-- LINKS -->
-[Set up your environment]: /t/9924?channel=8.0/edge
-[Deploy MySQL]: /t/9912?channel=8.0/edge
-[Scale your replicas]: /t/9920?channel=8.0/edge
-[Manage passwords]: /t/9918?channel=8.0/edge
-[Integrate MySQL with other applications]: /t/9916?channel=8.0/edge
-[Enable TLS encryption]: /t/9914?channel=8.0/edge
-[Upgrade charm]: /t/11745?channel=8.0/edge
-[Clean up your environment]: /t/9910?channel=8.0/edge
\ No newline at end of file
diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md
new file mode 100644
index 0000000000..5f20e6477c
--- /dev/null
+++ b/docs/tutorial/index.md
@@ -0,0 +1,628 @@
+# Tutorial
+
+This hands-on tutorial aims to help you learn how to deploy Charmed MySQL on machines and become familiar with its available operations.
+
+## Prerequisites
+
+While this tutorial intends to guide you as you deploy Charmed MySQL for the first time, it will be most beneficial if:
+- You have some experience using a Linux-based CLI
+- You are familiar with MySQL concepts such as replication and users.
+- Your computer fulfils the [minimum system requirements](/reference/system-requirements)
+
+---
+
+## Set up the environment
+
+First, we will set up a cloud environment using [Multipass](https://multipass.run/) with [LXD](https://documentation.ubuntu.com/lxd/latest/) and [Juju](https://documentation.ubuntu.com/juju/3.6/). This is the quickest and easiest way to get your machine ready for using Charmed MySQL. 
+
+To learn about other types of deployment environments and methods (e.g. bootstrapping other clouds, using Terraform), see [](/how-to/deploy/index).
+
+(create-multipass-vm)=
+### Create a Multipass VM
+
+Multipass is a quick and easy way to launch virtual machines running Ubuntu. It uses the [cloud-init](https://cloud-init.io/) standard to install and configure all the necessary parts automatically.
+
+Install Multipass from the [snap store](https://snapcraft.io/multipass):
+
+```{terminal}
+:input: sudo snap install multipass
+:user: user
+:host: my-pc
+```
+
+Spin up a new VM using [`multipass launch`](https://multipass.run/docs/launch-command) with the [charm-dev](https://github.com/canonical/multipass-blueprints/blob/main/v1/charm-dev.yaml) cloud-init configuration:
+
+```{terminal}
+:input: multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev
+:user: user
+:host: my-pc
+```
+
+This may take several minutes if it's the first time you launch this VM.
+
+As soon as the new VM has started, access it:
+
+```{terminal}
+:input: multipass shell my-vm
+:user: user
+:host: my-pc
+
+Welcome to Ubuntu 24.04.2 LTS (GNU/Linux 6.8.0-63-generic x86_64)
+
+ * Documentation:  https://help.ubuntu.com
+ * Management:     https://landscape.canonical.com
+ * Support:        https://ubuntu.com/pro
+...
+```
+
+```{tip}
+All necessary components have been pre-installed inside VM already, like LXD and Juju. The files `/var/log/cloud-init.log` and `/var/log/cloud-init-output.log` contain all low-level installation details. 
+```
+
+### Set up Juju
+
+Since `my-vm` already has Juju and LXD installed, we can go ahead and [bootstrap](https://documentation.ubuntu.com/juju/3.6/reference/juju-cli/list-of-juju-cli-commands/bootstrap/#details) a cloud. In this tutorial, we will use a local LXD [controller](https://documentation.ubuntu.com/juju/3.6/reference/controller/). 
+
+We will call our new controller “overlord”, but you can give it any name you’d like:
+
+```{terminal}
+:input: juju bootstrap localhost overlord
+:user: ubuntu
+:host: my-vm
+``` 
+
+The controller can work with different [Juju models](https://juju.is/docs/juju/model). Set up a specific model for Charmed MySQL named `tutorial`:
+
+```{terminal}
+:input: juju add-model tutorial
+:user: ubuntu
+:host: my-vm
+``` 
+
+You can now view the model you created by running the command [`juju status`](https://juju.is/docs/juju/juju-status). 
+
+```{terminal}
+:input: juju status
+:user: ubuntu
+:host: my-vm
+
+Model     Controller  Cloud/Region         Version   SLA          Timestamp
+tutorial  overlord    localhost/localhost   3.6.8    unsupported  15:31:14+02:00
+
+Model "admin/tutorial" is empty.
+```
+
+## Deploy Charmed MySQL
+
+To deploy Charmed MySQL, run the following command:
+
+```{terminal}
+:input: juju deploy mysql
+:user: ubuntu
+:host: my-vm
+```
+
+Juju will now fetch Charmed MySQL from [Charmhub](https://charmhub.io/mysql) and deploy it to the LXD cloud. This process can take several minutes depending on how provisioned (RAM, CPU, etc) your machine is. 
+
+You can track the progress by running:
+
+```{terminal}
+:input: juju status --watch 1s
+:user: ubuntu
+:host: my-vm
+```
+
+```{tip}
+You can open a separate terminal window, enter the same Multipass VM, and keep `juju status --watch 1s` permanently running in it.
+```
+
+When the application is ready, `juju status` will show something similar to the sample output below:
+
+```text
+Model      Controller  Cloud/Region         Version  SLA          Timestamp
+tutorial   overlord    localhost/localhost  3.5.2    unsupported  00:52:59+02:00
+
+App    Version          Status  Scale  Charm  Channel     Rev  Exposed  Message
+mysql  8.0.32-0ubun...  active      1  mysql  8.0/stable  151  no       Primary
+
+Unit      Workload  Agent  Machine  Public address  Ports           Message
+mysql/0*  active    idle   1        10.234.188.135  3306,33060/tcp  Primary
+
+Machine  State    Address         Inst id        Base          AZ  Message
+1        started  10.234.188.135  juju-ff9064-0  ubuntu@22.04      Running
+```
+
+You can also watch juju logs with the [`juju debug-log`](https://juju.is/docs/juju/juju-debug-log) command.
+
+## Access MySQL
+
+In this section, you will learn how to get the credentials of your deployment, connect to the MySQL instance, and interact with the database directly.
+
+This is where we are introduced to internal database [users](/explanation/users). 
+
+```{caution}
+This part of the tutorial accesses MySQL via the charm's `root` user. 
+
+**Do not directly interface with the `root` user in a production environment.**
+
+In a later section, we will cover how to safely access MySQL more safely.
+```
+
+The easiest way to access MySQL is via the [MySQL Command-Line Client](https://dev.mysql.com/doc/refman/8.0/en/mysql.html) (`mysql`). For this, we must first retrieve the credentials.
+
+### Retrieve credentials
+
+Connecting to the database requires that you know the values for `host` (IP address), `username` and `password`. 
+
+To retrieve `username` and `password`, run the [Juju action](https://juju.is/docs/juju/action) `get-password` on the leader unit as follows:
+
+```{terminal}
+:input: juju run mysql/leader get-password
+:user: ubuntu
+:host: my-vm
+
+...
+password: yWJjs2HccOmqFMshyRcwWnjF
+username: root
+```
+
+To retrieve the host’s IP address, run `juju status`. This should be listed under the "Public address" of the unit hosting the MySQL application:
+
+```{terminal}
+:input: juju status
+:user: ubuntu
+:host: my-vm
+
+...
+Unit      Workload  Agent  Machine  Public address  Ports           Message
+mysql/0*  active    idle   1        10.234.188.135  3306,33060/tcp  Primary
+...
+```
+
+### Interact with MySQL
+
+To access the unit hosting Charmed MySQL in production, one would normally use the following command:
+
+```shell
+mysql -h <ip_address> -u<username> -p<password>
+```
+
+However, this is not possible with the `root` user. For security reasons, the `root` user is restricted to only allow connections from `localhost`. 
+
+The way to access MySQL server with the `root` user is to first ssh into the primary Juju unit:
+
+```{terminal}
+:input: juju ssh mysql/leader
+:user: ubuntu
+:host: my-vm
+```
+
+```{note}
+In this case, we know the MySQL primary unit is also the [Juju leader unit](https://juju.is/docs/juju/leader), since it is the only existing unit. 
+
+In a cluster with more units, **the primary is not necessarily equivalent to the leader**. To identify the primary unit in a cluster, run `juju run mysql/<any_unit> get-cluster-status`. 
+```
+
+Once inside the Juju virtual machine, the `root` user can access MySQL with the following command:
+
+```
+mysql -h 127.0.0.1 -uroot -p<password>
+```
+
+As an example, using the password we obtained earlier:
+
+```{terminal}
+:input: mysql -h 127.0.0.1 -uroot -pyWJjs2HccOmqFMshyRcwWnjF
+:user: ubuntu
+:host: juju-ff9064-0
+
+Welcome to the MySQL monitor.  Commands end with ; or \g.
+Your MySQL connection id is 56
+Server version: 8.0.32-0ubuntu0.22.04.2 (Ubuntu)
+
+Copyright (c) 2000, 2023, Oracle and/or its affiliates.
+
+Oracle is a registered trademark of Oracle Corporation and/or its
+affiliates. Other names may be trademarks of their respective
+owners.
+
+Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
+
+mysql>
+```
+
+You can now interact with MySQL directly using any [MySQL Queries](https://dev.mysql.com/doc/refman/8.0/en/entering-queries.html). 
+
+For example:
+
+```sql
+SELECT VERSION(), CURRENT_DATE;
+```
+
+```text
++-------------------------+--------------+
+| VERSION()               | CURRENT_DATE |
++-------------------------+--------------+
+| 8.0.32-0ubuntu0.22.04.2 | 2023-01-29   |
++-------------------------+--------------+
+1 row in set (0.00 sec)
+```
+
+Feel free to test out any other MySQL queries. 
+
+When you’re ready to leave the mysql shell you can just type `exit`. Once you've typed `exit` you will be back in the host of Charmed MySQL (`mysql/0`). 
+
+Exit this host by once again typing `exit`. Now you will be in your original shell where you first started the tutorial; here you can interact with Juju and LXD.
+
+(scale-replicas)=
+## Scale your replicas
+
+The Charmed MySQL operator uses [MySQL InnoDB Cluster](https://dev.mysql.com/doc/refman/8.0/en/mysql-innodb-cluster-introduction.html) for scaling. It is built on MySQL [group replication](https://dev.mysql.com/doc/refman/8.0/en/group-replication.html), providing features such as automatic membership management, fault tolerance, and automatic failover. 
+
+An InnoDB Cluster usually runs in a single-primary mode, with one primary instance (read-write) and multiple secondary instances (read-only). 
+
+<!-- TODO: clarify "future" Future versions on Charmed MySQL will take advantage of a multi-primary mode, where multiple instances are primaries. Users can even change the topology of the cluster while InnoDB Cluster is online, to ensure the highest possible availability. -->
+
+```{caution}
+This tutorial hosts replicas all on the same machine. **This should not be done in a production environment.** 
+
+To enable high availability in a production environment, replicas should be hosted on different servers to [maintain isolation](https://canonical.com/blog/database-high-availability).
+```
+
+### Add units
+
+Currently, your deployment has only one [juju unit](https://juju.is/docs/juju/unit), known as the leader unit.  For each MySQL replica, a new juju unit (non-leader) is created. All units are members of the same database cluster.
+
+To add two replicas to your deployed MySQL application, run:
+
+```{terminal}
+:input: juju add-unit mysql -n 2
+:user: ubuntu
+:host: my-vm
+```
+
+You can now watch the scaling process in live using: `juju status --watch 1s`. It usually takes several minutes for new cluster members to be added. 
+
+You’ll know that all three nodes are in sync when `juju status` reports `Workload=active` and `Agent=idle`:
+
+```text
+Model     Controller  Cloud/Region         Version  SLA          Timestamp
+tutorial  overlord    localhost/localhost  3.5.2    unsupported  23:33:55+01:00
+
+App    Version          Status  Scale  Charm  Channel     Rev  Exposed  Message
+mysql  8.0.32-0ubun...  active      3  mysql  8.0/stable  147  no
+
+Unit      Workload  Agent  Machine  Public address  Ports  Message
+mysql/0*  active    idle   0        10.234.188.135         Primary
+mysql/1   active    idle   1        10.234.188.214
+mysql/2   active    idle   2        10.234.188.6
+
+Machine  State    Address         Inst id        Series  AZ  Message
+0        started  10.234.188.135  juju-ff9064-0  jammy       Running
+1        started  10.234.188.214  juju-ff9064-1  jammy       Running
+2        started  10.234.188.6    juju-ff9064-2  jammy       Running
+```
+
+```{note}
+The maximum possible number of Charmed MySQL units in a single Juju application is 9. This is a limitation of MySQL group replication. 
+
+Read more about all limitations in the [official MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/group-replication-limitations.html).
+```
+
+### Remove units
+
+Removing a unit from the application scales down the replicas. 
+
+Before we scale down, list all the units with `juju status`. You will see three units: `mysql/0`, `mysql/1`, and `mysql/2`. Each of these units hosts a MySQL replica. 
+
+To remove the replica hosted on the unit `mysql/2` enter:
+
+```{terminal}
+:input: juju remove-unit mysql/2
+:user: ubuntu
+:host: my-vm
+```
+
+You’ll know that the replica was successfully removed when you no longer see them in the `juju status` output:
+
+```text
+Model     Controller  Cloud/Region         Version  SLA          Timestamp
+tutorial  overlord    localhost/localhost  3.5.2    unsupported  23:46:43+01:00
+
+App    Version          Status  Scale  Charm  Channel     Rev  Exposed  Message
+mysql  8.0.32-0ubun...  active      2  mysql  8.0/stable  147  no
+
+Unit      Workload  Agent  Machine  Public address  Ports  Message
+mysql/0*  active    idle   0        10.234.188.135         Primary
+mysql/1   active    idle   1        10.234.188.214
+
+Machine  State    Address         Inst id        Series  AZ  Message
+0        started  10.234.188.135  juju-ff9064-0  jammy       Running
+1        started  10.234.188.214  juju-ff9064-1  jammy       Running
+```
+
+## Integrate with other applications
+
+[Integrations](https://documentation.ubuntu.com/juju/3.6/reference/relation/), also known as "relations", are the easiest way to create a user for MySQL. 
+
+Integrations automatically create a username, password, and database for the desired user/application. The best practice is to connect to MySQL via a specific user rather than the admin user, like we did earlier with the `root` user.
+
+In this tutorial, we will relate to the [data integrator charm](https://charmhub.io/data-integrator). This is a bare-bones charm that allows for central management of database users. It automatically provides credentials and endpoints that are needed to connect with a charmed database application.
+
+To deploy `data-integrator` and associate it to a new database called `test-database`:
+
+```{terminal}
+:input: juju deploy data-integrator --config database-name=test-database
+:user: ubuntu
+:host: my-vm
+
+Located charm "data-integrator" in charm-hub, revision 13
+Deploying "data-integrator" from charm-hub charm "data-integrator", revision 3 in channel edge on jammy
+```
+
+Running `juju status` will show you `data-integrator` in a `blocked` state. This state is expected due to not-yet established relation (integration) between applications:
+
+```text
+...
+App              Version          Status   Scale  Charm            Channel     Rev  Exposed  Message
+data-integrator                   blocked      1  data-integrator  stable     13    no       Please relate the data-integrator with the desired product
+mysql            8.0.32-0ubun...  active       2  mysql            8.0/stable  147  no
+
+Unit                Workload  Agent  Machine  Public address  Ports  Message
+data-integrator/1*  blocked   idle   4        10.234.188.85          Please relate the data-integrator with the desired product
+mysql/0*            active    idle   0        10.234.188.135         Primary
+mysql/1             active    idle   1        10.234.188.214
+...
+```
+
+Now that the `data-integrator` charm has been set up, we can relate it to MySQL. This will automatically create a username, password, and database for `data-integrator`:
+
+Relate the two applications with:
+
+```{terminal}
+:input: juju integrate data-integrator mysql
+:user: ubuntu
+:host: my-vm
+```
+
+Wait for `juju status` to show all applications/units as `active`:
+
+```text
+Model     Controller  Cloud/Region         Version  SLA          Timestamp
+tutorial  overlord    localhost/localhost  3.5.2    unsupported  00:10:27+01:00
+
+App              Version          Status  Scale  Charm            Channel     Rev  Exposed  Message
+data-integrator                   active      1  data-integrator  edge       13    no
+mysql            8.0.32-0ubun...  active      2  mysql            8.0/stable  147  no
+
+Unit                Workload  Agent  Machine  Public address  Ports  Message
+data-integrator/1*  active    idle   4        10.234.188.85
+mysql/0*            active    idle   0        10.234.188.135         Primary
+mysql/1             active    idle   1        10.234.188.214
+
+Machine  State    Address         Inst id        Series  AZ  Message
+0        started  10.234.188.135  juju-ff9064-0  jammy       Running
+1        started  10.234.188.214  juju-ff9064-1  jammy       Running
+4        started  10.234.188.85   juju-ff9064-4  jammy       Running
+```
+
+To retrieve the username, password and database name, run the `get-credentials` Juju action:
+
+```{terminal}
+:input: juju run data-integrator/leader get-credentials
+:user: ubuntu
+:host: my-vm
+
+mysql:
+  database: test-database
+  endpoints: 10.234.188.135:3306
+  password: NZWCNOyfSElJW0u6bnQDOWAA
+  read-only-endpoints: 10.234.188.214:10.234.188.85:3306
+  username: relation-5
+  version: 8.0.32-0ubuntu0.22.04.2
+ok: "True"
+```
+
+(access-the-integrated-database)=
+### Access the integrated database
+
+Use `endpoints`, `username`, `password` from above to connect newly created database `test-database` on MySQL server:
+
+```{terminal}
+:scroll:
+:input: mysql -h 10.234.188.135 -P 3306 -urelation-4 -pNZWCNOyfSElJW0u6bnQDOWAA -e "show databases"
+:user: ubuntu
+:host: my-vm
+
++--------------------+
+| Database           |
++--------------------+
+| test-database      |
++--------------------+
+```
+
+The newly created database `test-database` is also available on all other MySQL cluster members:
+
+```{terminal}
+:scroll:
+:input: mysql -h 10.234.188.214 -P 3306 -urelation-5 -pNZWCNOyfSElJW0u6bnQDOWAA -e "show databases"
+:user: ubuntu
+:host: my-vm
+
++--------------------+
+| Database           |
++--------------------+
+| test-database      |
++--------------------+
+```
+
+You've successfully set up a new user and database by integrating your Charmed MySQL app with the Data Integrator app. 
+
+### Remove the user
+
+Removing the integration automatically removes the user that was created when the integration was created.
+
+To remove the integration, run the following command:
+
+```{terminal}
+:input: juju remove-relation mysql data-integrator
+:user: ubuntu
+:host: my-vm
+```
+
+Try to connect to the same MySQL you just used in the [previous section](access-the-integrated-database), you'll get an error message:
+
+```{terminal}
+:scroll:
+:input: mysql -h 10.234.188.135 -P 3306 -urelation-5 -pNZWCNOyfSElJW0u6bnQDOWAA -e "show databases"
+:user: ubuntu
+:host: my-vm
+
+
+ERROR 1045 (28000): Access denied for user 'relation-5'@'_gateway.lxd' (using password: YES)
+```
+
+This is expected, since the user no longer exists after removing the integration. However, note that **data remains on the server** at this stage.
+
+To create a user again, re-integrate the applications:
+
+```{terminal}
+:scroll:
+:input: juju integrate data-integrator mysql
+:user: ubuntu
+:host: my-vm
+```
+Re-integrating generates a new user and password. You can obtain these credentials as before, with the `get-credentials` action, and connect to the database with this new credentials. 
+
+From here you will see all of your data is still present in the database.
+
+## Enable encryption with TLS
+
+[Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security) is a protocol used to encrypt data exchanged between two applications. Essentially, it secures data transmitted over a network.
+
+Typically, enabling TLS internally within a highly available database or between a highly available database and client/server applications requires a high level of expertise. This has all been encoded into Charmed MySQL so that configuring TLS requires minimal effort on your end.
+
+TLS is enabled by integrating Charmed MySQL with the [Self-signed certificates charm](https://charmhub.io/self-signed-certificates). This charm centralises TLS certificate management consistently and handles operations like providing, requesting, and renewing TLS certificates.
+
+```{caution}
+**[Self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) are not recommended for a production environment.**
+
+Check [this guide](https://discourse.charmhub.io/t/11664) for an overview of the TLS certificates charms available. 
+```
+
+Before enabling TLS on Charmed MySQL, we must deploy the `self-signed-certificates` charm:
+
+```{terminal}
+:scroll:
+:input: juju deploy self-signed-certificates --config ca-common-name="Tutorial CA"
+:user: ubuntu
+:host: my-vm
+```
+
+Wait until `self-signed-certificates` is up and active, using `juju status --watch 1s` to monitor its progress:
+
+```text
+Model     Controller  Cloud/Region         Version  SLA          Timestamp
+tutorial  overlord    localhost/localhost  3.5.2    unsupported  00:40:42+01:00
+
+App                        Version          Status  Scale  Charm                      Channel     Rev  Exposed  Message
+mysql                      8.0.32-0ubun...  active      2  mysql                      8.0/stable  147  no
+self-signed-certificates                    active      1  self-signed-certificates   edge        77   no
+
+Unit                          Workload  Agent  Machine  Public address  Ports  Message
+mysql/0*                      active    idle   0        10.234.188.135         Primary
+mysql/1                       active    idle   1        10.234.188.214
+self-signed-certificates/1*   active    idle   6        10.234.188.19
+
+Machine  State    Address         Inst id        Series  AZ  Message
+0        started  10.234.188.135  juju-ff9064-0  jammy       Running
+1        started  10.234.188.214  juju-ff9064-1  jammy       Running
+6        started  10.234.188.19   juju-ff9064-6  focal       Running
+```
+
+To enable TLS on Charmed MySQL, integrate the two applications:
+
+```{terminal}
+:scroll:
+:input: juju integrate mysql self-signed-certificates
+:user: ubuntu
+:host: my-vm
+```
+
+MySQL is now using TLS certificate generated by the `self-signed-certificates` charm.
+
+Use `openssl` to connect to MySQL and check the TLS certificate in use:
+
+```{terminal}
+:scroll:
+:input: openssl s_client -starttls mysql -connect 10.234.188.135:3306 | grep Issuer
+:user: ubuntu
+:host: my-vm
+
+...
+depth=1 C = US, CN = self-signed-certificates-operator
+...
+```
+
+To remove the external TLS and return to the locally generate one, remove the integration from the applications:
+
+```{terminal}
+:input: juju remove-relation mysql self-signed-certificates
+:user: ubuntu
+:host: my-vm
+```
+
+If you once again check the TLS certificates in use via the OpenSSL client, you will see something similar to the output below:
+
+```{terminal}
+:input: openssl s_client -starttls mysql -connect 10.234.188.135:3306 | grep Issuer
+:user: ubuntu
+:host: my-vm
+
+...
+depth=1 CN = MySQL_Server_8.0.32_Auto_Generated_CA_Certificate
+...
+```
+
+The Charmed MySQL application reverted to the placeholder certificate that was created locally during the MySQL Server installation.
+
+## Clean up your environment
+
+In this tutorial we've successfully deployed and accessed MySQL on LXD, added and removed cluster members, added and removed database users, and enabled a layer of security with TLS.
+
+You may now keep your MySQL deployment running and write to the database, or remove it entirely using the steps in this page.
+
+If you'd like to keep your environment for later, simply stop your VM with:
+
+```{terminal}
+:input: multipass stop my-vm
+:user: user
+:host: my-pc
+```
+
+If you're done with testing and would like to free up resources on your machine, you can remove the VM entirely.
+
+```{caution}
+When you remove VM as shown below, you will lose all the data in MySQL and any other applications inside Multipass VM! 
+
+For more information, see the docs for [`multipass delete`](https://multipass.run/docs/delete-command).
+```
+
+**Delete your VM and its data** by running:
+
+```{terminal}
+:input: multipass delete --purge my-vm
+:user: user
+:host: my-pc
+```
+
+### Next steps
+
+- Run [Charmed MySQL on Kubernetes](https://github.com/canonical/mysql-k8s-operator).
+- Check out our Charmed offerings of [PostgreSQL](https://charmhub.io/postgresql?channel=14) and [Kafka](https://charmhub.io/kafka?channel=edge).
+- Read about [High Availability Best Practices](https://canonical.com/blog/database-high-availability)
+- [Report](https://github.com/canonical/mysql-operator/issues) any problems you encountered.
+- [Give us your feedback](/reference/contacts).
+- [Contribute to the code base](https://github.com/canonical/mysql-operator)
+
+
diff --git a/docs/tutorial/t-clean-up.md b/docs/tutorial/t-clean-up.md
deleted file mode 100644
index 837e217335..0000000000
--- a/docs/tutorial/t-clean-up.md
+++ /dev/null
@@ -1,36 +0,0 @@
-> [Charmed MySQL Tutorial](/t/9922) > 7. Clean up your environment
-
-# Clean up your environment
-
-In this tutorial we've successfully deployed and accessed MySQL on LXD, added and removed cluster members, added and removed database users, and enabled a layer of security with TLS.
-
-You may now keep your MySQL deployment running and write to the database, or remove it entirely using the steps in this page.
-
-## Stop your virtual machine
-If you'd like to keep your environment for later, simply stop your VM with
-```shell
-multipass stop my-vm
-```
-
-## Delete your virtual machine
-If you're done with testing and would like to free up resources on your machine, you can remove the VM entirely.
-
-[note type="caution"]
-**Warning**: When you remove VM as shown below, you will lose all the data in MySQL and any other applications inside Multipass VM! 
-
-For more information, see the docs for [`multipass delete`](https://multipass.run/docs/delete-command).
-[/note]
-
-**Delete your VM and its data** by running
-```shell
-multipass delete --purge my-vm
-```
-
-## Next Steps
-
-- Run [Charmed MySQL on Kubernetes](https://github.com/canonical/mysql-k8s-operator).
-- Check out our Charmed offerings of [PostgreSQL](https://charmhub.io/postgresql?channel=14) and [Kafka](https://charmhub.io/kafka?channel=edge).
-- Read about [High Availability Best Practices](https://canonical.com/blog/database-high-availability)
-- [Report](https://github.com/canonical/mysql-operator/issues) any problems you encountered.
-- [Give us your feedback](https://chat.charmhub.io/charmhub/channels/data-platform).
-- [Contribute to the code base](https://github.com/canonical/mysql-operator)
\ No newline at end of file
diff --git a/docs/tutorial/t-deploy.md b/docs/tutorial/t-deploy.md
deleted file mode 100644
index 53b4d00533..0000000000
--- a/docs/tutorial/t-deploy.md
+++ /dev/null
@@ -1,143 +0,0 @@
-> [Charmed MySQL Tutorial](/t/9922) > 2. Deploy MySQL
-
-# Deploy Charmed MySQL
-
-In this section, you will deploy Charmed MySQL, access a unit, and interact with the MySQL databases that exist inside the application.
-
-## Summary
-* [Deploy MySQL](#deploy-mysql)
-* [Access MySQL](#access-mysql)
-  * [Retrieve credentials](#retrieve-credentials)
-  * [ Access MySQL via the `mysql` client](#access-mysql-via-the-mysql-client)
----
-
-## Deploy MySQL
-
-To deploy Charmed MySQL, run the following command:
-```shell
-juju deploy mysql
-```
-
-Juju will now fetch Charmed MySQL from [Charmhub](https://charmhub.io/mysql) and deploy it to the LXD cloud. This process can take several minutes depending on how provisioned (RAM, CPU, etc) your machine is. You can track the progress by running:
-```shell
-juju status --watch 1s
-```
-
->This command is useful for checking the real-time information about the state of a charm and the machines hosting it. Check the [`juju status` documentation](https://juju.is/docs/juju/juju-status) for more information about its usage.
-
-When the application is ready, `juju status` will show the `mysql` app as `active` and the `mysql/0*` unit as `idle`, like the example below:
-```shell
-Model      Controller  Cloud/Region         Version  SLA          Timestamp
-tutorial   overlord    localhost/localhost  3.5.2    unsupported  00:52:59+02:00
-
-App    Version          Status  Scale  Charm  Channel     Rev  Exposed  Message
-mysql  8.0.32-0ubun...  active      1  mysql  8.0/stable  151  no       Primary
-
-Unit      Workload  Agent  Machine  Public address  Ports           Message
-mysql/0*  active    idle   1        10.234.188.135  3306,33060/tcp  Primary
-
-Machine  State    Address         Inst id        Base          AZ  Message
-1        started  10.234.188.135  juju-ff9064-0  ubuntu@22.04      Running
-```
-
-> To exit the screen with `juju status --watch 1s`, enter `Ctrl+C`.
-
-You can also watch juju logs with the [`juju debug-log`](https://juju.is/docs/juju/juju-debug-log) command. More info on logging in the [juju logs documentation](https://juju.is/docs/olm/juju-logs).
-
-## Access MySQL
-[note type="caution"]
-**Warning:** This part of the tutorial accesses MySQL via the `root` user. 
-
-**Do not directly interface with the `root` user in a production environment.**
-
-In a [later section about integrations](/t/9916), we will cover how to safely access MySQL via a separate user.
-[/note]
-
- The easiest way to access MySQL is via the [MySQL Command-Line Client](https://dev.mysql.com/doc/refman/8.0/en/mysql.html) (`mysql`). For this, we must first retrieve the credentials.
-
-### Retrieve credentials
-Connecting to the database requires that you know the values for `host` (IP address), `username` and `password`. 
-
-To retrieve `username` and `password`, run the [Juju action](https://juju.is/docs/juju/action) `get-password` on the leader unit as follows:
-```shell
-juju run mysql/leader get-password
-```
-Example output:
-```shell
-...
-password: yWJjs2HccOmqFMshyRcwWnjF
-username: root
-```
-
-To request a password for a different user, use the option `username`:
-```shell
-juju run mysql/leader get-password username=<username>
-```
-
-To retrieve the host’s IP address, run `juju status`. This should be listed under the "Public address" of the unit hosting the MySQL application:
-```shell
-...
-Unit      Workload  Agent  Machine  Public address  Ports  Message
-mysql/0*  active    idle   1        10.234.188.135  3306,33060/tcp  Primary
-...
-```
-
-### Access MySQL via the `mysql` client
-
-To access the unit hosting Charmed MySQL, one could normally use the following command:
-
-```
-mysql -h <ip_address> -u<username> -p<password>
-```
-
-However, this is not possible with the `root` user. For security reasons, the `root` user is restricted to only allow connections from localhost. 
-
-The way to access MySQL server with the `root` user is to first ssh into the primary Juju unit:
-```shell
-juju ssh mysql/leader
-```
-> In this case, we know the primary unit is the [juju leader unit](https://juju.is/docs/juju/leader), since it is the only existing unit. 
->
-> In a cluster with more units, **the primary is not necessarily equivalent to the leader**. To identify the primary unit in a cluster, run `juju run mysql/<any_unit> get-cluster-status`. This will display the entire cluster topology.
-
-Once inside the Juju virtual machine, the `root` user can access MySQL by calling
-```
-mysql -h 127.0.0.1 -uroot -pyWJjs2HccOmqFMshyRcwWnjF
-```
-> Remember, your password will be different to the example above. Make sure to insert it without a space as `-p<password>`
-
-You will then see the `mysql>` command prompt, similar to the output below:
-```none
-Welcome to the MySQL monitor.  Commands end with ; or \g.
-Your MySQL connection id is 56
-Server version: 8.0.32-0ubuntu0.22.04.2 (Ubuntu)
-
-Copyright (c) 2000, 2023, Oracle and/or its affiliates.
-
-Oracle is a registered trademark of Oracle Corporation and/or its
-affiliates. Other names may be trademarks of their respective
-owners.
-
-Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
-
-mysql>
-```
-
-> If at any point you'd like to leave the mysql client, enter `Ctrl+D` or type `exit`.
-
-You can now interact with MySQL directly using any [MySQL Queries](https://dev.mysql.com/doc/refman/8.0/en/entering-queries.html). For example entering `SELECT VERSION(), CURRENT_DATE;` should output something like:
-```shell
-mysql> SELECT VERSION(), CURRENT_DATE;
-+-------------------------+--------------+
-| VERSION()               | CURRENT_DATE |
-+-------------------------+--------------+
-| 8.0.32-0ubuntu0.22.04.2 | 2023-01-29   |
-+-------------------------+--------------+
-1 row in set (0.00 sec)
-```
-
-Feel free to test out any other MySQL queries. 
-
->When you’re ready to leave the mysql shell you can just type `exit`. Once you've typed `exit` you will be back in the host of Charmed MySQL (`mysql/0`). Exit this host by once again typing `exit`. Now you will be in your original shell where you first started the tutorial; here you can interact with Juju and LXD.
-
-> Next step: [3. Scale your replicas](/t/9920)
\ No newline at end of file
diff --git a/docs/tutorial/t-enable-tls.md b/docs/tutorial/t-enable-tls.md
deleted file mode 100644
index 6fd3170fa3..0000000000
--- a/docs/tutorial/t-enable-tls.md
+++ /dev/null
@@ -1,93 +0,0 @@
-> [Charmed MySQL Tutorial](/t/9922) > 6. Enable TLS encryption
-
-# Enable encryption with TLS
-
-[Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security) is a protocol used to encrypt data exchanged between two applications. Essentially, it secures data transmitted over a network.
-
-Typically, enabling TLS internally within a highly available database or between a highly available database and client/server applications requires a high level of expertise. This has all been encoded into Charmed MySQL so that configuring TLS requires minimal effort on your end.
-
-TLS is enabled by integrating Charmed MySQL with the [Self Signed Certificates Charm](https://charmhub.io/self-signed-certificates). This charm centralises TLS certificate management consistently and handles operations like providing, requesting, and renewing TLS certificates.
-
-In this section, you will learn how to enable security in your MySQL deployment using TLS encryption.
-
-[note type="caution"]
-**[Self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) are not recommended for a production environment.**
-
-Check [this guide](/t/11664) for an overview of the TLS certificates charms available. 
-[/note]
-
-## Summary
-- [Enable TLS](#enable-tls)
-  - [Deploy TLS charm](#deploy-tls-charm)
-  - [Integrate with MySQL](#integrate-with-mysql)
-    - [Check the TLS certificate in use](#check-the-tls-certificate-in-use)
-- [Disable TLS ](#disable-tls)
-
----
-
-## Enable TLS
-To enable TLS on Charmed MySQL, we must deploy the `self-signed-certificates` charm and integrate it with MySQL.
-
-### Deploy TLS charm
-Deploy the `self-signed-certificates` TLS charm with the following command:
-```shell
-juju deploy self-signed-certificates --config ca-common-name="Tutorial CA"
-```
-
-Wait until `self-signed-certificates` is up and active, using `juju status --watch 1s` to monitor its progress:
-```shell
-Model     Controller  Cloud/Region         Version  SLA          Timestamp
-tutorial  overlord    localhost/localhost  3.5.2    unsupported  00:40:42+01:00
-
-App                        Version          Status  Scale  Charm                      Channel     Rev  Exposed  Message
-mysql                      8.0.32-0ubun...  active      2  mysql                      8.0/stable  147  no
-self-signed-certificates                    active      1  self-signed-certificates   edge        77   no
-
-Unit                          Workload  Agent  Machine  Public address  Ports  Message
-mysql/0*                      active    idle   0        10.234.188.135         Primary
-mysql/1                       active    idle   1        10.234.188.214
-self-signed-certificates/1*   active    idle   6        10.234.188.19
-
-Machine  State    Address         Inst id        Series  AZ  Message
-0        started  10.234.188.135  juju-ff9064-0  jammy       Running
-1        started  10.234.188.214  juju-ff9064-1  jammy       Running
-6        started  10.234.188.19   juju-ff9064-6  focal       Running
-```
-
-### Integrate with MySQL
-
-To enable TLS on Charmed MySQL, integrate the two applications:
-```shell
-juju integrate mysql self-signed-certificates
-```
-MySQL is now using TLS certificate generated by the `self-signed-certificates` charm.
-
-#### Check the TLS certificate in use
-Use `openssl` to connect to MySQL and check the TLS certificate in use:
-```shell
-> openssl s_client -starttls mysql -connect 10.234.188.135:3306 | grep Issuer
-...
-depth=1 C = US, CN = self-signed-certificates-operator
-...
-```
-
-## Disable TLS
-To remove the external TLS and return to the locally generate one, remove the integration from the applications:
-```shell
-juju remove-relation mysql self-signed-certificates
-```
-
-If you once again check the TLS certificates in use via the OpenSSL client, you will see something similar to the output below:
-
-```shell
-> openssl s_client -starttls mysql -connect 10.234.188.135:3306 | grep Issuer
-```
-
-```shell
-...
-depth=1 CN = MySQL_Server_8.0.32_Auto_Generated_CA_Certificate
-...
-```
-The Charmed MySQL application reverted to the placeholder certificate that was created locally during the MySQL server installation.
-
->Next step: [7. Clean up your environment](/t/9695)
\ No newline at end of file
diff --git a/docs/tutorial/t-integrate.md b/docs/tutorial/t-integrate.md
deleted file mode 100644
index 84bb3e7337..0000000000
--- a/docs/tutorial/t-integrate.md
+++ /dev/null
@@ -1,158 +0,0 @@
-> [Charmed MySQL Tutorial](/t/9922) > 5. Integrate with other applications
-
-# Integrate with other applications
-
-[Integrations](https://juju.is/docs/sdk/integration), known as "relations" in Juju 2.9, are the easiest way to create a user for a Charmed MySQL application. 
-
-Integrations automatically create a username, password, and database for the desired user/application. As mentioned in the [earlier section about accessing MySQL](/t/9912#access-mysql-via-the-mysql-client), it is better practice to connect to MySQL via a specific user instead of the `root` user.
-
-In this section, you will learn how to integrate your Charmed MySQL with another application (charmed or not) via the Data Integrator charm. 
-
-## Summary
-* [Deploy `data-integrator`](#deploy-data-integrator)
-* [Integrate with MySQL](#integrate-with-mysql)
-* [Access the integrated database](#access-the-integrated-database)
-* [Remove the user](#remove-the-user)
-
----
-
-## Deploy `data-integrator`
-
-In this tutorial, we will relate to the [Data Integrator charm](https://charmhub.io/data-integrator). This is a bare-bones charm that allows for central management of database users. It automatically provides credentials and endpoints that are needed to connect with a charmed database application.
-
- In order to deploy the Data Integrator charm we can use the command `juju deploy` we have learned above:
-
-To deploy `data-integrator`, run
-
-```shell
-juju deploy data-integrator --config database-name=test-database
-```
-
-Example output:
-```shell
-Located charm "data-integrator" in charm-hub, revision 13
-Deploying "data-integrator" from charm-hub charm "data-integrator", revision 3 in channel edge on jammy
-```
-
-Running `juju status` will show you `data-integrator` in a `blocked` state. This state is expected due to not-yet established relation (integration) between applications.
-```shell
-Model     Controller  Cloud/Region         Version  SLA          Timestamp
-tutorial  overlord    localhost/localhost  3.5.2    unsupported  00:07:00+01:00
-
-App              Version          Status   Scale  Charm            Channel     Rev  Exposed  Message
-data-integrator                   blocked      1  data-integrator  stable     13    no       Please relate the data-integrator with the desired product
-mysql            8.0.32-0ubun...  active       2  mysql            8.0/stable  147  no
-
-Unit                Workload  Agent  Machine  Public address  Ports  Message
-data-integrator/1*  blocked   idle   4        10.234.188.85          Please relate the data-integrator with the desired product
-mysql/0*            active    idle   0        10.234.188.135         Primary
-mysql/1             active    idle   1        10.234.188.214
-
-Machine  State    Address         Inst id        Series  AZ  Message
-0        started  10.234.188.135  juju-ff9064-0  jammy       Running
-1        started  10.234.188.214  juju-ff9064-1  jammy       Running
-4        started  10.234.188.85   juju-ff9064-4  jammy       Running
-```
-
-## Integrate with MySQL
-
-Now that the `data-integrator` charm has been set up, we can relate it to MySQL. This will automatically create a username, password, and database for `data-integrator`.
-
-Relate the two applications with:
-```shell
-juju integrate data-integrator mysql
-```
-
-Wait for `juju status --watch 1s` to show all applications/units as `active`:
-```shell
-Model     Controller  Cloud/Region         Version  SLA          Timestamp
-tutorial  overlord    localhost/localhost  3.5.2    unsupported  00:10:27+01:00
-
-App              Version          Status  Scale  Charm            Channel     Rev  Exposed  Message
-data-integrator                   active      1  data-integrator  edge       13    no
-mysql            8.0.32-0ubun...  active      2  mysql            8.0/stable  147  no
-
-Unit                Workload  Agent  Machine  Public address  Ports  Message
-data-integrator/1*  active    idle   4        10.234.188.85
-mysql/0*            active    idle   0        10.234.188.135         Primary
-mysql/1             active    idle   1        10.234.188.214
-
-Machine  State    Address         Inst id        Series  AZ  Message
-0        started  10.234.188.135  juju-ff9064-0  jammy       Running
-1        started  10.234.188.214  juju-ff9064-1  jammy       Running
-4        started  10.234.188.85   juju-ff9064-4  jammy       Running
-```
-
-To retrieve the username, password and database name, run the command
-```shell
-juju run data-integrator/leader get-credentials
-```
-Example output:
-```yaml
-mysql:
-  database: test-database
-  endpoints: 10.234.188.135:3306
-  password: NZWCNOyfSElJW0u6bnQDOWAA
-  read-only-endpoints: 10.234.188.214:10.234.188.85:3306
-  username: relation-5
-  version: 8.0.32-0ubuntu0.22.04.2
-ok: "True"
-```
-> Note that your hostnames, usernames, and passwords will be different.
-
-## Access the integrated database
-
-Use `endpoints`, `username`, `password` from above to connect newly created database `test-database` on MySQL server:
-```shell
-> mysql -h 10.234.188.135 -P 3306 -urelation-4 -pNZWCNOyfSElJW0u6bnQDOWAA -e "show databases"
-+--------------------+
-| Database           |
-+--------------------+
-| test-database      |
-+--------------------+
-```
-
-The newly created database `test-database` is also available on all other MySQL cluster members:
-```shell
-> mysql -h 10.234.188.214 -P 3306 -urelation-5 -pNZWCNOyfSElJW0u6bnQDOWAA -e "show databases"
-+--------------------+
-| Database           |
-+--------------------+
-| test-database      |
-+--------------------+
-```
-
-When you integrate two applications, Charmed MySQL automatically sets up a new user and database for you. Note the database name we specified when we first deployed the `data-integrator` charm: `--config database-name=test-database`.
-
-## Remove the user
-To remove the user, remove the integration. Removing the integration automatically removes the user that was created when the integration was created. 
-
-To remove the integration, run the following command:
-```shell
-juju remove-relation mysql data-integrator
-```
-
-Try to connect to the same MySQL you just used in the previous section ([Access the related database](#access-the-related-database)):
-```shell
-mysql -h 10.234.188.135 -P 3306 -urelation-5 -pNZWCNOyfSElJW0u6bnQDOWAA -e "show databases"
-```
-
-This will output an error message, since the user no longer exists.
-```shell
-ERROR 1045 (28000): Access denied for user 'relation-5'@'_gateway.lxd' (using password: YES)
-```
-This is expected, as `juju remove-relation mysql-k8s data-integrator` also removes the user.
-
-> **Note**: Data remains on the server at this stage.
-
-To create a user again, re-integrate the applications:
-```shell
-juju integrate data-integrator mysql
-```
-Re-integrating generates a new user and password. Obtain these credentials as before, with the `get-credentials` action:
-```shell
-juju run data-integrator/leader get-credentials
-```
-You can connect to the database with this new credentials. From here you will see all of your data is still present in the database.
-
-> Next step: [6. Enable TLS encryption](/t/9914)
\ No newline at end of file
diff --git a/docs/tutorial/t-manage-passwords.md b/docs/tutorial/t-manage-passwords.md
deleted file mode 100644
index 02a1c14e29..0000000000
--- a/docs/tutorial/t-manage-passwords.md
+++ /dev/null
@@ -1,64 +0,0 @@
-> [Charmed MySQL Tutorial](/t/9922) > 4. Manage passwords
-
-# Manage passwords
-
-When we accessed MySQL earlier in this tutorial, we needed to use a password manually. Passwords help to secure our database and are essential for security. Over time, it is a good practice to change the password frequently. 
-
-This section will go through setting and changing the password for the admin user.
-
-## Summary
-* [Retrieve the root password](#retrieve-the-root-password)
-* [Rotate the root password](#rotate-the-root-password)
-* [Set the root password](#set-the-root-password)
-
----
-
-## Retrieve the root password
-The root user's password can be retrieved by running the `get-password` action on the Charmed MySQL application:
-```shell
-juju run mysql/leader get-password
-```
-Example output:
-```shell
-...
-password: yWJjs2HccOmqFMshyRcwWnjF
-username: root
-```
-
-## Rotate the root password
-You can change the root user's password to a new random password by running:
-```shell
-juju run mysql/leader set-password
-```
-Example output:
-```shell
-Running operation 12 with 1 task
-  - task 13 on unit-mysql-1
-
-Waiting for task 13...
-status: completed
-```
-The `status: completed` above means the password has been successfully updated. To be sure, call `get-password` once again to check that the root password is different from the previous password.
-
-## Set the root password
-You can change the root password to a specific password by running:
-```shell
-juju run mysql/leader set-password password=my-password && \
-juju run mysql/leader get-password
-```
-Example output:
-```shell
-Running operation 18 with 1 task
-  - task 19 on unit-mysql-1
-
-Waiting for task 19...
-Running operation 20 with 1 task
-  - task 21 on unit-mysql-1
-
-Waiting for task 21...
-password: my-password
-username: root
-```
-The root `password` should match whatever you passed in when you entered the command.
-
-> Next step: [5. Integrate with another application](/t/9916)
\ No newline at end of file
diff --git a/docs/tutorial/t-scale.md b/docs/tutorial/t-scale.md
deleted file mode 100644
index e8b6f9baa7..0000000000
--- a/docs/tutorial/t-scale.md
+++ /dev/null
@@ -1,85 +0,0 @@
-> [Charmed MySQL Tutorial](/t/9922) > 3. Scale your replicas
-
-# Scale your replicas
-
-In this section, you will learn to scale your Charmed MySQL by adding or removing juju units.
-
-The Charmed MySQL operator uses [MySQL InnoDB Cluster](https://dev.mysql.com/doc/refman/8.0/en/mysql-innodb-cluster-introduction.html) for scaling. It is built on MySQL [Group Replication](https://dev.mysql.com/doc/refman/8.0/en/group-replication.html), providing features such as automatic membership management, fault tolerance, and automatic failover. 
-
-An InnoDB Cluster usually runs in a single-primary mode, with one primary instance (read-write) and multiple secondary instances (read-only). 
-
-<!-- TODO: clarify "future" Future versions on Charmed MySQL will take advantage of a multi-primary mode, where multiple instances are primaries. Users can even change the topology of the cluster while InnoDB Cluster is online, to ensure the highest possible availability. -->
-
-[note type="caution"]
-**Disclaimer:** This tutorial hosts replicas all on the same machine. **This should not be done in a production environment.** 
-
-To enable high availability in a production environment, replicas should be hosted on different servers to [maintain isolation](https://canonical.com/blog/database-high-availability).
-[/note]
-
-## Summary
-* [Add replicas](#add-replicas)
-* [Remove replicas](#remove-replicas)
-
----
-
-Currently, your deployment has only one [juju unit](https://juju.is/docs/juju/unit), known in juju as the leader unit.  For each MySQL replica, a new juju unit (non-leader) is created. All units are members of the same database cluster.
-
-## Add replicas
-You can add two replicas to your deployed MySQL application with:
-```shell
-juju add-unit mysql -n 2
-```
-
-You can now watch the scaling process in live using: `juju status --watch 1s`. It usually takes several minutes for new cluster members to be added. 
-
-You’ll know that all three nodes are in sync when `juju status` reports `Workload=active` and `Agent=idle`:
-```shell
-Model     Controller  Cloud/Region         Version  SLA          Timestamp
-tutorial  overlord    localhost/localhost  3.5.2    unsupported  23:33:55+01:00
-
-App    Version          Status  Scale  Charm  Channel     Rev  Exposed  Message
-mysql  8.0.32-0ubun...  active      3  mysql  8.0/stable  147  no
-
-Unit      Workload  Agent  Machine  Public address  Ports  Message
-mysql/0*  active    idle   0        10.234.188.135         Primary
-mysql/1   active    idle   1        10.234.188.214
-mysql/2   active    idle   2        10.234.188.6
-
-Machine  State    Address         Inst id        Series  AZ  Message
-0        started  10.234.188.135  juju-ff9064-0  jammy       Running
-1        started  10.234.188.214  juju-ff9064-1  jammy       Running
-2        started  10.234.188.6    juju-ff9064-2  jammy       Running
-```
-[note]
-The maximum number of Charmed MySQL units in a single Juju application is 9. This is a limitation of MySQL Group replication. Read more about all limitations in the [official MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/group-replication-limitations.html).
-[/note]
-
-## Remove replicas
-Removing a unit from the application scales down the replicas. 
-
-Before we scale down, list all the units with `juju status`. You will see three units: `mysql/0`, `mysql/1`, and `mysql/2`. Each of these units hosts a MySQL replica. 
-
-To remove the replica hosted on the unit `mysql/2` enter:
-```shell
-juju remove-unit mysql/2
-```
-
-You’ll know that the replica was successfully removed when `juju status --watch 1s` reports:
-```shell
-Model     Controller  Cloud/Region         Version  SLA          Timestamp
-tutorial  overlord    localhost/localhost  3.5.2    unsupported  23:46:43+01:00
-
-App    Version          Status  Scale  Charm  Channel     Rev  Exposed  Message
-mysql  8.0.32-0ubun...  active      2  mysql  8.0/stable  147  no
-
-Unit      Workload  Agent  Machine  Public address  Ports  Message
-mysql/0*  active    idle   0        10.234.188.135         Primary
-mysql/1   active    idle   1        10.234.188.214
-
-Machine  State    Address         Inst id        Series  AZ  Message
-0        started  10.234.188.135  juju-ff9064-0  jammy       Running
-1        started  10.234.188.214  juju-ff9064-1  jammy       Running
-```
-<!--TODO: What about generic scaling down (without specifying which unit)?-->
-
-> Next step: [4. Manage passwords](/t/9918)
\ No newline at end of file
diff --git a/docs/tutorial/t-set-up.md b/docs/tutorial/t-set-up.md
deleted file mode 100644
index ef34c46ee5..0000000000
--- a/docs/tutorial/t-set-up.md
+++ /dev/null
@@ -1,64 +0,0 @@
-> [Charmed MySQL Tutorial](/t/9922) > 1. Set up your environment
-
-# Set up your environment
-
-In this first step, you will set up a development environment with the required components for deploying Charmed MySQL.
-
-[note]
-Before you start, make sure your machine meets the [minimum system requirements](/t/11742).
-[/note]
-
-## Summary
-* [Set up Multipass](#set-up-multipass)
-* [Set up Juju](#set-up-juju)
-
----
-
-## Set up Multipass
-[Multipass](https://multipass.run/) is a quick and easy way to launch virtual machines running Ubuntu. It uses the [cloud-init](https://cloud-init.io/) standard to install and configure all the necessary parts automatically.
-
-Install Multipass from the [snap store](https://snapcraft.io/multipass):
-```shell
-sudo snap install multipass
-```
-
-Launch a new VM using the [`charm-dev`](https://github.com/canonical/multipass-blueprints/blob/main/v1/charm-dev.yaml) cloud-init config:
-```shell
-multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev
-```
-
-> All `multipass launch` params are described in the [Multipass documentation](https://multipass.run/docs/launch-command).
-
-The list of [Multipass commands](https://multipass.run/docs/multipass-cli-commands) is short and self-explanatory. For example, to show all running VMs, just run `multipass list`.
-
-As soon as new VM has started, access it with the following command:
-```shell
-multipass shell my-vm
-```
-> If at any point you'd like to leave Multipass VM, enter `Ctrl+D` or type `exit`.
-
-All necessary components have been pre-installed inside VM already, like LXD and Juju. The files `/var/log/cloud-init.log` and `/var/log/cloud-init-output.log` contain all low-level installation details. 
-
-## Set up Juju
-
-Let's bootstrap Juju to use the local LXD controller. We will call it "overlord", but you can give it any name you'd like.
-```shell
-juju bootstrap localhost overlord
-```
-
-
-The controller can work with different [Juju models](https://juju.is/docs/juju/model). Set up a specific model for Charmed MySQL named ‘tutorial’:
-```shell
-juju add-model tutorial
-```
-
-You can now view the model you created above by entering the command `juju status` into the command line. You should see something similar to the following output:
-
-```none
-Model    Controller  Cloud/Region         Version  SLA          Timestamp
-tutorial overlord    localhost/localhost  3.5.2    unsupported  23:20:53+01:00
-
-Model "admin/tutorial" is empty.
-```
-
-> Next step: [2.  Deploy MySQL](/t/9912?channel=8.0/edge)
\ No newline at end of file