diff --git a/.gitignore b/.gitignore
index f6ba599..3e2c1db 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,6 @@ src/config.php
 /e2e/playwright-report/
 /e2e/test-results/
 /doc-site/_site/
-/doc-site/docs/legacy-html/
+/doc-site/docs/user-guide/chapters/
 
 src/index.html
diff --git a/doc-site/docs/index.md b/doc-site/docs/index.md
index fc6d359..aeeb128 100644
--- a/doc-site/docs/index.md
+++ b/doc-site/docs/index.md
@@ -6,6 +6,6 @@ LogAnalyzer is a PHP web front end for browsing syslog and related log data. Thi
 - **[Quick start](user-guide/quick-start.md)** — run with Docker and skim the UI with screenshots.
 - **[Interface map](user-guide/interface-map.md)** — main routes and where to read more.
 - [Third-party and bundled libraries](third-party.md) lists versions and update notes.
-- [User guide overview](legacy-html-manuals.md) indexes every imported manual page; sources remain [`doc/*.html`](https://github.com/rsyslog/loganalyzer/tree/master/doc) on GitHub.
+- [User guide overview](user-guide/overview.md) indexes every imported manual page; sources remain [`doc/*.html`](https://github.com/rsyslog/loganalyzer/tree/master/doc) on GitHub.
 
 Handbook build: `doc-site/`; published at [https://rsyslog.github.io/loganalyzer/](https://rsyslog.github.io/loganalyzer/) (`site_url` in `mkdocs.yml`).
diff --git a/doc-site/docs/user-guide/interface-map.md b/doc-site/docs/user-guide/interface-map.md
index bd9b6b8..2d4c5e5 100644
--- a/doc-site/docs/user-guide/interface-map.md
+++ b/doc-site/docs/user-guide/interface-map.md
@@ -11,12 +11,12 @@ LogAnalyzer is a PHP web UI. URLs below are the primary entry points; your deplo
 | Reports | `reports.php` | Report-oriented views. |
 | Administration | `admin/index.php` | Manage sources, users, and system options (administrators). |
 
-See [Search syntax](../legacy-html/searching.md) for query syntax used in filters and searches.
+See [Search syntax](chapters/searching.md) for query syntax used in filters and searches.
 
 ## Documentation trail
 
-- **Operational setup:** [Docker & CI](../docker.md), [Installation](../legacy-html/install.md), [Troubleshooting](../legacy-html/troubleshoot.md).
-- **Using the product:** [Basics](../legacy-html/basics.md), [Search syntax](../legacy-html/searching.md), [Text log files](../legacy-html/textfiles.md), [Windows Event Log](../legacy-html/windowsevent.md).
+- **Operational setup:** [Docker & CI](../docker.md), [Installation](chapters/install.md), [Troubleshooting](chapters/troubleshoot.md).
+- **Using the product:** [Basics](chapters/basics.md), [Search syntax](chapters/searching.md), [Text log files](chapters/textfiles.md), [Windows Event Log](chapters/windowsevent.md).
 
 ## Screenshots
 
diff --git a/doc-site/docs/legacy-html-manuals.md b/doc-site/docs/user-guide/overview.md
similarity index 56%
rename from doc-site/docs/legacy-html-manuals.md
rename to doc-site/docs/user-guide/overview.md
index 15ef146..d7d75c5 100644
--- a/doc-site/docs/legacy-html-manuals.md
+++ b/doc-site/docs/user-guide/overview.md
@@ -6,16 +6,16 @@ Every `*.html` manual under [`doc/`](https://github.com/rsyslog/loganalyzer/blob
 
 ## Pages (in-site)
 
-- [Documentation home](legacy-html/manual.md) (`manual.html`)
-- [Basics](legacy-html/basics.md) (`basics.html`)
-- [Installation](legacy-html/install.md) (`install.html`)
-- [Search syntax](legacy-html/searching.md) (`searching.html`)
-- [Troubleshooting](legacy-html/troubleshoot.md) (`troubleshoot.html`)
-- [Build from repo](legacy-html/build_from_repo.md) (`build_from_repo.html`)
-- [Free support](legacy-html/free_support.md) (`free_support.html`)
-- [Professional services](legacy-html/professional_services.md) (`professional_services.html`)
-- [Text log files](legacy-html/textfiles.md) (`textfiles.html`)
-- [Windows Event Log](legacy-html/windowsevent.md) (`windowsevent.html`)
+- [Documentation home](chapters/manual.md) (`manual.html`)
+- [Basics](chapters/basics.md) (`basics.html`)
+- [Installation](chapters/install.md) (`install.html`)
+- [Search syntax](chapters/searching.md) (`searching.html`)
+- [Troubleshooting](chapters/troubleshoot.md) (`troubleshoot.html`)
+- [Build from repo](chapters/build_from_repo.md) (`build_from_repo.html`)
+- [Free support](chapters/free_support.md) (`free_support.html`)
+- [Professional services](chapters/professional_services.md) (`professional_services.html`)
+- [Text log files](chapters/textfiles.md) (`textfiles.html`)
+- [Windows Event Log](chapters/windowsevent.md) (`windowsevent.html`)
 
 ## Source in the repository
 
diff --git a/doc-site/docs/user-guide/quick-start.md b/doc-site/docs/user-guide/quick-start.md
index 5bb71e0..23d5f40 100644
--- a/doc-site/docs/user-guide/quick-start.md
+++ b/doc-site/docs/user-guide/quick-start.md
@@ -39,5 +39,5 @@ PNG files under `doc-site/docs/assets/user-guide/` are produced with **Playwrigh
 ## Go deeper
 
 - [Interface map](interface-map.md) — how main areas fit together.
-- [User guide overview](../legacy-html-manuals.md) — full list of imported chapters from `doc/`.
-- [Installation](../legacy-html/install.md) and [Basics](../legacy-html/basics.md) for configuration and concepts.
+- [User guide overview](overview.md) — full list of imported chapters from `doc/`.
+- [Installation](chapters/install.md) and [Basics](chapters/basics.md) for configuration and concepts.
diff --git a/doc-site/mkdocs.yml b/doc-site/mkdocs.yml
index b5c9fe9..b550f77 100644
--- a/doc-site/mkdocs.yml
+++ b/doc-site/mkdocs.yml
@@ -30,18 +30,18 @@ nav:
   - Home: index.md
   - Docker & CI (from AGENTS.md): docker.md
   - LogAnalyzer user guide:
-    - Overview: legacy-html-manuals.md
-    - Quick start: user-guide/quick-start.md
-    - Interface map: user-guide/interface-map.md
-    - Documentation home: legacy-html/manual.md
-    - Basics: legacy-html/basics.md
-    - Installation: legacy-html/install.md
-    - Search syntax: legacy-html/searching.md
-    - Troubleshooting: legacy-html/troubleshoot.md
-    - Build from repo: legacy-html/build_from_repo.md
-    - Free support: legacy-html/free_support.md
-    - Professional services: legacy-html/professional_services.md
-    - Text log files: legacy-html/textfiles.md
-    - Windows Event Log: legacy-html/windowsevent.md
+    - 'Overview': user-guide/overview.md
+    - 'Quick start': user-guide/quick-start.md
+    - 'Interface map': user-guide/interface-map.md
+    - 'Documentation home': user-guide/chapters/manual.md
+    - 'Basics': user-guide/chapters/basics.md
+    - 'Installation': user-guide/chapters/install.md
+    - 'Search syntax': user-guide/chapters/searching.md
+    - 'Troubleshooting': user-guide/chapters/troubleshoot.md
+    - 'Build from repo': user-guide/chapters/build_from_repo.md
+    - 'Free support': user-guide/chapters/free_support.md
+    - 'Professional services': user-guide/chapters/professional_services.md
+    - 'Text log files': user-guide/chapters/textfiles.md
+    - 'Windows Event Log': user-guide/chapters/windowsevent.md
   - Repository README: project-readme.md
   - Third-party components: third-party.md
diff --git a/doc-site/prepare_docs.py b/doc-site/prepare_docs.py
index a7f7eee..3e42e8a 100644
--- a/doc-site/prepare_docs.py
+++ b/doc-site/prepare_docs.py
@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Prepare doc-site/docs from repository Markdown; embed legacy HTML as MkDocs pages."""
+"""Prepare doc-site/docs from repository Markdown; embed upstream doc/*.html as MkDocs pages under user-guide/chapters/."""
 from __future__ import annotations
 
 import os
@@ -9,7 +9,10 @@
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 OUT_DIR = Path(__file__).resolve().parent / "docs"
-LEGACY_SUBDIR = "legacy-html"
+# Handbook-native pages live in user-guide/; imported doc/*.html render under user-guide/chapters/.
+USER_GUIDE_DIR = "user-guide"
+IMPORTED_CHAPTERS_DIR = "chapters"
+OVERVIEW_MD = "overview.md"
 REPO_URL = os.environ.get("GHP_REPO_URL", "https://github.com/rsyslog/loganalyzer").rstrip("/")
 DEFAULT_BRANCH = os.environ.get("GHP_DEFAULT_BRANCH", "master").strip() or "master"
 
@@ -122,13 +125,15 @@ def _ordered_legacy_stems(stems: set[str]) -> list[str]:
 def _format_legacy_nav_lines(stems_ordered: list[str]) -> list[str]:
     lines = [
         LEGACY_NAV_HEADER,
-        "    - Overview: legacy-html-manuals.md",
-        "    - Quick start: user-guide/quick-start.md",
-        "    - Interface map: user-guide/interface-map.md",
+        f"    - {_yaml_single_quoted('Overview')}: {USER_GUIDE_DIR}/{OVERVIEW_MD}",
+        f"    - {_yaml_single_quoted('Quick start')}: {USER_GUIDE_DIR}/quick-start.md",
+        f"    - {_yaml_single_quoted('Interface map')}: {USER_GUIDE_DIR}/interface-map.md",
     ]
     for stem in stems_ordered:
         label = LEGACY_NAV_LABELS.get(stem, stem.replace("_", " ").title())
-        lines.append(f"    - {label}: legacy-html/{stem}.md")
+        lines.append(
+            f"    - {_yaml_single_quoted(label)}: {USER_GUIDE_DIR}/{IMPORTED_CHAPTERS_DIR}/{stem}.md"
+        )
     return lines
 
 
@@ -177,6 +182,16 @@ def _write_legacy_markdown(
     out_path.write_text(md, encoding="utf-8", newline="\n")
 
 
+def _remove_pre_migration_doc_artifacts(out_dir: Path) -> None:
+    """Remove handbook output from the pre-PR layout (legacy-html/, legacy-html-manuals.md)."""
+    for name in ("legacy-html", "legacy-html-manuals.md"):
+        path = out_dir / name
+        if path.is_dir():
+            shutil.rmtree(path)
+        elif path.is_file():
+            path.unlink()
+
+
 def main() -> int:
     OUT_DIR.mkdir(parents=True, exist_ok=True)
     agents = REPO_ROOT / "AGENTS.md"
@@ -188,12 +203,16 @@ def main() -> int:
         text = readme.read_text(encoding="utf-8", errors="replace")
         (OUT_DIR / "project-readme.md").write_text(text, encoding="utf-8", newline="\n")
         print(f"Wrote {OUT_DIR / 'project-readme.md'}")
+    _remove_pre_migration_doc_artifacts(OUT_DIR)
     manuals = REPO_ROOT / "doc"
     if manuals.is_dir():
-        legacy_out = OUT_DIR / LEGACY_SUBDIR
-        if legacy_out.is_dir():
-            shutil.rmtree(legacy_out)
-        legacy_out.mkdir(parents=True, exist_ok=True)
+        guide_root = OUT_DIR / USER_GUIDE_DIR
+        guide_root.mkdir(parents=True, exist_ok=True)
+        chapters_out = guide_root / IMPORTED_CHAPTERS_DIR
+        if chapters_out.is_dir():
+            shutil.rmtree(chapters_out)
+        chapters_out.mkdir(parents=True, exist_ok=True)
+
         html_files = sorted(manuals.glob("*.html"))
         stems = {f.stem for f in html_files}
 
@@ -202,11 +221,11 @@ def main() -> int:
             doc_title, body = _extract_title_and_body(raw)
             body = _rewrite_hrefs(body, stems)
             md_name = src.with_suffix(".md").name
-            _write_legacy_markdown(legacy_out / md_name, doc_title, body)
-            print(f"Wrote {legacy_out / md_name} <- {src.name}")
+            _write_legacy_markdown(chapters_out / md_name, doc_title, body)
+            print(f"Wrote {chapters_out / md_name} <- {src.name}")
 
         blob_base = f"{REPO_URL}/blob/{DEFAULT_BRANCH}/doc"
-        rel_prefix = f"{LEGACY_SUBDIR}/"
+        rel_prefix = f"{IMPORTED_CHAPTERS_DIR}/"
 
         ordered = _ordered_legacy_stems(stems)
         stem_to_html = {f.stem: f.name for f in html_files}
@@ -240,12 +259,9 @@ def main() -> int:
                 "",
             ]
         )
-        (OUT_DIR / "legacy-html-manuals.md").write_text(
-            "\n".join(lines) + "\n",
-            encoding="utf-8",
-            newline="\n",
-        )
-        print(f"Wrote {OUT_DIR / 'legacy-html-manuals.md'}")
+        overview_path = OUT_DIR / USER_GUIDE_DIR / OVERVIEW_MD
+        overview_path.write_text("\n".join(lines) + "\n", encoding="utf-8", newline="\n")
+        print(f"Wrote {overview_path}")
         _patch_mkdocs_legacy_nav(_ordered_legacy_stems(stems))
     return 0