docs: clarify dark-mode vs Valentus roles and legacy names

Add Legacy names migration guide; stop recommending stacking the
overlay on Valentus (already bundled); fix Default UI examples.

Author: AMDphreak

.github/workflows/release.yml

@@ -103,7 +103,7 @@ jobs:
           node -e "const fs=require('fs');const p=JSON.parse(fs.readFileSync('package.json','utf8'));delete p.private;fs.writeFileSync('package.json',JSON.stringify(p,null,2)+'\n')"
           npm --version
           npm publish --access public
-          npm deprecate antora-dark-theme@* "Renamed — use valentus-theme (bundled dark mode). See https://github.com/antora-supplemental/valentus-theme" || true
+          npm deprecate antora-dark-theme@* "Split: use valentus-theme (chrome + dark) or antora-dark-mode (overlay only). See https://antora-supplemental.github.io/antora-dark-mode/antora-dark-mode/guide/legacy-names.html" || true
         # Trusted publisher on npmjs.com (package → Settings → Trusted publishing):
         #   Provider: GitHub Actions
         #   Organization/user: antora-supplemental

CHANGELOG.adoc

@@ -10,6 +10,8 @@ Entries below are in **chronological order** by date: prior release, then the **
 
 == [Unreleased]
 
+* *Docs:* Guide page xref:guide:legacy-names.adoc[Legacy names & migration] — `antora-dark-theme` → `valentus-theme` / `antora-dark-mode`, canonical org repos vs personal forks, Zulip correction blurb. Linked from Getting Started and Installation.
+* *Docs:* Clarify product roles — Valentus release bundle already includes dark mode; overlay / ui-module examples use Default UI (do not stack this package on Valentus `ui-bundle.zip`).
 * *CI:* Release workflow fixes (`v*.*.*` tag filter, `workflow_dispatch`, lockfile); npm publish via trusted publishing (OIDC) — no `NPM_TOKEN`.
 
 == [1.3.1] - 2026-06-13

README.adoc

@@ -42,20 +42,22 @@ If you'd like to see native dark mode support in Antora, please upvote the featu
 
 Your support helps the Antora team prioritize this feature!
 
-**Doc-site chrome** (mast, header layout, VCS icons) lives in link:https://github.com/antora-supplemental/valentus-theme[valentus-theme].
-Pair dark mode as overlay or ui-module on top of the *valentus* `ui.bundle` — not the other way around.
+**Full chrome + dark mode** (mast, header, layout, VCS icons, toggle) lives in link:https://github.com/antora-supplemental/valentus-theme[valentus-theme] — use that release `ui-bundle.zip` when you want the whole stack.
+This package is the *dark-mode-only* overlay for Default UI or other themes that do not already ship dark mode.
+Coming from the retired **`antora-dark-theme`** name? See xref:legacy-names.adoc[Legacy names & migration].
 
 == Quick Start
 
 === Overlay on your theme bundle (recommended)
 
-Reserve `ui.bundle` for your theme. Layer dark mode via one `supplemental_files` directory:
+Reserve `ui.bundle` for a theme that does *not* already include dark mode (Default UI, custom themes, etc.).
+Do **not** layer this overlay on the Valentus release bundle — Valentus already bundles dark mode.
 
 [source,yaml]
 ----
 ui:
   bundle:
-    url: https://github.com/antora-supplemental/valentus-theme/releases/download/v2/ui-bundle.zip
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
     snapshot: true
   supplemental_files: ./site/supplemental-ui   # merge antora-dark-mode supplemental-ui here
 ----

README.md

@@ -2,7 +2,11 @@
 
 Dark mode supplemental UI for Antora — overlay install or slot-based ui-module.
 
-**Does not occupy `ui.bundle`** when mixed with valentus or other themes. See [Installation](https://antora-supplemental.github.io/antora-dark-mode/antora-dark-mode/guide/installation.html).
+**Does not occupy `ui.bundle`** when mixed with another theme. See [Installation](https://antora-supplemental.github.io/antora-dark-mode/antora-dark-mode/guide/installation.html).
+
+Want mast/header/layout chrome *plus* dark mode? Use **[valentus-theme](https://github.com/antora-supplemental/valentus-theme)** (release `ui-bundle.zip` already includes dark mode) — do not stack this overlay on Valentus.
+
+Migrating from the retired **`antora-dark-theme`** package? See [Legacy names & migration](https://antora-supplemental.github.io/antora-dark-mode/antora-dark-mode/guide/legacy-names.html).
 
 ---
 
@@ -15,7 +19,7 @@ pnpm add -D antora-dark-mode
 ```yaml
 ui:
   bundle:
-    url: https://github.com/antora-supplemental/valentus-theme/releases/download/v2/ui-bundle.zip
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
     snapshot: true
   supplemental_files: ./site/supplemental-ui   # merge node_modules/antora-dark-mode/supplemental-ui
 ```
@@ -42,6 +46,7 @@ Republishing to npm as **overlay transport** (not `ui.bundle` replacement). Same
 | Resource | URL |
 |----------|-----|
 | Install guide | [installation.adoc](docs/modules/guide/pages/installation.adoc) |
+| Legacy names | [legacy-names.adoc](docs/modules/guide/pages/legacy-names.adoc) |
 | UI modules | [ui-modules.adoc](docs/modules/guide/pages/ui-modules.adoc) |
 | Live demo | [antora-supplemental.github.io/antora-dark-mode](https://antora-supplemental.github.io/antora-dark-mode) |
 | Source | [github.com/antora-supplemental/antora-dark-mode](https://github.com/antora-supplemental/antora-dark-mode) |

docs/maintainers/antora-chat-corrections.md

@@ -2,6 +2,8 @@
 
 Post these in [Antora Zulip](https://antora.zulipchat.com/) where older threads still reference `antora-dark-theme`.
 
+Published guide (preferred link for readers): [Legacy names & migration](https://antora-supplemental.github.io/antora-dark-mode/antora-dark-mode/guide/legacy-names.html) (`docs/modules/guide/pages/legacy-names.adoc`).
+
 ---
 
 ## Short correction (reply to outdated install advice)

docs/maintainers/npm-republish-plan.md

@@ -64,7 +64,7 @@ After trusted publishing works, consider **Settings → Publishing access → Re
 
 ```powershell
 # After publish — deprecate legacy package name (if you own antora-dark-theme)
-npm deprecate antora-dark-theme@* "Renamed — use antora-dark-mode. See https://github.com/antora-supplemental/antora-dark-mode"
+npm deprecate antora-dark-theme@* "Split: use valentus-theme (chrome + dark) or antora-dark-mode (overlay only). See https://antora-supplemental.github.io/antora-dark-mode/antora-dark-mode/guide/legacy-names.html"
 ```
 
 `prepack` script runs sync + validate automatically.

docs/modules/guide/nav.adoc

@@ -1,6 +1,7 @@
 .Documentation
 * xref:index.adoc[Getting Started]
 * xref:installation.adoc[Installation]
+* xref:legacy-names.adoc[Legacy names & migration]
 * xref:ui-modules.adoc[UI Modules]
 * xref:npm-distribution.adoc[npm distribution]
 * xref:configuration.adoc[Configuration]

docs/modules/guide/pages/index.adoc

@@ -6,6 +6,8 @@ Dark mode toggle, FOUC prevention, and CSS overrides for the Antora Default UI.
 
 For composed doc-site chrome (mast, header, layout), see link:https://github.com/antora-supplemental/valentus-theme[valentus-theme].
 
+Coming from the former **`antora-dark-theme`** package (or a personal fork of that name)? See xref:legacy-names.adoc[Legacy names & migration].
+
 == Install
 
 See xref:installation.adoc[Installation], xref:ui-modules.adoc[UI Modules], and xref:npm-distribution.adoc[npm distribution].

docs/modules/guide/pages/installation.adoc

@@ -3,7 +3,11 @@
 :description: Install Antora dark mode as a supplemental overlay or composable UI module.
 
 Dark mode is a *slipstream overlay* — it must **not** occupy `ui.bundle.url` when you mix it with another theme.
-Reserve `ui.bundle` for your theme (Default UI, valentus-theme, architexture-theme, a custom bundle, etc.).
+Reserve `ui.bundle` for your theme (Default UI, architexture-theme, a custom bundle, etc.).
+
+IMPORTANT: link:https://github.com/antora-supplemental/valentus-theme[valentus-theme] already ships *bundled* dark mode in its release `ui-bundle.zip`.
+Do **not** layer this overlay on Valentus unless you are composing modules from scratch — use Valentus alone for the full chrome + dark stack.
+Coming from the retired **`antora-dark-theme`** package? See xref:legacy-names.adoc[Legacy names & migration].
 
 * link:https://github.com/antora-supplemental/antora-dark-mode/releases[GitHub Releases]
 * link:https://antora-supplemental.github.io/docs/[Antora Supplemental docs portal] (extensions registry)
@@ -15,12 +19,12 @@ Reserve `ui.bundle` for your theme (Default UI, valentus-theme, architexture-the
 | Path | When to use | `ui.bundle` owner
 
 | xref:#overlay[Supplemental overlay] (recommended)
-| Any theme; one merged `supplemental_files` directory
-| Your theme or Default UI
+| Dark mode on Default UI or a theme that does *not* already include it
+| Your theme or Default UI (**not** Valentus release bundle)
 
 | xref:ui-modules.adoc[UI module + orchestrator]
-| Theme chrome from valentus + dark mode without partial collisions
-| Your theme release bundle
+| Slot-based inject when the theme owns `head-meta` / `footer-scripts` partials
+| Your theme release bundle (compose; skip if using Valentus pre-merged zip)
 
 | xref:#convenience-bundle[Convenience `ui-bundle.zip`]
 | Quick start on Default UI only — no other theme
@@ -51,7 +55,7 @@ cp -r node_modules/antora-dark-mode/supplemental-ui/* site/supplemental-ui/
 ----
 ui:
   bundle:
-    url: https://github.com/antora-supplemental/valentus-theme/releases/download/v2/ui-bundle.zip
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
     snapshot: true
   supplemental_files: ./site/supplemental-ui
 ----

docs/modules/guide/pages/legacy-names.adoc

@@ -0,0 +1,88 @@
+= Legacy names & migration
+:navtitle: Legacy names
+:description: Migrate from antora-dark-theme (and personal forks) to antora-dark-mode and valentus-theme.
+
+[[migrate-from-antora-dark-theme]]
+== From `antora-dark-theme`
+
+The monolithic **`antora-dark-theme`** package was split and renamed under the `antora-supplemental` organization.
+
+[cols="2,3", options="header"]
+|===
+| Former | Use instead
+
+| `antora-dark-theme` (npm / GitHub release bundle) as full site UI
+| link:https://github.com/antora-supplemental/valentus-theme[`valentus-theme`^] release `ui-bundle.zip` (chrome + **bundled dark mode**)
+
+| Dark mode only on another theme / Default UI
+| **`antora-dark-mode`** — slipstream overlay (must **not** occupy `ui.bundle` when mixed with another theme)
+|===
+
+=== Playbook: full stack
+
+Replace:
+
+[source,yaml]
+----
+ui:
+  bundle:
+    url: https://github.com/antora-supplemental/antora-dark-theme/releases/.../ui-bundle.zip
+----
+
+With:
+
+[source,yaml]
+----
+ui:
+  bundle:
+    url: https://github.com/antora-supplemental/valentus-theme/releases/download/v2/ui-bundle.zip
+    snapshot: true
+----
+
+Remove `antora-dark-theme` from `package.json` if present.
+Valentus install details: link:https://antora-supplemental.github.io/valentus-theme/[valentus-theme docs^].
+
+=== Playbook: dark mode overlay only
+
+Keep your theme (or Default UI) in `ui.bundle`, then layer dark mode via `supplemental_files` — see xref:installation.adoc[Installation].
+
+[source,bash]
+----
+pnpm add -D antora-dark-mode
+----
+
+== Canonical repositories (not personal forks)
+
+| Role | Canonical home |
+|---|---|
+| Dark mode overlay | https://github.com/antora-supplemental/antora-dark-mode[`antora-supplemental/antora-dark-mode`^] |
+| Composed chrome + dark mode | https://github.com/antora-supplemental/valentus-theme[`antora-supplemental/valentus-theme`^] |
+| Org public GitHub config | https://github.com/antora-supplemental/.github[`antora-supplemental/.github`^] |
+| Org private GitHub config | https://github.com/antora-supplemental/.github-private[`antora-supplemental/.github-private`^] |
+
+Personal forks of the old `antora-dark-theme` name (for example under a member account) are obsolete once history is contained in the org repos above.
+Do not publish or pin those forks as the install source.
+
+Default UI dark-mode experiments that lived on a GitLab fork of `antora-ui-default` are **upstream proposals** (see open MRs on https://gitlab.com/antora/antora-ui-default[`antora/antora-ui-default`^]).
+Sites that need dark mode today should use this overlay or Valentus rather than waiting on Default UI merge.
+
+== Zulip / community corrections
+
+Short copy for threads that still say `antora-dark-theme`:
+
+[source,text]
+----
+The monolithic antora-dark-theme package was split:
+- Full chrome + dark mode → valentus-theme (release ui-bundle.zip)
+- Dark mode overlay only → antora-dark-mode
+Docs: https://antora-supplemental.github.io/valentus-theme/
+----
+
+Maintainer paste templates also live in `docs/maintainers/antora-chat-corrections.md`.
+
+== See also
+
+* xref:installation.adoc[Installation]
+* xref:npm-distribution.adoc[npm distribution]
+* link:https://antora-supplemental.github.io/docs/docs/theme-products.html[Theme products (org docs hub)^]
+* link:https://antora-supplemental.github.io/docs/docs/org-github-config.html[Org GitHub config (docs hub)^]