diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7fd7a5c..5fbfac0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -16,16 +16,16 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up JDK 21
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
         with:
           distribution: temurin
           java-version: '21'
 
       - name: Cache Maven local repository
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.m2/repository
           key: ${{ runner.os }}-m2-${{ matrix.paper-version }}-${{ hashFiles('**/pom.xml') }}
@@ -47,16 +47,16 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up JDK 21
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
         with:
           distribution: temurin
           java-version: '21'
 
       - name: Cache Maven local repository
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.m2/repository
           key: ${{ runner.os }}-m2-feature-${{ matrix.paper-version }}-${{ hashFiles('**/pom.xml') }}
@@ -65,3 +65,248 @@ jobs:
 
       - name: Run feature tests
         run: mvn -B -Dpaper.version=${{ matrix.paper-version }} -Dmockbukkit.artifactId=${{ matrix.mockbukkit-artifactId }} -Dmockbukkit.version=${{ matrix.mockbukkit-version }} -Pfeature-tests -Dtest=*FeatureTest test
+
+  # ─────────────────────────────────────────────────────────────────────────
+  # Smoke tests — Paper & Folia (downloaded from api.papermc.io)
+  # Matrix: platform × mc-prefix × java
+  # ─────────────────────────────────────────────────────────────────────────
+  smoke-papermc:
+    name: "Smoke · ${{ matrix.platform }} / MC ${{ matrix.mc-prefix }} / Java ${{ matrix.java }}"
+    runs-on: ubuntu-latest
+    needs: [unit-tests, feature-tests]
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: [paper, folia]
+        mc-prefix: ["1.21", "26.1"]
+        java: [21, 25]
+        exclude:
+          # MC 26.1 requires Java 25+
+          - mc-prefix: "26.1"
+            java: 21
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up JDK ${{ matrix.java }}
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: ${{ matrix.java }}
+          cache: maven
+
+      - name: Build plugin JAR
+        run: mvn -B -ntp -DskipTests package
+
+      - name: Resolve latest ${{ matrix.platform }} build for MC ${{ matrix.mc-prefix }}.x
+        id: server
+        run: |
+          PLATFORM="${{ matrix.platform }}"
+          PREFIX="${{ matrix.mc-prefix }}"
+          VERSIONS_JSON=$(curl -fsSL "https://fill.papermc.io/v3/projects/${PLATFORM}")
+          MC_VERSION=$(PREFIX="${PREFIX}" python3 -c "import sys,os,json;d=json.loads(sys.stdin.read());p=os.environ['PREFIX'];vs=d.get('versions',{});fam=p if p in vs else next((f for f in vs if f.startswith(p+'.')),None);print(vs[fam][0] if fam and vs.get(fam) else '')" <<< "$VERSIONS_JSON")
+          if [[ -z "$MC_VERSION" ]]; then
+            echo "::error::No ${PLATFORM} builds found matching MC ${PREFIX}.x."
+            echo "available=false" >> "$GITHUB_OUTPUT"
+            exit 1
+          fi
+          BUILDS_JSON=$(curl -fsSL "https://fill.papermc.io/v3/projects/${PLATFORM}/versions/${MC_VERSION}/builds")
+          BUILD_INFO=$(python3 -c "import sys,json;bs=json.loads(sys.stdin.read());st=[b for b in bs if b.get('channel')=='STABLE'];c=st[0] if st else (bs[0] if bs else None);[print(c['id']),print(c['downloads']['server:default']['url'])] if c else None" <<< "$BUILDS_JSON")
+          BUILD=$(echo "$BUILD_INFO" | sed -n '1p')
+          DOWNLOAD_URL=$(echo "$BUILD_INFO" | sed -n '2p')
+          JAR_NAME=$(basename "$DOWNLOAD_URL")
+          if [[ -z "$BUILD" || -z "$DOWNLOAD_URL" ]]; then
+            echo "::error::No builds found for ${PLATFORM} ${MC_VERSION}."
+            echo "available=false" >> "$GITHUB_OUTPUT"
+            exit 1
+          fi
+          echo "mc_version=${MC_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "build=${BUILD}"           >> "$GITHUB_OUTPUT"
+          echo "jar_name=${JAR_NAME}"     >> "$GITHUB_OUTPUT"
+          echo "download_url=${DOWNLOAD_URL}" >> "$GITHUB_OUTPUT"
+          echo "available=true"          >> "$GITHUB_OUTPUT"
+          echo "Resolved: ${PLATFORM} ${MC_VERSION} build ${BUILD} (${JAR_NAME})"
+
+      - name: Download ${{ matrix.platform }} server JAR
+        if: steps.server.outputs.available == 'true'
+        run: |
+          mkdir -p smoke-server/plugins
+          curl -fsSL "${{ steps.server.outputs.download_url }}" -o smoke-server/server.jar
+
+      - name: Copy plugin JAR
+        if: steps.server.outputs.available == 'true'
+        run: cp target/EzCountdown-*.jar smoke-server/plugins/EzCountdown.jar
+
+      - name: Configure server
+        if: steps.server.outputs.available == 'true'
+        run: |
+          echo "eula=true" > smoke-server/eula.txt
+          printf '%s\n' \
+            "online-mode=false" \
+            "level-type=flat" \
+            "generate-structures=false" \
+            "max-players=0" \
+            > smoke-server/server.properties
+
+      - name: Run server and wait for ready
+        if: steps.server.outputs.available == 'true'
+        run: |
+          cd smoke-server
+          java -Xms512m -Xmx1g -jar server.jar --nogui > server.log 2>&1 &
+          SERVER_PID=$!
+          ELAPSED=0
+          while [ $ELAPSED -lt 120 ]; do
+            sleep 2; ELAPSED=$((ELAPSED + 2))
+            if grep -q "Done (" server.log 2>/dev/null; then
+              echo "Server ready after ${ELAPSED}s"; break
+            fi
+            if ! kill -0 $SERVER_PID 2>/dev/null; then
+              echo "Server process exited after ${ELAPSED}s"; break
+            fi
+          done
+          kill $SERVER_PID 2>/dev/null || true
+          wait $SERVER_PID 2>/dev/null || true
+
+      - name: Assert no EzCountdown errors
+        if: steps.server.outputs.available == 'true'
+        run: |
+          LOG=smoke-server/server.log
+          if grep -qiE "SEVERE.*EzCountdown|Could not load.*EzCountdown|Error initialising.*EzCountdown" "$LOG"; then
+            echo "::error::EzCountdown logged errors on ${{ matrix.platform }} MC ${{ matrix.mc-prefix }} (Java ${{ matrix.java }}):"
+            grep -iE "SEVERE.*EzCountdown|Could not load.*EzCountdown|Error initialising.*EzCountdown" "$LOG"
+            exit 1
+          fi
+          if grep -qiE "Enabling EzCountdown|EzCountdown.*enabled" "$LOG"; then
+            echo "Smoke test passed — EzCountdown loaded on ${{ matrix.platform }} MC ${{ steps.server.outputs.mc_version }} (Java ${{ matrix.java }})."
+          else
+            echo "::warning::Plugin load confirmation not found — server may not have finished loading within the timeout."
+          fi
+
+      - name: Upload server log
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: smoke-log-${{ matrix.platform }}-mc${{ matrix.mc-prefix }}-java${{ matrix.java }}
+          path: smoke-server/server.log
+          if-no-files-found: ignore
+          retention-days: 7
+
+  # ─────────────────────────────────────────────────────────────────────────
+  # Smoke tests — Spigot (compiled via BuildTools, result cached by MC+Java)
+  # Matrix: mc-prefix × java
+  # ─────────────────────────────────────────────────────────────────────────
+  smoke-spigot:
+    name: "Smoke · spigot / MC ${{ matrix.mc-prefix }} / Java ${{ matrix.java }}"
+    runs-on: ubuntu-latest
+    needs: [unit-tests, feature-tests]
+    strategy:
+      fail-fast: false
+      matrix:
+        mc-prefix: ["1.21"]
+        java: [21, 25]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up JDK ${{ matrix.java }}
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: ${{ matrix.java }}
+          cache: maven
+
+      - name: Configure Git for BuildTools
+        run: |
+          git config --global user.email "ci@github.com"
+          git config --global user.name  "CI"
+
+      - name: Build plugin JAR
+        run: mvn -B -ntp -DskipTests package
+
+      - name: Restore cached Spigot JAR (MC ${{ matrix.mc-prefix }}, Java ${{ matrix.java }})
+        id: spigot-cache
+        uses: actions/cache@v5
+        with:
+          path: spigot-build/spigot-${{ matrix.mc-prefix }}.jar
+          key: spigot-jar-mc${{ matrix.mc-prefix }}-java${{ matrix.java }}-v1
+
+      - name: Build Spigot via BuildTools
+        if: steps.spigot-cache.outputs.cache-hit != 'true'
+        id: buildtools
+        run: |
+          mkdir -p spigot-build/work
+          cd spigot-build/work
+          curl -fsSL \
+            "https://hub.spigotmc.org/jenkins/job/BuildTools/lastSuccessfulBuild/artifact/target/BuildTools.jar" \
+            -o BuildTools.jar
+          java -jar BuildTools.jar --rev "${{ matrix.mc-prefix }}" 2>&1 | tee buildtools.log || {
+            echo "::warning::BuildTools failed for MC ${{ matrix.mc-prefix }} on Java ${{ matrix.java }} — version may not be supported yet. Spigot smoke test will be skipped."
+            echo "failed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          }
+          SPIGOT_JAR=$(ls spigot-${{ matrix.mc-prefix }}*.jar 2>/dev/null | head -1)
+          if [[ -z "$SPIGOT_JAR" ]]; then
+            SPIGOT_JAR=$(ls spigot*.jar 2>/dev/null | grep -v craftbukkit | head -1)
+          fi
+          if [[ -n "$SPIGOT_JAR" ]]; then
+            cp "$SPIGOT_JAR" "../spigot-${{ matrix.mc-prefix }}.jar"
+            echo "::notice::Cached ${SPIGOT_JAR} as spigot-${{ matrix.mc-prefix }}.jar"
+          else
+            echo "::warning::BuildTools completed but no Spigot JAR found — smoke test will be skipped."
+            echo "failed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Run Spigot smoke test
+        run: |
+          SPIGOT_JAR="spigot-build/spigot-${{ matrix.mc-prefix }}.jar"
+          if [[ ! -f "$SPIGOT_JAR" ]]; then
+            echo "::warning::Spigot JAR not available for MC ${{ matrix.mc-prefix }} — BuildTools could not build this version. Smoke test skipped."
+            exit 0
+          fi
+          mkdir -p smoke-server/plugins
+          cp "$SPIGOT_JAR" smoke-server/server.jar
+          cp target/EzCountdown-*.jar smoke-server/plugins/EzCountdown.jar
+          echo "eula=true" > smoke-server/eula.txt
+          printf '%s\n' \
+            "online-mode=false" \
+            "level-type=flat" \
+            "generate-structures=false" \
+            "max-players=0" \
+            > smoke-server/server.properties
+          cd smoke-server
+          java -Xms512m -Xmx1g -jar server.jar --nogui > server.log 2>&1 &
+          SERVER_PID=$!
+          ELAPSED=0
+          while [ $ELAPSED -lt 120 ]; do
+            sleep 2; ELAPSED=$((ELAPSED + 2))
+            if grep -q "Done (" server.log 2>/dev/null; then
+              echo "Server ready after ${ELAPSED}s"; break
+            fi
+            if ! kill -0 $SERVER_PID 2>/dev/null; then
+              echo "Server process exited after ${ELAPSED}s"; break
+            fi
+          done
+          kill $SERVER_PID 2>/dev/null || true
+          wait $SERVER_PID 2>/dev/null || true
+          LOG=server.log
+          if grep -qiE "SEVERE.*EzCountdown|Could not load.*EzCountdown|Error initialising.*EzCountdown" "$LOG"; then
+            echo "::error::EzCountdown logged errors on Spigot MC ${{ matrix.mc-prefix }} (Java ${{ matrix.java }}):"
+            grep -iE "SEVERE.*EzCountdown|Could not load.*EzCountdown|Error initialising.*EzCountdown" "$LOG"
+            exit 1
+          fi
+          if grep -qiE "Enabling EzCountdown|EzCountdown.*enabled" "$LOG"; then
+            echo "Smoke test passed — EzCountdown loaded on Spigot MC ${{ matrix.mc-prefix }} (Java ${{ matrix.java }})."
+          else
+            echo "::warning::Plugin load confirmation not found — server may not have finished loading within the timeout."
+          fi
+
+      - name: Upload Spigot server log
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: smoke-log-spigot-mc${{ matrix.mc-prefix }}-java${{ matrix.java }}
+          path: smoke-server/server.log
+          if-no-files-found: ignore
+          retention-days: 7
diff --git a/.github/workflows/maven-publish.yml b/.github/workflows/maven-publish.yml
index 5f5d24a..9597741 100644
--- a/.github/workflows/maven-publish.yml
+++ b/.github/workflows/maven-publish.yml
@@ -16,9 +16,9 @@ jobs:
       packages: write
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up JDK 21
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v5
       with:
         java-version: '21'
         distribution: 'temurin'
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b2b3a6a..b60842f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,13 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-05-30
+
+### Added
+
+- **Folia support** - the plugin now runs on Folia (marked `folia-supported: true` in `plugin.yml`). Folia's `GlobalRegionScheduler` is used automatically when detected at runtime; Paper/Spigot continue to use the Bukkit scheduler.
+- **`compat/` package hierarchy** - clean OOP abstraction layer:
+  - `compat.platform.PlatformDetector` - detects Folia vs. Paper/Spigot at startup via `RegionizedServer` class presence.
+  - `compat.scheduler.SchedulerAdapter` / `TaskHandle` - platform-agnostic scheduler interface (`runTask`, `runTaskTimer`, `runTaskLater`, `runTaskAsync`).
+  - `compat.scheduler.BukkitSchedulerAdapter` - `SchedulerAdapter` backed by `BukkitScheduler` (Paper/Spigot).
+  - `compat.scheduler.FoliaSchedulerAdapter` - `SchedulerAdapter` backed by `GlobalRegionScheduler` (Folia); only class-loaded when Folia is detected.
+  - `compat.scheduler.SchedulerAdapterFactory` - chooses the correct adapter with graceful fallback if Folia classes are missing.
+  - `compat.version.ServerVersionUtil` - canonical location for runtime Minecraft version detection (replaces `util.ServerVersionUtil`).
+  - `compat.material.MaterialCompat` - canonical location for cross-version material resolution (replaces `util.MaterialCompat`).
+- **Startup platform log** - `PluginBootstrap` now logs the active scheduler adapter class on enable (e.g. `Scheduler: BukkitSchedulerAdapter`).
+
+### Changed
+
+- `util.ServerVersionUtil` and `util.MaterialCompat` are now `@Deprecated` delegation stubs that forward to their canonical `compat.*` counterparts; they will be removed in a future release.
+- All internal scheduler usages (`CountdownManager`, `FireworkShowManager`, `PatternScheduler`, `ChatInputListener`, all `listener.actions.*` GUI action classes, `SpigotIntegration`, `SpigotUpdateChecker`) now go through `SchedulerAdapter` instead of `Bukkit.getScheduler()` / `BukkitRunnable` directly.
+- **Scoreboard API modernised** - `ScoreboardDisplay` now delegates to `compat.scoreboard.ScoreboardCompat`. On Paper 1.20.3+ (`Criteria.DUMMY` available) the modern `registerNewObjective(String, Criteria, Component)` overload is used; older builds fall back to the legacy string overload. The deprecated `Scoreboard.resetScores(String)` calls are replaced by objective unregister/re-register via `ScoreboardCompat.resetObjective`.
+- **Title API modernised** - `TitleDisplay` now delegates to `compat.title.TitleCompat`. On Paper 1.18+ the Adventure `Player.showTitle(Title)` / `Player.clearTitle()` APIs are preferred over the deprecated `sendTitle(String...)` / `resetTitle()`. `TitleValidator` now also accepts `showTitle` as a valid title capability. A Spigot/legacy string fallback is retained.
+
+- **Per-player notification targeting**  -  `NotificationBuilder.players(Collection<Player>)` restricts a notification to specific players. `EzCountdownApi.sendNotification(Notification, Collection<Player>)` provides an inline alternative without building a `Notification` first.
+- **`Countdown.isVisibleTo(Player)`**  -  centralises per-player visibility logic (permission gate + target-player set) in one method; all display handlers now use it instead of duplicated inline checks.
+- **`CountdownBuilder.targetPlayers(Collection<Player>)`**  -  restrict a persistent countdown's display to specific players.
+- **Developer-friendly exception hierarchy**  -  new `com.skyblockexp.ezcountdown.api.exception` package:
+  - `EzCountdownException`  -  base unchecked exception; catch this for all EzCountdown API errors.
+  - `CountdownNotFoundException`  -  thrown when referencing a countdown name that does not exist; carries `getCountdownName()`.
+  - `DuplicateCountdownException`  -  thrown when creating a countdown whose name already exists; carries `getCountdownName()`.
+  - `InvalidConfigurationException`  -  thrown by `NotificationBuilder.build()` and future builder validators when configuration is invalid; replaces the generic `IllegalStateException`.
+- **`api-version` bumped to `1.18`** in `plugin.yml`; minimum supported Minecraft version is Paper/Spigot 1.18. Dialog display continues to require Paper 1.21.7+.
+- **Broadened Java compatibility** - release JARs now target Java 17 bytecode (previously Java 21), so the plugin runs on Paper 1.18 - 1.20.4 (Java 17) as well as Paper 1.20.5+ (Java 21). The `jdk21` Maven profile also targets Java 17 bytecode.
+- **`ServerVersionUtil`** - new utility class (`com.skyblockexp.ezcountdown.util.ServerVersionUtil`) for runtime Minecraft version detection; enables future conditional feature gating without hard API dependencies.
+- **Startup guard** - `onEnable` now logs the detected MC and Java version and disables the plugin with a clear error message if the server is too old (MC < 1.18 or Java < 17).
+
+### Changed
+
+- **All display handlers** (`ActionBarDisplay`, `TitleDisplay`, `ChatDisplay`, `BossBarDisplay`, `ScoreboardDisplay`, `DialogDisplay`) use `countdown.isVisibleTo(player)` instead of duplicated inline permission checks.
+- **`NotificationBuilder.build()`** now throws `InvalidConfigurationException` (a subclass of `EzCountdownException`) instead of a plain `IllegalStateException`.
+- **`ScoreboardDisplay`** catch blocks now include `NoSuchMethodError` so the scoreboard falls back to chat if the String-criteria `registerNewObjective` overload is ever removed in a future Paper build.
+- Project version bumped from `1.4.3` to `2.0.0`.
+
+### Fixed
+
+- **DURATION countdown resets to full duration on `/countdown reload`**  -  `resumeRunningCountdowns()` previously called `handler.onStart()`, which always sets `targetInstant` to `now + fullDuration`, discarding the `target_epoch` saved in storage. It now calls `handler.ensureTarget()` instead, which is a no-op when a target is already present. The same guard was added to the legacy fallback path for handler-less countdown types. End-commands that fired once before a reload will no longer fire again unexpectedly due to the countdown silently restarting.
+
 ## [1.4.2] - 2026-05-16
 
 ### Added
 
-- **Configurable time format** — new `display.time-format` section in `config.yml`.
-  - `pattern` (default `"{days}d {hours}h {minutes}m {seconds}s"`) — customize the token layout used for the `{formatted}` placeholder and `%ezcountdown_<name>_formatted%` PAPI expansion.
-  - `hide-leading-zeros` (default `true`) — when enabled, leading space-delimited segments whose unit value is zero are suppressed. For example, `0d 0h 5m 3s` is displayed as `5m 3s`.
+- **Configurable time format**  -  new `display.time-format` section in `config.yml`.
+  - `pattern` (default `"{days}d {hours}h {minutes}m {seconds}s"`)  -  customize the token layout used for the `{formatted}` placeholder and `%ezcountdown_<name>_formatted%` PAPI expansion.
+  - `hide-leading-zeros` (default `true`)  -  when enabled, leading space-delimited segments whose unit value is zero are suppressed. For example, `0d 0h 5m 3s` is displayed as `5m 3s`.
   - Applies to countdown display messages, discord webhook `{time_left}`, PlaceholderAPI, and the GUI preview action.
   - Hot-reloads with `/countdown reload`.
 
@@ -27,10 +73,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Notification API** — `EzCountdownApi.sendNotification(Notification)` fires a one-shot ephemeral timed display from any plugin without creating a persistent countdown or touching `countdowns.yml`.
-- **`Notification` model** — lightweight immutable value object with factory methods `Notification.ofSeconds(long)`, `Notification.of(Duration)`, and a fluent `NotificationBuilder` (display types, format message, start/end messages).
-- **`NotificationBuilder`** — fluent builder for `Notification`; all fields have sensible defaults (`ACTION_BAR` display, `{formatted}` message); `build()` validates duration > 0.
-- **Ephemeral countdown support** — `Countdown.isEphemeral()` / `CountdownBuilder.ephemeral(boolean)`; ephemeral countdowns are removed from memory automatically when they end and are never written to storage.
+- **Notification API**  -  `EzCountdownApi.sendNotification(Notification)` fires a one-shot ephemeral timed display from any plugin without creating a persistent countdown or touching `countdowns.yml`.
+- **`Notification` model**  -  lightweight immutable value object with factory methods `Notification.ofSeconds(long)`, `Notification.of(Duration)`, and a fluent `NotificationBuilder` (display types, format message, start/end messages).
+- **`NotificationBuilder`**  -  fluent builder for `Notification`; all fields have sensible defaults (`ACTION_BAR` display, `{formatted}` message); `build()` validates duration > 0.
+- **Ephemeral countdown support**  -  `Countdown.isEphemeral()` / `CountdownBuilder.ephemeral(boolean)`; ephemeral countdowns are removed from memory automatically when they end and are never written to storage.
 
 ## [1.3.2] - 2026-04-27
 
diff --git a/docs/_sass/color_schemes/ezcountdown.scss b/docs/_sass/color_schemes/ezcountdown.scss
index 782cf91..0b7e63f 100644
--- a/docs/_sass/color_schemes/ezcountdown.scss
+++ b/docs/_sass/color_schemes/ezcountdown.scss
@@ -1,4 +1,4 @@
-// EzCountdown — dark/green color scheme for just-the-docs
+// EzCountdown  -  dark/green color scheme for just-the-docs
 //
 // Palette:
 //   Background   #111111  (body)
@@ -6,7 +6,7 @@
 //   Elevated     #1e1e1e  (code blocks, search, table rows)
 //   Border       #2a2a2a
 //   Text         #c8d4cc  (body)  /  #ffffff (headings)
-//   Accent       #4ade80  (green — links, nav highlight, buttons)
+//   Accent       #4ade80  (green  -  links, nav highlight, buttons)
 //   Accent dim   #22c55e  (hover state)
 
 $color-scheme: dark;
diff --git a/docs/api/EzCountdownApi.md b/docs/api/EzCountdownApi.md
index 216222a..0742767 100644
--- a/docs/api/EzCountdownApi.md
+++ b/docs/api/EzCountdownApi.md
@@ -8,33 +8,57 @@ nav_order: 2
 
 Public service interface exposed by the plugin: `com.skyblockexp.ezcountdown.api.EzCountdownApi`
 
-Methods
+## Methods
+
+### Countdown lifecycle
 
 - `boolean startCountdown(String name)`
-  - Start a configured countdown by name. Returns `true` if started successfully.
+  - Start a configured countdown by name. Returns `true` if started successfully, `false` if the countdown was already running or does not exist.
 
 - `boolean stopCountdown(String name)`
-  - Stop a running countdown by name. Returns `true` if stopped.
+  - Stop a running countdown by name. Returns `true` if stopped, `false` if it was already stopped or does not exist.
 
 - `Optional<Countdown> getCountdown(String name)`
-  - Retrieve a countdown configuration/runtime instance by name.
+  - Retrieve a countdown configuration and runtime state by name.
 
 - `Collection<Countdown> listCountdowns()`
   - List all countdowns currently known to the plugin.
 
+### Countdown management
+
 - `boolean createCountdown(Countdown countdown)`
-  - Create and persist a new countdown configuration. Returns `true` on success.
+  - Create and persist a new countdown configuration. Returns `true` on success, `false` if a countdown with the same name already exists.
+
+- `boolean createCountdown(CountdownType type, long durationSeconds, Collection<Player> targetPlayers)`
+  - Convenience overload: create an ephemeral countdown of the given type and duration, visible only to the specified players. Returns `true` on success.
 
 - `boolean deleteCountdown(String name)`
   - Delete a configured countdown by name. Returns `true` when deleted.
 
+### Notifications
+
 - `Optional<String> sendNotification(Notification notification)`
-  - Fire a one-shot, ephemeral timed display notification without creating a persistent countdown. The notification runs for its configured duration then disappears automatically — it is never written to `countdowns.yml`. Returns an `Optional` containing the generated internal name on success, or an empty `Optional` on collision.
+  - Fire a one-shot ephemeral timed display notification. The notification runs for its configured duration then is removed automatically  -  it is never written to `countdowns.yml` and does not appear in `/countdown list`. Returns an `Optional` containing the generated internal name on success, or an empty `Optional` on name collision.
+
+- `Optional<String> sendNotification(Notification notification, Collection<Player> players)`
+  - Same as above, but restrict the notification to the specified players. Equivalent to building a `Notification` with `NotificationBuilder.players(players)`.
+
+## Exceptions
 
-Usage example (service lookup):
+Methods return boolean flags or Optional on expected failures (e.g. countdown not found). The API also defines a typed exception hierarchy for use in builders and validation:
+
+| Exception | Package | Description |
+|---|---|---|
+| `EzCountdownException` | `api.exception` | Base class for all EzCountdown API exceptions |
+| `CountdownNotFoundException` | `api.exception` | A countdown name does not exist; carries `getCountdownName()` |
+| `DuplicateCountdownException` | `api.exception` | A countdown with this name already exists; carries `getCountdownName()` |
+| `InvalidConfigurationException` | `api.exception` | Thrown by `NotificationBuilder.build()` when duration is missing or invalid |
+
+## Usage example
 
 ```java
-RegisteredServiceProvider<EzCountdownApi> rsp = Bukkit.getServicesManager().getRegistration(EzCountdownApi.class);
+RegisteredServiceProvider<EzCountdownApi> rsp =
+        Bukkit.getServicesManager().getRegistration(EzCountdownApi.class);
 if (rsp != null) {
     EzCountdownApi api = rsp.getProvider();
     api.createCountdown(myCountdown);
@@ -42,8 +66,15 @@ if (rsp != null) {
 }
 ```
 
-Notes
+Per-player notification:
+
+```java
+List<Player> targets = List.of(player1, player2);
+api.sendNotification(Notification.ofSeconds(30), targets);
+```
+
+## Notes
 
 - Changes made via the API are persisted using the plugin's `countdowns.yml` storage.
-- Methods return boolean flags to indicate success; check plugin logs or events for failure reasons.
-- Countdowns created by `sendNotification` are ephemeral: they run in memory only and are deleted automatically when they end. They are never stored in `countdowns.yml` and do not appear in `/countdown list`.
+- Ephemeral countdowns created by `sendNotification` are held in memory only; they are deleted automatically when they end and are never stored in `countdowns.yml`.
+- `createCountdown(CountdownType, long, Collection<Player>)` creates an ephemeral (in-memory) countdown visible only to the provided players.
diff --git a/docs/api/README.md b/docs/api/README.md
index c52de25..23ef9a5 100644
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -1,6 +1,6 @@
 ---
 title: Developer API
-nav_order: 4
+nav_order: 5
 has_children: true
 ---
 
@@ -8,8 +8,8 @@ has_children: true
 
 ## Prerequisites
 
-- Java 21 (matches Paper API classfile version used by the plugin).
-- Access to the GitHub Packages repository
+- Java 17 or newer.
+- Access to the GitHub Packages repository.
 
 ## Quick start
 
@@ -17,7 +17,7 @@ Follow these steps to add and use the EzCountdown API from your plugin.
 
 ### Installation
 
-1) Add the GitHub Packages repository to your `pom.xml` (replace owner/repo if different):
+1) Add the GitHub Packages repository to your `pom.xml`:
 
 ```xml
 <repositories>
@@ -29,30 +29,34 @@ Follow these steps to add and use the EzCountdown API from your plugin.
 </repositories>
 ```
 
-2) Add the dependency (use the published version tag):
+2) Add the dependency:
 
 ```xml
 <dependency>
-    <groupId>com.skyblockexp</groupId>
+    <groupId>com.github.ez-plugins</groupId>
     <artifactId>ezcountdown</artifactId>
-    <version>1.3.1</version>
+    <version>2.0.0</version>
+    <scope>provided</scope>
 </dependency>
 ```
 
+> Use `<scope>provided</scope>`  -  the plugin jar is already on the server; you do not want to shade it into your own jar.
+
 ## Service lookup
 
 ### Getting the API
 
-Use Bukkit's `ServicesManager` to obtain a reference to the `EzCountdownApi` service. The example below shows the common pattern used in other plugins:
+Use Bukkit's `ServicesManager` to obtain a reference to the `EzCountdownApi` service:
 
 ```java
 import com.skyblockexp.ezcountdown.api.EzCountdownApi;
 import org.bukkit.Bukkit;
 import org.bukkit.plugin.RegisteredServiceProvider;
 
-RegisteredServiceProvider<EzCountdownApi> rsp = Bukkit.getServicesManager().getRegistration(EzCountdownApi.class);
+RegisteredServiceProvider<EzCountdownApi> rsp =
+        Bukkit.getServicesManager().getRegistration(EzCountdownApi.class);
 if (rsp == null) {
-    // EzCountdown not available
+    // EzCountdown is not installed or not loaded yet
     return;
 }
 EzCountdownApi api = rsp.getProvider();
@@ -62,22 +66,13 @@ EzCountdownApi api = rsp.getProvider();
 
 ### Start/Stop
 
-Start an existing countdown by id:
-
 ```java
 api.startCountdown("example-countdown");
-```
-
-Stop a running countdown:
-
-```java
 api.stopCountdown("example-countdown");
 ```
 
 ### Create
 
-Create a countdown using `CountdownBuilder`:
-
 ```java
 import com.skyblockexp.ezcountdown.api.model.Countdown;
 import com.skyblockexp.ezcountdown.api.model.CountdownType;
@@ -104,27 +99,23 @@ api.startCountdown("launch");
 
 ### Inspect
 
-Inspect or list countdowns:
-
 ```java
 Optional<Countdown> maybe = api.getCountdown("launch");
 Collection<Countdown> all = api.listCountdowns();
 ```
 
-### Send a notification
+### Send a notification (global)
 
-`sendNotification` fires a one-shot ephemeral display that runs for the specified duration and then vanishes — no YAML entry is created and no `/countdown list` entry appears.
-
-The simplest usage:
+`sendNotification` fires a one-shot ephemeral display that runs for the specified duration and then vanishes  -  no YAML entry is created and no `/countdown list` entry appears.
 
 ```java
 import com.skyblockexp.ezcountdown.api.model.Notification;
 
-// Show an action bar countdown for 30 seconds (plugin defaults for display).
+// Show an action bar countdown for 30 seconds using plugin defaults.
 api.sendNotification(Notification.ofSeconds(30));
 ```
 
-Use the builder for full control:
+Full builder example:
 
 ```java
 import com.skyblockexp.ezcountdown.api.model.Notification;
@@ -135,28 +126,69 @@ import java.util.EnumSet;
 Notification notif = Notification.builder()
     .duration(Duration.ofMinutes(5))
     .displays(EnumSet.of(DisplayType.ACTION_BAR, DisplayType.BOSS_BAR))
-    .message("{formatted}")               // optional: format message key
-    .startMessage("Event starts soon!")   // optional: broadcast on start
-    .endMessage("Event started!")         // optional: broadcast on end
+    .message("{formatted}")
+    .startMessage("Event starts soon!")
+    .endMessage("Event started!")
     .build();
 
 Optional<String> handle = api.sendNotification(notif);
+
+// Stop early if needed:
+handle.ifPresent(name -> api.stopCountdown(name));
 ```
 
-`sendNotification` returns the generated internal name wrapped in `Optional.of(...)` on success, or `Optional.empty()` on the rare name collision. You can use the name to stop the notification early:
+### Send a notification to specific players
+
+Two ways to send a notification to a subset of online players:
+
+**Option A  -  via the builder:**
 
 ```java
-handle.ifPresent(name -> api.stopCountdown(name));
+import com.skyblockexp.ezcountdown.api.model.Notification;
+import java.util.List;
+
+List<Player> vipPlayers = /* your player collection */;
+
+Notification notif = Notification.builder()
+    .duration(60)
+    .message("VIP event in {formatted}")
+    .players(vipPlayers)   // restrict to these players
+    .build();
+
+api.sendNotification(notif);
 ```
 
-## Javadoc & API reference
+**Option B  -  inline (without a pre-built Notification):**
+
+```java
+api.sendNotification(Notification.ofSeconds(60), vipPlayers);
+```
 
-See the generated API docs for full type and method details: `docs/api/EzCountdownApi.md` and the `model/` and `event/` pages in this folder. If you want, I can add a GitHub Pages workflow to publish hosted Javadoc automatically on release.
+### Exceptions
+
+EzCountdown throws typed exceptions from the `com.skyblockexp.ezcountdown.api.exception` package:
+
+| Exception | When thrown |
+|---|---|
+| `EzCountdownException` | Base class  -  catch this to handle any EzCountdown error |
+| `CountdownNotFoundException` | A countdown name does not exist |
+| `DuplicateCountdownException` | Creating a countdown with an already-used name |
+| `InvalidConfigurationException` | `NotificationBuilder.build()` called without a valid duration |
+
+```java
+import com.skyblockexp.ezcountdown.api.exception.EzCountdownException;
+import com.skyblockexp.ezcountdown.api.exception.CountdownNotFoundException;
+
+try {
+    Notification notif = Notification.builder().build(); // missing duration!
+} catch (InvalidConfigurationException e) {
+    getLogger().warning("Bad notification config: " + e.getMessage());
+}
+```
 
 ## Further reading
 
-- API reference: [docs/api/EzCountdownApi.md](docs/api/EzCountdownApi.md)
-- Events: [docs/api/event](docs/api/event)
-- Models: [docs/api/model](docs/api/model)
-- Notification model: [docs/api/model/Notification.md](docs/api/model/Notification.md)
+- [EzCountdownApi interface](EzCountdownApi)  -  full method list
+- [Events](event/)  -  `CountdownStartEvent`, `CountdownTickEvent`, `CountdownEndEvent`
+- [Models](model/)  -  `Countdown`, `Notification`, `CountdownType`
 
diff --git a/docs/api/model/Notification.md b/docs/api/model/Notification.md
index 8e74609..2c807fe 100644
--- a/docs/api/model/Notification.md
+++ b/docs/api/model/Notification.md
@@ -16,17 +16,18 @@ Notifications are used exclusively with [`EzCountdownApi.sendNotification`](../E
 
 ## Factory methods
 
-- `static Notification ofSeconds(long seconds)` — Create a notification with the given duration (seconds) and all other settings at their defaults.
-- `static Notification of(Duration duration)` — Create a notification from a `java.time.Duration` with all other settings at their defaults.
-- `static NotificationBuilder builder()` — Start a fluent `NotificationBuilder`.
+- `static Notification ofSeconds(long seconds)`  -  Create a notification with the given duration (seconds) and all other settings at their defaults.
+- `static Notification of(Duration duration)`  -  Create a notification from a `java.time.Duration` with all other settings at their defaults.
+- `static NotificationBuilder builder()`  -  Start a fluent `NotificationBuilder`.
 
 ## Accessors
 
-- `long getDurationSeconds()` — Duration of the notification in seconds (always > 0).
-- `EnumSet<DisplayType> getDisplayTypes()` — Which displays are shown. Defaults to `ACTION_BAR`.
-- `String getFormatMessage()` — Format message key. Defaults to `{formatted}`.
-- `String getStartMessage()` — Optional message broadcast when the notification starts. May be `null`.
-- `String getEndMessage()` — Optional message broadcast when the notification ends. May be `null`.
+- `long getDurationSeconds()`  -  Duration of the notification in seconds (always > 0).
+- `EnumSet<DisplayType> getDisplayTypes()`  -  Which displays are shown. Defaults to `ACTION_BAR`.
+- `String getFormatMessage()`  -  Format message key. Defaults to `{formatted}`.
+- `String getStartMessage()`  -  Optional message broadcast when the notification starts. May be `null`.
+- `String getEndMessage()`  -  Optional message broadcast when the notification ends. May be `null`.
+- `Set<UUID> getTargetPlayers()`  -  Set of player UUIDs that will receive this notification. `null` means all online players.
 
 ## Default values
 
@@ -36,6 +37,7 @@ Notifications are used exclusively with [`EzCountdownApi.sendNotification`](../E
 | `formatMessage` | `{formatted}` |
 | `startMessage` | `null` (no broadcast) |
 | `endMessage` | `null` (no broadcast) |
+| `targetPlayers` | `null` (all online players) |
 
 ## NotificationBuilder
 
@@ -51,13 +53,49 @@ Obtained via `Notification.builder()`. All methods return `this` for chaining.
 | `message(String)` | Set the format message; `null` or blank resets to `{formatted}` |
 | `startMessage(String)` | Set the start broadcast; blank treated as `null` |
 | `endMessage(String)` | Set the end broadcast; blank treated as `null` |
-| `build()` | Build and return the `Notification`. Throws `IllegalStateException` if duration was never set or is ≤ 0. |
+| `players(Collection<? extends Player>)` | Restrict the notification to these players; `null` or empty targets all online players |
+| `build()` | Build and return the `Notification`. Throws `InvalidConfigurationException` if duration was never set or is ≤ 0. |
 
 ## Examples
 
 One-liner (action bar for 30 s, plugin defaults):
 
 ```java
+Notification n = Notification.ofSeconds(30);
+api.sendNotification(n);
+```
+
+Full builder  -  action bar + boss bar for 5 minutes:
+
+```java
+Notification n = Notification.builder()
+    .duration(Duration.ofMinutes(5))
+    .displays(EnumSet.of(DisplayType.ACTION_BAR, DisplayType.BOSS_BAR))
+    .message("{formatted}")
+    .startMessage("Event starts soon!")
+    .endMessage("Event started!")
+    .build();
+
+Optional<String> handle = api.sendNotification(n);
+```
+
+Target specific players only:
+
+```java
+List<Player> vipPlayers = getVipPlayers();
+
+Notification n = Notification.builder()
+    .duration(60)
+    .message("VIP reward in {formatted}")
+    .players(vipPlayers)
+    .build();
+
+api.sendNotification(n);
+
+// Or inline:
+api.sendNotification(Notification.ofSeconds(60), vipPlayers);
+```
+
 Notification notif = Notification.ofSeconds(30);
 api.sendNotification(notif);
 ```
diff --git a/docs/commands.md b/docs/commands.md
index b11e136..90cd2d5 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -4,74 +4,133 @@ parent: Server Owners
 nav_order: 1
 ---
 
-# Commands (Quick Reference for Server Owners)
+# Commands
 
-This page lists the most important commands staff will use to manage countdowns. Keep these in a staff guide or paste them into your control panel.
+All commands use the `/countdown` base (aliases: `/ezcountdown`, `/ezcd`).
 
-Core commands
+## Command reference
+
+### `/countdown create`
+
+Create a new countdown. The command syntax depends on the type:
+
+| Type | Syntax | Example |
+|---|---|---|
+| Fixed date | `/countdown create <name> <YYYY-MM-DD> <HH:mm>` | `/countdown create new_year 2026-01-01 00:00` |
+| Duration | `/countdown create <name> duration <time>` | `/countdown create maintenance duration 2h` |
+| Manual | `/countdown create <name> manual <time>` | `/countdown create launch manual 30m` |
+| Recurring (yearly) | `/countdown create <name> recurring <month> <day> <HH:mm>` | `/countdown create xmas recurring 12 25 00:00` |
+
+Duration values accept `h` (hours), `m` (minutes), `s` (seconds), and combinations like `1h30m`.
+
+**Clock-aligned recurring flags** (append to `create recurring`):
+
+| Flag | Description | Example value |
+|---|---|---|
+| `--align-to-clock` | Enable clock-aligned repeats | _(no value)_ |
+| `--align-interval <value>` | Alignment interval | `2h`, `1d`, `30m` |
+| `--timezone <ZoneId>` | IANA timezone | `UTC`, `Europe/London` |
+| `--missed-run-policy <policy>` | Handle missed runs | `SKIP`, `RUN_SINGLE`, `RUN_ALL` |
+
+Example  -  announce every 2 hours, UTC:
+
+```
+/countdown create announce recurring 0 0 00:00 --align-to-clock --align-interval 2h --timezone UTC --missed-run-policy SKIP
+```
+
+---
+
+### `/countdown start` / `/countdown stop`
 
 ```
-/countdown create <name> <date|duration|manual|recurring>
 /countdown start <name>
 /countdown stop <name>
+```
+
+Start or stop a countdown by name. `duration` countdowns start automatically when created; use `manual` if you want to control the start time.
+
+---
+
+### `/countdown delete`
+
+```
 /countdown delete <name>
+```
+
+Remove a countdown permanently from `countdowns.yml`. This cannot be undone; use `/countdown stop` if you only want to pause it.
+
+---
+
+### `/countdown list`
+
+```
 /countdown list
+```
+
+Show all configured countdowns and whether they are currently running.
+
+---
+
+### `/countdown info`
+
+```
 /countdown info <name>
+```
+
+Show full details for a countdown: type, target/duration, display types, enabled commands, and current state.
+
+---
+
+### `/countdown reload`
+
+```
 /countdown reload
 ```
 
- - `create` - Create a countdown. Types:
-  - `date` - Fixed target: `YYYY-MM-DD HH:mm` (example: `2026-01-01 00:00`).
-  - `duration` - Run for a duration (examples: `2h`, `30m`, `1h30m`). Starts immediately unless defaults say otherwise.
-  - `manual` - Duration-based but stays stopped until `start`.
-  - `recurring` - Yearly event: provide `month day time` (e.g. `12 31 23:59`).
+Reload `config.yml`, `messages.yml`, and `countdowns.yml` without restarting the server. Running countdowns resume from where they left off.
 
-    New flags for `create recurring` (clock-aligned schedules)
+---
 
-    - `--align-to-clock` - enable clock alignment for recurring schedules.
-    - `--align-interval <value>` - alignment interval (e.g. `2h`, `1d`, `30m`).
-    - `--timezone <ZoneId>` - IANA timezone to use (e.g. `UTC`, `Europe/London`).
-    - `--missed-run-policy <SKIP|RUN_SINGLE|RUN_ALL>` - how to handle missed runs when the server was down.
+### `/countdown gui`
 
- - `start` / `stop` - Start or stop a running countdown by name.
- - `delete` - Remove a countdown from `countdowns.yml` (use `reload` to apply).
- - `list` - Show all configured countdowns and whether they are running.
- - `info` - Show details for a specific countdown (type, target, displays, commands).
- - `reload` - Reloads `config.yml`, `messages.yml`, and `countdowns.yml` without restarting the server.
+```
+/countdown gui
+/countdown gui <name>
+```
+
+Open the in-game visual editor. With no argument, shows a list of all countdowns. Pass a name to edit that countdown directly. Requires `ezcountdown.admin`.
+
+---
 
-Location management
+### Location management
 
 ```
 /ezcd location add <name>
 /ezcd location delete <name>
 ```
 
- - `location add` saves the executor's current position to `locations.yml` under the given name.
- - `location delete` removes a named location.
- - Permissions: `ezcountdown.location.add` and `ezcountdown.location.delete`.
+Save or remove a named teleport location. Use `location add` while standing at the target location; the plugin records your position, world, and facing direction. Named locations are referenced in `countdowns.yml` under `teleport.start` and `teleport.end`.
 
-Examples
+Requires `ezcountdown.location.add` / `ezcountdown.location.delete`.
 
-```
-/countdown create new_year 2026-01-01 00:00
-/countdown create maintenance duration 2h
-/countdown create festival recurring 12 31 23:59
-/countdown create announce recurring 0 0 00:00 --align-to-clock --align-interval 2h --timezone UTC --missed-run-policy SKIP
-/ezcd location add spawn
-```
+---
+
+## Permissions summary
 
-Practical tips for server owners
+| Node | Default | What it allows |
+|---|---|---|
+| `ezcountdown.use` | `true` (all players) | `/countdown list` and `/countdown info` |
+| `ezcountdown.admin` | `op` | Create, start, stop, delete, reload, GUI |
+| `ezcountdown.location.add` | `op` | Save named teleport locations |
+| `ezcountdown.location.delete` | `op` | Remove named teleport locations |
 
-- After creating a countdown you will often want to edit `countdowns.yml` to configure displays, custom messages, end commands, and teleport behaviour.
-- Use `reload` after editing YAML files to apply changes immediately.
-- Keep a short list of commonly used countdown names (for holidays or events) so staff can quickly create them.
- - Test `commands_on_end` in a non-production environment first - commands run as console.
+See [Permissions](permissions) for recommended group assignments.
 
-Permissions summary
+---
 
- - `ezcountdown.admin` - Full management (create, start, stop, delete, reload).
- - `ezcountdown.use` - View/list countdowns and run `info`.
- - `ezcountdown.location.add` / `ezcountdown.location.delete` - Manage named teleport locations.
+## Tips
 
-If you'd like, I can add a one-line `staff-help.txt` snippet you can paste into your control panel or staff Discord.
+- After creating a countdown, edit `plugins/EzCountdown/countdowns.yml` to configure display types, custom messages, end commands, and teleport behaviour  -  then run `/countdown reload`.
+- Test `commands_on_end` on a staging server first; they run as console with full permissions.
+- Use `manual` type for countdown events you want to arm in advance and trigger at the right moment.
 
diff --git a/docs/configuration.md b/docs/configuration.md
index 834b499..89f9a18 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -4,131 +4,166 @@ parent: Server Owners
 nav_order: 2
 ---
 
-# Configuration (Server Owner Notes)
+# Configuration
 
-Configuration files are in the plugin data folder and are reloaded with `/countdown reload` or on server restart.
+Configuration files live in `plugins/EzCountdown/` and are reloaded with `/countdown reload` or on server restart.
 
-Key files
+## Files overview
 
- - `config.yml` - Global plugin settings and sensible defaults (update intervals, default displays, compatibility overrides).
- - `messages.yml` - All user-facing text; supports MiniMessage for colors and simple HTML-like formatting.
- - `countdowns.yml` - Per-countdown definitions: type, date/duration, enabled displays, messages, end commands, teleport actions.
- - `locations.yml` - Named teleport locations used by countdowns (world, x, y, z, yaw, pitch).
+| File | Purpose |
+|---|---|
+| `config.yml` | Global plugin settings: update intervals, default displays, time format, compatibility overrides |
+| `messages.yml` | All user-facing text; supports MiniMessage for colors and formatting |
+| `countdowns.yml` | Per-countdown definitions: type, date/duration, display types, messages, end commands, teleport |
+| `locations.yml` | Named teleport locations (world, x, y, z, yaw, pitch) |
 
-Important settings to review
-
- - `update-interval` - How often (seconds) countdowns update; lower = smoother but more CPU.
- - `default-displays` - Controls which display types are enabled by default (actionbar, bossbar, chat, title, scoreboard).
- - `display-overrides.force-enable.<display>` - Force-enable a display type when the server lacks native support (use with caution).
- - `placeholder-support` - If enabled, PlaceholderAPI placeholders are available. Example placeholders: `%ezcountdown_<name>_formatted%`.
-
-Recurring alignment options
+---
 
-- `align_to_clock` - boolean, when `true` enables clock-aligned repeats (default `false`).
-- `align_interval` - duration string like `2h`, `1d`, or `30m` describing the alignment interval used when `align_to_clock: true`.
-- `timezone` / `zone` - an IANA timezone identifier (e.g. `UTC`, `Europe/London`) used to resolve calendar times; `timezone` is an alias for the existing `zone` key.
-- `missed_run_policy` - controls behavior when the server was down for scheduled occurrences. Values: `SKIP` (default), `RUN_SINGLE`, `RUN_ALL`.
+## `config.yml`  -  key settings
 
-Example `countdowns.yml` entry
+| Key | Description |
+|---|---|
+| `update-interval` | How often (in seconds) countdowns tick. Lower = smoother display but more CPU. |
+| `default-displays` | Display types enabled by default for new countdowns (`actionbar`, `bossbar`, `chat`, `title`, `scoreboard`, `dialog`). |
+| `display-overrides.force-enable.<display>` | Force-enable a display type regardless of runtime support (use with caution). |
+| `placeholder-support` | Enable PlaceholderAPI integration. Requires [PlaceholderAPI](https://github.com/PlaceholderAPI/PlaceholderAPI) to be installed. |
 
-```yaml
-countdowns:
-  new_year:
-    type: date
-    date: "2026-01-01 00:00"
-    displays:
-      - actionbar
-      - bossbar
-    message: "New Year in %ezcountdown_new_year_formatted%"
-    commands_on_end:
-      - "broadcast &6Happy New Year!"
-    teleport:
-      start: spawn
-      end: arena
-```
+---
 
-**Time Format**
+## Time format
 
-The `{formatted}` placeholder (and `%ezcountdown_<name>_formatted%`) is driven by two settings under `display.time-format` in `config.yml`:
+The `{formatted}` placeholder (and `%ezcountdown_<name>_formatted%`) is controlled by `display.time-format` in `config.yml`:
 
 | Key | Type | Default | Description |
-|-----|------|---------|-------------|
+|---|---|---|---|
 | `display.time-format.pattern` | string | `"{days}d {hours}h {minutes}m {seconds}s"` | Token layout. Supported tokens: `{days}`, `{hours}`, `{minutes}`, `{seconds}`. |
-| `display.time-format.hide-leading-zeros` | boolean | `true` | When `true`, leading space-delimited segments whose unit value is `0` are omitted. At least the last segment is always shown. |
+| `display.time-format.hide-leading-zeros` | boolean | `true` | When `true`, leading zero-valued segments are omitted. The last segment is always shown. |
 
 Examples with `hide-leading-zeros: true`:
 
 | Remaining | Output |
-|-----------|--------|
+|---|---|
 | 2d 5h 3m 7s | `2d 5h 3m 7s` |
 | 0d 2h 5m 3s | `2h 5m 3s` |
 | 0d 0h 0m 45s | `45s` |
 | 0d 0h 0m 0s | `0s` |
 
-These settings are reloaded with `/countdown reload`.
+---
+
+## Boss bar customization
 
-**Boss Bar Customization**
+Set per-countdown inside `countdowns.yml` under `display.bossbar`:
 
-- `display.bossbar.color`: (optional) A `BarColor` name used for the countdown's boss bar. Valid values include `BLUE`, `RED`, `GREEN`, `YELLOW`, `PINK`, `PURPLE`, `WHITE` (matching Bukkit's `BarColor` enum). Default: `BLUE`.
-- `display.bossbar.style`: (optional) A `BarStyle` name used for the boss bar's segment style. Valid values include `SOLID`, `SEGMENTED_6`, `SEGMENTED_10`, `SEGMENTED_12`, `SEGMENTED_20` (matching Bukkit's `BarStyle` enum). Default: `SOLID`.
+| Key | Type | Default | Valid values |
+|---|---|---|---|
+| `color` | string | `BLUE` | `BLUE`, `RED`, `GREEN`, `YELLOW`, `PINK`, `PURPLE`, `WHITE` |
+| `style` | string | `SOLID` | `SOLID`, `SEGMENTED_6`, `SEGMENTED_10`, `SEGMENTED_12`, `SEGMENTED_20` |
 
-Example with boss bar options:
+**Compatibility:** boss bar requires Minecraft 1.9+. On older servers the plugin silently skips the boss bar display.
+
+---
+
+## Clock-aligned recurring options
+
+Set these per-countdown in `countdowns.yml`:
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `align_to_clock` | boolean | `false` | Enable clock-aligned repeats |
+| `align_interval` | string |  -  | Alignment interval (e.g. `2h`, `1d`, `30m`) |
+| `timezone` | string | server default | IANA timezone identifier (e.g. `UTC`, `Europe/London`) |
+| `missed_run_policy` | string | `SKIP` | `SKIP`, `RUN_SINGLE`, or `RUN_ALL` |
+
+---
+
+## Translation tokens
+
+Reference `messages.yml` keys from inside `countdowns.yml` using `{translate:key.path}`:
 
 ```yaml
+# messages.yml
+sales:
+  format: "<white>Sale</white> <gray>ends in</gray> <yellow>{formatted}</yellow>"
+  start: "<green>Sale started!</green>"
+  end: "<red>Sale ended.</red>"
+
+# countdowns.yml
 countdowns:
-  holiday_sale:
-    type: FIXED_DATE
-    target: "2026-12-20 12:00"
-    display:
-      types: [BOSS_BAR, ACTION_BAR]
-      update-interval: 1
-      bossbar:
-        color: RED
-        style: SEGMENTED_10
+  my_sale:
     messages:
       format: "{translate:sales.format}"
       start: "{translate:sales.start}"
       end: "{translate:sales.end}"
 ```
 
-Clock-aligned recurring example
+Translation tokens are resolved before MiniMessage serialization and before runtime placeholders like `{formatted}`, so translated text may include both. Nested `{translate:...}` tokens are resolved up to 3 levels deep. Missing keys are replaced with an empty string and logged as a warning.
+
+---
+
+## Full `countdowns.yml` example
 
 ```yaml
 countdowns:
-  two_hour_utc:
+  new_year:
+    type: FIXED_DATE
+    target: "2026-01-01 00:00"
+    timezone: "UTC"
+    display:
+      types: [ACTION_BAR, BOSS_BAR]
+      update-interval: 1
+      bossbar:
+        color: YELLOW
+        style: SOLID
+    messages:
+      format: "New Year in {formatted}"
+      start: "Countdown started!"
+      end: "Happy New Year!"
+    commands_on_end:
+      - "broadcast &6Happy New Year!"
+    teleport:
+      end: spawn
+
+  two_hour_announce:
     type: RECURRING
     align_to_clock: true
     align_interval: "2h"
     timezone: "UTC"
-    # (other recurring keys like recurring.month/day/time are optional when using align_interval)
-    running: true
-```
-
-Server-owner tips
-
-- Always back up `countdowns.yml` before large edits.
-- Use `messages.yml` to localize or brand the messages; test MiniMessage outputs on a test server.
- - Use `messages.yml` to localize or brand the messages; test MiniMessage outputs on a test server.
- - Translation variables: you can reference message keys from `messages.yml` directly inside `countdowns.yml` (or other config strings) using the `{translate:key.path}` token. Example:
+    missed_run_policy: SKIP
+    display:
+      types: [CHAT]
+    messages:
+      format: "Next reset in {formatted}"
 
-```yaml
-# messages.yml
-example:
-  format: "<white>Example Event</white> <gray>starts in</gray> <yellow>{formatted}</yellow>"
+  maintenance:
+    type: DURATION
+    duration: "2h"
+    display:
+      types: [ACTION_BAR, TITLE]
+    messages:
+      format: "Maintenance in {formatted}"
+      end: "Maintenance complete!"
+    commands_on_end:
+      - "broadcast &aServer is back online!"
 
-# countdowns.yml
-countdowns:
-  my_event:
+  holiday_sale:
+    type: FIXED_DATE
+    target: "2026-12-20 12:00"
+    display:
+      types: [BOSS_BAR, ACTION_BAR]
+      bossbar:
+        color: RED
+        style: SEGMENTED_10
     messages:
-      format: "{translate:example.format}"
+      format: "{translate:sales.format}"
+      start: "{translate:sales.start}"
+      end: "{translate:sales.end}"
 ```
 
-Behavior notes:
+---
 
- - Missing keys: if a `{translate:...}` key is not present in `messages.yml`, the plugin will log a warning and replace the token with an empty string in the output.
- - Nesting: translated values may themselves contain `{translate:...}` tokens; nesting is resolved up to 3 levels to avoid infinite loops.
- - Ordering: translation resolution happens before runtime placeholder replacement (for example `{name}`, `{formatted}`) and before MiniMessage serialization, so translated text can include placeholders and MiniMessage markup.
- - `commands_on_end` run as console - avoid dangerous or untested commands in production.
-- Use `display-overrides.force-enable` only when you understand the compatibility risks; the plugin includes runtime fallbacks but some features may not work correctly on older servers.
+## Server-owner tips
 
-Need a sample `countdowns.yml` with several pre-made events? I can add one tailored to holidays and routine maintenance.
+- Back up `countdowns.yml` before large edits  -  a YAML syntax error will prevent the file from loading.
+- Use `messages.yml` to centralize all player-visible text; test MiniMessage formatting on a staging server.
+- Use `display-overrides.force-enable` only when you understand the compatibility risks. The plugin already includes runtime fallbacks for most display types.
+- `commands_on_end` run as console with full operator permissions  -  keep the list minimal and review it regularly.
diff --git a/docs/feature/index.md b/docs/feature/index.md
index f5ca916..4409185 100644
--- a/docs/feature/index.md
+++ b/docs/feature/index.md
@@ -1,22 +1,33 @@
 ---
 title: Features
-nav_order: 3
+nav_order: 4
 has_children: true
 ---
 
 # Features
 
-Detailed documentation for each feature in EzCountdown. Whether you are configuring a countdown for the first time or tuning advanced behavior, the pages in this section have complete YAML references and examples.
+Detailed documentation for each feature in EzCountdown.
 
 ## What's in this section
 
 | Page | Description |
 |---|---|
 | [Countdown Types](countdown_types) | Fixed date, duration, manual, recurring, and clock-aligned modes |
-| [Display Types](display/) | Action bar, boss bar, title, chat, and scoreboard |
+| [Display Types](display/) | Action bar, boss bar, title, chat, scoreboard, and dialog (Paper 1.21.7+) |
 | [Firework Shows](firework_shows) | Trigger firework displays on countdown start or end |
 | [GUI](gui) | In-game visual editor for managing countdowns |
 | [Placeholders](placeholders) | PlaceholderAPI placeholders for use in other plugins |
 | [Teleport](teleport) | Teleport players to named locations on start or end |
 | [Timezones](timezones) | IANA timezone reference for clock-aligned recurring countdowns |
 | [Discord Integration](discord_integration) | Post webhook notifications to Discord |
+
+## Compatibility quick reference
+
+| Feature | Min. Minecraft version |
+|---|---|
+| Core (action bar, chat, title) | Paper/Spigot 1.18 |
+| Boss bar | Paper/Spigot 1.18 (Bukkit boss bar API, available since MC 1.9) |
+| Scoreboard | Paper/Spigot 1.18 |
+| Dialog display | Paper 1.21.7+  -  gracefully skipped on older builds |
+| PlaceholderAPI | Any 1.18+ build with PlaceholderAPI installed |
+| Clock-aligned recurring | Paper/Spigot 1.18 |
diff --git a/docs/index.md b/docs/index.md
index 11bd0f2..52ccaaa 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -10,19 +10,20 @@ nav_order: 1
 [![Release](https://img.shields.io/github/v/release/ez-plugins/EzCountdown)](https://github.com/ez-plugins/EzCountdown/releases)
 [![License](https://img.shields.io/github/license/ez-plugins/EzCountdown)](https://github.com/ez-plugins/EzCountdown/blob/main/LICENSE)
 
-A feature-rich countdown plugin for Paper/Spigot servers. Create countdowns for events, launches, maintenance windows, and more - all configurable from YAML with no coding required.
+A feature-rich countdown plugin for Paper/Spigot servers. Create countdowns for events, launches, maintenance windows, and more  -  all configurable from YAML with no coding required.
 
 ## Features
 
-- **Four countdown modes** - fixed date, duration, manual, and recurring (yearly or clock-aligned).
-- **Five display types** - action bar, boss bar, title, chat, and scoreboard.
-- **PlaceholderAPI support** - expose countdown values to scoreboards, holograms, and other plugins.
-- **Discord webhooks** - post start/end notifications to a Discord channel.
-- **In-game GUI** - manage countdowns visually without editing YAML.
-- **Firework shows** - trigger configurable firework displays on start or end.
-- **Teleport actions** - move all online players to a named location when a countdown starts or ends.
-- **Console commands on end** - run any command when a countdown completes.
-- **Developer API** - create, start, stop, and listen to countdown events from other plugins.
+- **Four countdown modes**  -  fixed date, duration, manual, and recurring (yearly or clock-aligned).
+- **Six display types**  -  action bar, boss bar, title, chat, scoreboard, and dialog (Paper 1.21.7+).
+- **Per-player visibility**  -  restrict any countdown or notification to specific permission nodes or a target-player set.
+- **PlaceholderAPI support**  -  expose countdown values to scoreboards, holograms, and other plugins.
+- **Discord webhooks**  -  post start/end notifications to a Discord channel.
+- **In-game GUI**  -  manage countdowns visually without editing YAML.
+- **Firework shows**  -  trigger configurable firework displays on start or end.
+- **Teleport actions**  -  move all online players to a named location when a countdown starts or ends.
+- **Console commands on end**  -  run any command when a countdown completes.
+- **Developer API**  -  create, start, stop, listen to countdown events, and send per-player notifications from other plugins.
 
 ## Quick Start
 
@@ -41,16 +42,24 @@ A feature-rich countdown plugin for Paper/Spigot servers. Create countdowns for
    /countdown reload
    ```
 
+## Compatibility
+
+| Requirement | Minimum version |
+|---|---|
+| Minecraft / server software | Paper or Spigot **1.18** (or any fork) |
+| Java | **17** |
+| Dialog display | Paper **1.21.7** (gracefully skipped on older builds) |
+| PlaceholderAPI | Any compatible build (soft dependency) |
+
+> **Server owners**: download the release jar from [GitHub Releases](https://github.com/ez-plugins/EzCountdown/releases). Java 17 and Paper/Spigot 1.18 or newer are all you need.
+>
+> **Plugin developers**: add EzCountdown as a `provided` dependency and compile your plugin against Java 17 or newer.
+
 ## Documentation
 
 | Section | Description |
 |---|---|
-| [Server Owners](server-owners) | Getting started: install, commands, permissions, configuration |
+| [Tutorials](tutorials/) | Step-by-step guides: create your first countdown, set up recurring announcements |
+| [Server Owners](server-owners) | Install, commands, permissions, configuration reference |
 | [Features](feature/) | Countdown types, displays, Discord, fireworks, teleports, and more |
 | [Developer API](api/) | Java API, events, and models for plugin developers |
-
-## Installation
-
-Download the latest release from [GitHub Releases](https://github.com/ez-plugins/EzCountdown/releases) and place the jar in your server's `plugins/` folder. Requires **Paper 1.20+** and **Java 21+**.
-
-For dependency access in your own plugin, see the [Developer API](api/) page.
diff --git a/docs/permissions.md b/docs/permissions.md
index 2b1dfe1..02e8c6c 100644
--- a/docs/permissions.md
+++ b/docs/permissions.md
@@ -4,28 +4,44 @@ parent: Server Owners
 nav_order: 3
 ---
 
-# Permissions (Who should have which node)
+# Permissions
 
 Use a permissions plugin (LuckPerms recommended) to assign these nodes to groups rather than individuals.
 
- Core nodes
- 
- - `ezcountdown.use` - View countdowns and run informational commands (`/countdown list`, `/countdown info`).
- - `ezcountdown.admin` - Full management: create, start, stop, delete, and `reload`.
- - `ezcountdown.location.add` - Add a named teleport location with `/ezcd location add`.
- - `ezcountdown.location.delete` - Remove a named teleport location with `/ezcd location delete`.
+## Permission nodes
 
-Recommended assignment
+| Node | Default | Description |
+|---|---|---|
+| `ezcountdown.use` | `true` | View countdowns: `/countdown list`, `/countdown info` |
+| `ezcountdown.admin` | `op` | Full management: create, start, stop, delete, reload, GUI |
+| `ezcountdown.location.add` | `op` | Add named teleport locations with `/ezcd location add` |
+| `ezcountdown.location.delete` | `op` | Remove named teleport locations with `/ezcd location delete` |
 
-- Admins/Managers: `ezcountdown.admin`.
-- Moderators/Trusted Staff: `ezcountdown.use` (+ `location.*` if they manage spawn/teleports).
-- Regular players: no permissions by default unless you want players to query countdowns.
+## Recommended group assignments
 
-Security notes for server owners
+| Group | Suggested nodes |
+|---|---|
+| Admins / Server Managers | `ezcountdown.admin` (includes all operations) |
+| Moderators / Trusted Staff | `ezcountdown.use` + `ezcountdown.location.add` if they manage spawn/teleports |
+| Regular players | `ezcountdown.use` (granted by default) |
 
-- `ezcountdown.admin` allows editing and running end-of-countdown console commands - do not grant this to the general staff group.
-- Use groups and inheritance in your permissions plugin to avoid mistakes.
-- Audit `countdowns.yml` regularly if staff can edit files directly; consider limiting filesystem access to only a few trusted admins.
+## LuckPerms example
 
-Want me to output a sample LuckPerms commands snippet to create groups and assign these nodes? I can add that next.
+```
+# Grant admin to your admin group
+lp group admin permission set ezcountdown.admin true
+
+# Grant view-only to moderators
+lp group moderator permission set ezcountdown.use true
+
+# Grant location management to a dedicated events group
+lp group events permission set ezcountdown.location.add true
+lp group events permission set ezcountdown.location.delete true
+```
+
+## Security notes
+
+- `ezcountdown.admin` allows editing countdowns and running `commands_on_end` entries as console  -  do not grant this to untrusted groups.
+- Keep `commands_on_end` entries in `countdowns.yml` to a minimum and audit them regularly if staff members have write access to plugin configuration files.
+- Use groups and inheritance in your permissions plugin rather than assigning nodes directly to players.
 
diff --git a/docs/server-owners.md b/docs/server-owners.md
index 4dcfcdb..c8e96d2 100644
--- a/docs/server-owners.md
+++ b/docs/server-owners.md
@@ -1,12 +1,20 @@
 ---
 title: Server Owners
-nav_order: 2
+nav_order: 3
 has_children: true
 ---
 
 # Server Owners
 
-This section covers everything you need to run EzCountdown on your server without writing any code. Start here if you are a server admin or operator.
+This section covers everything you need to run EzCountdown on your server without writing any code.
+
+## Installation
+
+1. Download the latest jar from [GitHub Releases](https://github.com/ez-plugins/EzCountdown/releases).
+2. Place the jar in your server's `plugins/` folder.
+3. Start or restart the server. Configuration files are created automatically inside `plugins/EzCountdown/`.
+
+**Requirements:** Paper or Spigot 1.18 (or any fork) and Java 17.
 
 ## What's in this section
 
@@ -15,3 +23,7 @@ This section covers everything you need to run EzCountdown on your server withou
 | [Commands](commands) | Every `/countdown` and `/ezcd` command with examples |
 | [Configuration](configuration) | Config files, YAML keys, and tips for customizing behavior |
 | [Permissions](permissions) | Permission nodes and recommended group assignments |
+
+## New to EzCountdown?
+
+Start with the [Tutorials](../tutorials/) for step-by-step guides on creating your first countdown and setting up recurring announcements.
diff --git a/docs/tutorials/first-countdown.md b/docs/tutorials/first-countdown.md
new file mode 100644
index 0000000..104bbb5
--- /dev/null
+++ b/docs/tutorials/first-countdown.md
@@ -0,0 +1,129 @@
+---
+title: Your First Countdown
+parent: Tutorials
+nav_order: 1
+---
+
+# Tutorial: Your First Countdown
+
+In this tutorial you will create a fixed-date countdown that counts down to New Year 2027 and displays on the action bar and boss bar.
+
+**Time to complete:** about 5 minutes.
+
+---
+
+## Step 1  -  Install the plugin
+
+1. Download `EzCountdown.jar` from [GitHub Releases](https://github.com/ez-plugins/EzCountdown/releases).
+2. Place the jar in your server's `plugins/` folder.
+3. Start (or restart) the server. You will see a message in the console confirming the plugin loaded.
+4. Check that the data folder was created:
+
+   ```
+   plugins/EzCountdown/
+   ├── config.yml
+   ├── countdowns.yml
+   ├── messages.yml
+   └── locations.yml
+   ```
+
+---
+
+## Step 2  -  Create the countdown
+
+In-game (as an operator), run:
+
+```
+/countdown create new_year 2027-01-01 00:00
+```
+
+The countdown is created and starts immediately. You should see a brief action bar message.
+
+> **Tip:** names must be unique and contain no spaces. Use underscores (`_`) to separate words.
+
+---
+
+## Step 3  -  Check it works
+
+```
+/countdown info new_year
+```
+
+The output shows the type (`FIXED_DATE`), the target (`2027-01-01 00:00`), and the running state.
+
+```
+/countdown list
+```
+
+The countdown should appear as running.
+
+---
+
+## Step 4  -  Customise the display
+
+Open `plugins/EzCountdown/countdowns.yml` in a text editor. You will see an entry similar to:
+
+```yaml
+countdowns:
+  new_year:
+    type: FIXED_DATE
+    target: "2027-01-01 00:00"
+    ...
+```
+
+Replace the entry with the following to enable both the action bar and a coloured boss bar, and add custom messages:
+
+```yaml
+countdowns:
+  new_year:
+    type: FIXED_DATE
+    target: "2027-01-01 00:00"
+    timezone: "UTC"
+    display:
+      types:
+        - ACTION_BAR
+        - BOSS_BAR
+      update-interval: 1
+      bossbar:
+        color: YELLOW
+        style: SOLID
+    messages:
+      format: "<yellow>New Year</yellow> <gray>in</gray> <white>{formatted}</white>"
+      start: "<green>New Year countdown started!</green>"
+      end: "<gold>Happy New Year!</gold>"
+    commands_on_end:
+      - "broadcast Happy New Year!"
+```
+
+---
+
+## Step 5  -  Reload
+
+Apply the changes without restarting the server:
+
+```
+/countdown reload
+```
+
+The countdown now shows on the action bar and boss bar with the custom messages.
+
+---
+
+## Step 6  -  Stop and restart
+
+You can pause and resume the countdown at any time:
+
+```
+/countdown stop new_year
+/countdown start new_year
+```
+
+Stopping a `FIXED_DATE` countdown and starting it again will resume the timer from where it left off (the target date does not change).
+
+---
+
+## Next steps
+
+- Add the countdown to a [permission node](../permissions) so only certain players see it.
+- Learn how to set up a [recurring announcement](recurring-countdown) that fires every few hours.
+- Explore [display types](../feature/display/) for scoreboard, title, and dialog displays.
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
new file mode 100644
index 0000000..27aeb1a
--- /dev/null
+++ b/docs/tutorials/index.md
@@ -0,0 +1,17 @@
+---
+title: Tutorials
+nav_order: 2
+has_children: true
+---
+
+# Tutorials
+
+Step-by-step guides for setting up common countdown scenarios. No coding required  -  these tutorials use only in-game commands and YAML configuration.
+
+## Available tutorials
+
+| Tutorial | What you will build |
+|---|---|
+| [Your First Countdown](first-countdown) | A fixed-date countdown displayed on the action bar and boss bar |
+| [Recurring Announcements](recurring-countdown) | A clock-aligned recurring message that fires every two hours |
+| [Per-Player Notifications (Developer)](notifications) | An API-driven per-player notification for plugin developers |
diff --git a/docs/tutorials/notifications.md b/docs/tutorials/notifications.md
new file mode 100644
index 0000000..e3d962b
--- /dev/null
+++ b/docs/tutorials/notifications.md
@@ -0,0 +1,139 @@
+---
+title: Per-Player Notifications (Developer)
+parent: Tutorials
+nav_order: 3
+---
+
+# Tutorial: Per-Player Notifications
+
+This tutorial is aimed at **plugin developers**. You will use the EzCountdown Java API to send a timed notification to a specific subset of online players  -  for example, a VIP countdown shown only to players with a particular rank.
+
+**Prerequisites:** You have added the EzCountdown API as a `provided` dependency. See the [Developer API quick start](../api/) for dependency setup instructions.
+
+---
+
+## What is a notification?
+
+A `Notification` is an ephemeral (temporary) countdown that:
+- Runs in memory only  -  not saved to `countdowns.yml`.
+- Disappears automatically when its duration expires.
+- Can be restricted to specific players.
+
+---
+
+## Step 1  -  Get the API
+
+In your plugin's `onEnable` or wherever you need it:
+
+```java
+import com.skyblockexp.ezcountdown.api.EzCountdownApi;
+import org.bukkit.Bukkit;
+import org.bukkit.plugin.RegisteredServiceProvider;
+
+RegisteredServiceProvider<EzCountdownApi> rsp =
+        Bukkit.getServicesManager().getRegistration(EzCountdownApi.class);
+if (rsp == null) {
+    getLogger().warning("EzCountdown not found  -  notifications disabled.");
+    return;
+}
+EzCountdownApi ezApi = rsp.getProvider();
+```
+
+---
+
+## Step 2  -  Send a global notification
+
+The simplest case  -  show an action bar countdown to every online player for 60 seconds:
+
+```java
+import com.skyblockexp.ezcountdown.api.model.Notification;
+
+ezApi.sendNotification(Notification.ofSeconds(60));
+```
+
+---
+
+## Step 3  -  Send to specific players
+
+Collect the players you want to target and pass them to `sendNotification`:
+
+```java
+import java.util.List;
+import org.bukkit.entity.Player;
+
+// Example: notify all players who have the VIP permission
+List<Player> vipPlayers = Bukkit.getOnlinePlayers().stream()
+        .filter(p -> p.hasPermission("myserver.vip"))
+        .toList();
+
+ezApi.sendNotification(Notification.ofSeconds(60), vipPlayers);
+```
+
+Only the players in `vipPlayers` will see the action bar notification. All other online players are unaffected.
+
+---
+
+## Step 4  -  Build a richer notification
+
+Use `NotificationBuilder` to customise the display type, messages, and target players in one go:
+
+```java
+import com.skyblockexp.ezcountdown.api.model.Notification;
+import com.skyblockexp.ezcountdown.display.DisplayType;
+import java.time.Duration;
+import java.util.EnumSet;
+
+Notification notif = Notification.builder()
+    .duration(Duration.ofMinutes(5))
+    .displays(EnumSet.of(DisplayType.ACTION_BAR, DisplayType.BOSS_BAR))
+    .message("<gold>VIP event</gold> <gray>in</gray> <white>{formatted}</white>")
+    .startMessage("<gold>VIP event countdown started!</gold>")
+    .endMessage("<gold>VIP event is starting now!</gold>")
+    .players(vipPlayers)   // restrict to VIP players
+    .build();
+
+Optional<String> handle = ezApi.sendNotification(notif);
+
+// You can stop the notification early using the returned handle:
+handle.ifPresent(name -> ezApi.stopCountdown(name));
+```
+
+---
+
+## Step 5  -  Handle the exception
+
+`NotificationBuilder.build()` throws `InvalidConfigurationException` (a subclass of `EzCountdownException`) if the duration was not set or is not positive:
+
+```java
+import com.skyblockexp.ezcountdown.api.exception.InvalidConfigurationException;
+
+try {
+    Notification notif = Notification.builder()
+        // forgot .duration(...)
+        .message("{formatted}")
+        .build();  // throws here
+} catch (InvalidConfigurationException e) {
+    getLogger().severe("Bad notification config: " + e.getMessage());
+}
+```
+
+---
+
+## Display type compatibility
+
+| Display type | Min. MC version | Notes |
+|---|---|---|
+| `ACTION_BAR` | Paper/Spigot 1.18 | Falls back to chat on older builds |
+| `BOSS_BAR` | Paper/Spigot 1.18 | |
+| `TITLE` | Paper/Spigot 1.18 | Falls back to action bar then chat |
+| `CHAT` | All supported versions | Most compatible |
+| `SCOREBOARD` | Paper/Spigot 1.18 | |
+| `DIALOG` | Paper 1.21.7+ | Skipped on older builds |
+
+---
+
+## Next steps
+
+- Listen to [`CountdownEndEvent`](../api/event/CountdownEndEvent) to run logic when a notification ends.
+- See the full [`EzCountdownApi`](../api/EzCountdownApi) reference for all available methods.
+- Explore the [`Notification` model](../api/model/Notification) for the complete builder API.
diff --git a/docs/tutorials/recurring-countdown.md b/docs/tutorials/recurring-countdown.md
new file mode 100644
index 0000000..d207e65
--- /dev/null
+++ b/docs/tutorials/recurring-countdown.md
@@ -0,0 +1,107 @@
+---
+title: Recurring Announcements
+parent: Tutorials
+nav_order: 2
+---
+
+# Tutorial: Recurring Announcements
+
+In this tutorial you will create a countdown that resets automatically every two hours and shows a chat message warning players about an upcoming server event. This uses the **clock-aligned recurring** mode.
+
+**Time to complete:** about 10 minutes.
+
+---
+
+## What clock-aligned recurring means
+
+A clock-aligned recurring countdown fires at fixed intervals anchored to the clock. With `align_interval: 2h` and `timezone: UTC` the countdown fires at 00:00, 02:00, 04:00 … UTC. When the current cycle ends, the next one starts automatically.
+
+This is useful for:
+- Regular server events (reset, boss spawn, shop refresh).
+- Reminders that repeat on a predictable schedule.
+- Server-rule announcements.
+
+---
+
+## Step 1  -  Create the countdown
+
+```
+/countdown create server_reset recurring 0 0 00:00 --align-to-clock --align-interval 2h --timezone UTC --missed-run-policy SKIP
+```
+
+> The `recurring 0 0 00:00` part (month=0, day=0, time=00:00) is a placeholder required by the parser when `--align-to-clock` is used; the actual firing times come from `--align-interval`.
+
+---
+
+## Step 2  -  Verify it was created
+
+```
+/countdown info server_reset
+```
+
+The output should show `align_to_clock: true`, `align_interval: 2h`, and `timezone: UTC`.
+
+---
+
+## Step 3  -  Customise in `countdowns.yml`
+
+Open `plugins/EzCountdown/countdowns.yml` and update the entry:
+
+```yaml
+countdowns:
+  server_reset:
+    type: RECURRING
+    align_to_clock: true
+    align_interval: "2h"
+    timezone: "UTC"
+    missed_run_policy: SKIP
+    display:
+      types:
+        - CHAT
+        - ACTION_BAR
+      update-interval: 60           # update every 60 s (low priority display)
+    messages:
+      format: "<gray>Next server reset in</gray> <white>{formatted}</white>"
+      start: "<aqua>Server reset cycle started.</aqua>"
+      end: "<red>Server reset in progress! Returning in 30 seconds...</red>"
+    commands_on_end:
+      - "broadcast Server reset complete!"
+```
+
+---
+
+## Step 4  -  Reload
+
+```
+/countdown reload
+```
+
+The countdown will fire chat reminders at each two-hour mark.
+
+---
+
+## Step 5  -  Test with a shorter interval
+
+While testing you may want to use a shorter interval to verify it works. Change `align_interval` to `5m` in `countdowns.yml`, reload, and watch the chat messages appear. Change it back to `2h` when done.
+
+---
+
+## Missed-run policies
+
+If your server was offline when a cycle was due:
+
+| Policy | Behaviour |
+|---|---|
+| `SKIP` | Skip the missed cycles and wait for the next scheduled time |
+| `RUN_SINGLE` | Run one missed cycle immediately on startup |
+| `RUN_ALL` | Run all missed cycles back-to-back on startup |
+
+`SKIP` is safe for most scenarios. Use `RUN_SINGLE` if you want the end commands to always fire at least once after a restart.
+
+---
+
+## Next steps
+
+- Combine with [teleport](../feature/teleport) to move players to an arena when the countdown ends.
+- Add a [Discord webhook](../feature/discord_integration) to post the reset notification to a staff channel.
+- See the full [Countdown Types](../feature/countdown_types) reference for all recurring options.
diff --git a/pom.xml b/pom.xml
index 2831ec4..b05fea4 100644
--- a/pom.xml
+++ b/pom.xml
@@ -5,7 +5,7 @@
 
     <groupId>com.github.ez-plugins</groupId>
     <artifactId>ezcountdown</artifactId>
-    <version>1.4.2</version>
+    <version>2.0.0</version>
     <name>EzCountdown Plugin</name>
     <description>Configurable countdowns for server launches, events, and maintenance windows.</description>
     <packaging>jar</packaging>
@@ -83,11 +83,10 @@
     </dependencies>
     
     <properties>
-        <!-- Default to Java 21 to match source language features (records, etc.). -->
-        <maven.compiler.source>21</maven.compiler.source>
-        <maven.compiler.target>21</maven.compiler.target>
+        <!-- Minimum bytecode target is Java 17 (records/pattern-instanceof used; Paper 1.18 requires Java 17). -->
+        <maven.compiler.source>17</maven.compiler.source>
+        <maven.compiler.target>17</maven.compiler.target>
 
-        <!-- Target Java 21 to match Paper API (class file version 65) -->
         <!-- Allow CI to override the Paper API version with -Dpaper.version -->
         <paper.version>1.21.11-R0.1-SNAPSHOT</paper.version>
         <!-- MockBukkit coordinates are configurable so CI can select the right artifact per Paper matrix entry -->
@@ -176,6 +175,7 @@
                 <version>3.0.0-M7</version>
                 <configuration>
                     <useModulePath>false</useModulePath>
+                    <argLine>-Dnet.bytebuddy.experimental=true</argLine>
                     <excludes>
                         <exclude>**/*FeatureTest.java</exclude>
                     </excludes>
@@ -255,15 +255,16 @@
                 <maven.compiler.target>17</maven.compiler.target>
             </properties>
         </profile>
-        <!-- If the build runs on JDK 21 or newer, enable Java 21 compilation. -->
+        <!-- JDK 21 can compile the code; we still target Java 17 bytecode so the JAR
+             runs on Paper 1.18-1.20.4 (Java 17) as well as Paper 1.20.5+ (Java 21). -->
         <profile>
             <id>jdk21</id>
             <activation>
                 <jdk>[21,)</jdk>
             </activation>
             <properties>
-                <maven.compiler.source>21</maven.compiler.source>
-                <maven.compiler.target>21</maven.compiler.target>
+                <maven.compiler.source>17</maven.compiler.source>
+                <maven.compiler.target>17</maven.compiler.target>
             </properties>
         </profile>
         <profile>
diff --git a/src/main/java/com/skyblockexp/ezcountdown/EzCountdownPlugin.java b/src/main/java/com/skyblockexp/ezcountdown/EzCountdownPlugin.java
index 8c53c10..bbd5f24 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/EzCountdownPlugin.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/EzCountdownPlugin.java
@@ -3,6 +3,7 @@
 import com.skyblockexp.ezcountdown.api.EzCountdownApi;
 import com.skyblockexp.ezcountdown.bootstrap.PluginBootstrap;
 import com.skyblockexp.ezcountdown.bootstrap.Registry;
+import com.skyblockexp.ezcountdown.util.ServerVersionUtil;
 import org.bukkit.plugin.java.JavaPlugin;
 
 public class EzCountdownPlugin extends JavaPlugin {
@@ -17,6 +18,22 @@ public static EzCountdownApi getApi() {
     @Override
     public void onEnable() {
         INSTANCE = this;
+
+        int mcMinor = ServerVersionUtil.minorVersion();
+        int javaMinor = parseJavaMajor();
+        getLogger().info("Server: MC " + ServerVersionUtil.versionDisplay() + " | Java " + javaMinor);
+
+        if (mcMinor < 18) {
+            getLogger().severe("EzCountdown requires Paper/Spigot 1.18 or newer. Disabling.");
+            getServer().getPluginManager().disablePlugin(this);
+            return;
+        }
+        if (javaMinor < 17) {
+            getLogger().severe("EzCountdown requires Java 17 or newer. Disabling.");
+            getServer().getPluginManager().disablePlugin(this);
+            return;
+        }
+
         registry = PluginBootstrap.start(this);
         getLogger().info("EzCountdown enabled.");
     }
@@ -30,5 +47,20 @@ public void onDisable() {
         INSTANCE = null;
         getLogger().info("EzCountdown disabled.");
     }
+
+    /** Returns the Java major version (e.g. 17, 21). */
+    private static int parseJavaMajor() {
+        try {
+            String v = System.getProperty("java.version", "17");
+            // "17.0.9", "21.0.1", "1.8.0_362"
+            if (v.startsWith("1.")) {
+                return Integer.parseInt(v.split("\\.")[1]);
+            }
+            return Integer.parseInt(v.split("[.\\-]")[0]);
+        } catch (Throwable ignored) {
+            return 17;
+        }
+    }
 }
 
+
diff --git a/src/main/java/com/skyblockexp/ezcountdown/api/EzCountdownApi.java b/src/main/java/com/skyblockexp/ezcountdown/api/EzCountdownApi.java
index 08388a1..8e22630 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/api/EzCountdownApi.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/api/EzCountdownApi.java
@@ -65,4 +65,36 @@ public interface EzCountdownApi {
      *         {@link Optional#empty()} on a (very unlikely) name collision
      */
     Optional<String> sendNotification(Notification notification);
+
+    /**
+     * Send an ephemeral countdown notification to a specific subset of players.
+     * <p>
+     * Behaves identically to {@link #sendNotification(Notification)} but
+     * restricts display output to the given players for the lifetime of the
+     * notification.  When {@code players} is {@code null} or empty the
+     * notification falls back to targeting all online players.
+     *
+     * <h3>Example</h3>
+     * <pre>{@code
+     * // Show a 10-second action-bar only to a single player
+     * api.sendNotification(Notification.ofSeconds(10), List.of(player));
+     *
+     * // Builder approach — same result
+     * api.sendNotification(
+     *     Notification.builder()
+     *         .duration(10)
+     *         .players(List.of(player))
+     *         .build()
+     * );
+     * }</pre>
+     *
+     * @param notification the notification descriptor
+     * @param players      players to receive the notification;
+     *                     {@code null} or empty sends to all online players
+     * @return the generated countdown name wrapped in Optional, or empty on collision
+     */
+    default Optional<String> sendNotification(Notification notification, Collection<Player> players) {
+        throw new UnsupportedOperationException(
+                "Per-player sendNotification is not supported by this EzCountdownApi implementation.");
+    }
 }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/api/EzCountdownApiImpl.java b/src/main/java/com/skyblockexp/ezcountdown/api/EzCountdownApiImpl.java
index 5f60346..5c31bc7 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/api/EzCountdownApiImpl.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/api/EzCountdownApiImpl.java
@@ -94,11 +94,16 @@ public boolean deleteCountdown(String name) {
 
     @Override
     public Optional<String> sendNotification(Notification notification) {
+        return sendNotification(notification, null);
+    }
+
+    @Override
+    public Optional<String> sendNotification(Notification notification, Collection<Player> players) {
         Objects.requireNonNull(notification, "notification");
         String name = "notif-" + UUID.randomUUID().toString().substring(0, 8);
         com.skyblockexp.ezcountdown.manager.CountdownDefaults defs = registry.defaults();
 
-        Countdown countdown = CountdownBuilder.builder(name)
+        CountdownBuilder builder = CountdownBuilder.builder(name)
                 .type(CountdownType.DURATION)
                 .displayTypes(notification.getDisplayTypes())
                 .updateIntervalSeconds(defs.updateIntervalSeconds())
@@ -106,9 +111,25 @@ public Optional<String> sendNotification(Notification notification) {
                 .startMessage(notification.getStartMessage())
                 .endMessage(notification.getEndMessage())
                 .durationSeconds(notification.getDurationSeconds())
-                .ephemeral(true)
-                .build();
+                .ephemeral(true);
+
+        // Resolve player set: explicit arg takes priority; then fall back to
+        // players embedded in the notification descriptor itself.
+        Collection<Player> effectivePlayers = (players != null && !players.isEmpty())
+                ? players
+                : null;
+        if (effectivePlayers == null && notification.getTargetPlayers() != null
+                && !notification.getTargetPlayers().isEmpty()) {
+            // Convert stored UUIDs back into online players (best-effort)
+            effectivePlayers = org.bukkit.Bukkit.getOnlinePlayers().stream()
+                    .filter(p -> notification.getTargetPlayers().contains(p.getUniqueId()))
+                    .collect(java.util.stream.Collectors.toList());
+        }
+        if (effectivePlayers != null && !effectivePlayers.isEmpty()) {
+            builder.targetPlayers(effectivePlayers);
+        }
 
+        Countdown countdown = builder.build();
         countdown.setRunning(true);
         countdown.setTargetInstant(java.time.Instant.now().plusSeconds(notification.getDurationSeconds()));
 
diff --git a/src/main/java/com/skyblockexp/ezcountdown/api/exception/CountdownNotFoundException.java b/src/main/java/com/skyblockexp/ezcountdown/api/exception/CountdownNotFoundException.java
new file mode 100644
index 0000000..77ef9dd
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/api/exception/CountdownNotFoundException.java
@@ -0,0 +1,22 @@
+package com.skyblockexp.ezcountdown.api.exception;
+
+/**
+ * Thrown when an operation references a countdown name that does not exist.
+ *
+ * <p>Example: calling {@code startCountdown("typo")} when no countdown
+ * named {@code "typo"} has been created.
+ */
+public class CountdownNotFoundException extends EzCountdownException {
+
+    private final String countdownName;
+
+    public CountdownNotFoundException(String name) {
+        super("Countdown not found: '" + name + "'");
+        this.countdownName = name;
+    }
+
+    /** Returns the name of the countdown that was not found. */
+    public String getCountdownName() {
+        return countdownName;
+    }
+}
diff --git a/src/main/java/com/skyblockexp/ezcountdown/api/exception/DuplicateCountdownException.java b/src/main/java/com/skyblockexp/ezcountdown/api/exception/DuplicateCountdownException.java
new file mode 100644
index 0000000..a2544c1
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/api/exception/DuplicateCountdownException.java
@@ -0,0 +1,22 @@
+package com.skyblockexp.ezcountdown.api.exception;
+
+/**
+ * Thrown when attempting to create a countdown whose name already exists.
+ *
+ * <p>Countdown names must be unique. Call {@link com.skyblockexp.ezcountdown.api.EzCountdownApi#deleteCountdown}
+ * first if you need to replace an existing countdown.
+ */
+public class DuplicateCountdownException extends EzCountdownException {
+
+    private final String countdownName;
+
+    public DuplicateCountdownException(String name) {
+        super("A countdown named '" + name + "' already exists");
+        this.countdownName = name;
+    }
+
+    /** Returns the duplicate countdown name. */
+    public String getCountdownName() {
+        return countdownName;
+    }
+}
diff --git a/src/main/java/com/skyblockexp/ezcountdown/api/exception/EzCountdownException.java b/src/main/java/com/skyblockexp/ezcountdown/api/exception/EzCountdownException.java
new file mode 100644
index 0000000..633bdfa
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/api/exception/EzCountdownException.java
@@ -0,0 +1,18 @@
+package com.skyblockexp.ezcountdown.api.exception;
+
+/**
+ * Base unchecked exception for all EzCountdown API errors.
+ *
+ * <p>Catch this type to handle any error thrown by the EzCountdown API in one
+ * place, or catch a more specific subclass for fine-grained handling.
+ */
+public class EzCountdownException extends RuntimeException {
+
+    public EzCountdownException(String message) {
+        super(message);
+    }
+
+    public EzCountdownException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}
diff --git a/src/main/java/com/skyblockexp/ezcountdown/api/exception/InvalidConfigurationException.java b/src/main/java/com/skyblockexp/ezcountdown/api/exception/InvalidConfigurationException.java
new file mode 100644
index 0000000..90d13c0
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/api/exception/InvalidConfigurationException.java
@@ -0,0 +1,20 @@
+package com.skyblockexp.ezcountdown.api.exception;
+
+/**
+ * Thrown when a {@link com.skyblockexp.ezcountdown.api.model.NotificationBuilder}
+ * or {@link com.skyblockexp.ezcountdown.api.model.CountdownBuilder} is built
+ * with invalid or missing configuration.
+ *
+ * <p>This replaces the plain {@link IllegalStateException} previously thrown
+ * by builder {@code build()} methods so callers can catch a specific type.
+ */
+public class InvalidConfigurationException extends EzCountdownException {
+
+    public InvalidConfigurationException(String message) {
+        super(message);
+    }
+
+    public InvalidConfigurationException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}
diff --git a/src/main/java/com/skyblockexp/ezcountdown/api/model/Countdown.java b/src/main/java/com/skyblockexp/ezcountdown/api/model/Countdown.java
index 9d11b30..2792050 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/api/model/Countdown.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/api/model/Countdown.java
@@ -7,8 +7,13 @@
 import java.time.LocalTime;
 import java.time.ZoneId;
 import java.time.ZonedDateTime;
+import java.util.Collection;
 import java.util.EnumSet;
+import java.util.HashSet;
 import java.util.Objects;
+import java.util.Set;
+import java.util.UUID;
+import org.bukkit.entity.Player;
 import com.skyblockexp.ezcountdown.util.DurationParser;
 import org.bukkit.boss.BarColor;
 import org.bukkit.boss.BarStyle;
@@ -82,6 +87,13 @@ public final class Countdown {
      */
     private boolean ephemeral = false;
 
+    /**
+     * When non-null and non-empty, only the players whose UUIDs are in this set
+     * will see this countdown's display output. {@code null} (the default) means
+     * the countdown is visible to all players (subject to {@link #visibilityPermission}).
+     */
+    private Set<UUID> targetPlayers = null;
+
     /**
      * Create a new Countdown instance.
      *
@@ -276,6 +288,47 @@ public Countdown(String name,
     /** Package-private — set by {@link CountdownBuilder#ephemeral(boolean)}. */
     void setEphemeral(boolean ephemeral) { this.ephemeral = ephemeral; }
 
+    /**
+     * Returns an unmodifiable snapshot of the player UUIDs this countdown is
+     * restricted to, or {@code null} if the countdown is visible to all players
+     * (subject to {@link #getVisibilityPermission()}).
+     */
+    public Set<UUID> getTargetPlayers() {
+        return targetPlayers == null ? null : java.util.Collections.unmodifiableSet(targetPlayers);
+    }
+
+    /**
+     * Restrict this countdown's display output to the given players.
+     * Pass {@code null} or an empty collection to remove the restriction and
+     * make the countdown visible to all players again.
+     *
+     * @param players target player UUIDs; {@code null} clears the restriction
+     */
+    public void setTargetPlayers(Collection<UUID> players) {
+        this.targetPlayers = (players == null || players.isEmpty()) ? null : new HashSet<>(players);
+    }
+
+    /**
+     * Returns {@code true} if {@code player} should receive display updates
+     * from this countdown.
+     *
+     * <p>A player is visible when both conditions are satisfied:
+     * <ol>
+     *   <li>The player is in the {@linkplain #getTargetPlayers() target set}
+     *       (or no target set is configured).</li>
+     *   <li>The player has the {@linkplain #getVisibilityPermission() visibility
+     *       permission} (or no permission is configured).</li>
+     * </ol>
+     */
+    public boolean isVisibleTo(Player player) {
+        if (targetPlayers != null && !targetPlayers.isEmpty()
+                && !targetPlayers.contains(player.getUniqueId())) {
+            return false;
+        }
+        String perm = visibilityPermission;
+        return perm == null || perm.isBlank() || player.hasPermission(perm);
+    }
+
     /** @return configured duration in seconds for duration/manual types */
     public long getDurationSeconds() { return durationSeconds; }
 
diff --git a/src/main/java/com/skyblockexp/ezcountdown/api/model/CountdownBuilder.java b/src/main/java/com/skyblockexp/ezcountdown/api/model/CountdownBuilder.java
index b858f7a..4c4f601 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/api/model/CountdownBuilder.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/api/model/CountdownBuilder.java
@@ -6,9 +6,15 @@
 import java.time.LocalTime;
 import java.time.ZoneId;
 import java.util.ArrayList;
+import java.util.Collection;
 import java.util.EnumSet;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Objects;
+import java.util.Set;
+import java.util.UUID;
+import java.util.stream.Collectors;
+import org.bukkit.entity.Player;
 
 /**
  * Builder for {@link Countdown} to simplify construction from consumer code.
@@ -36,6 +42,7 @@ public final class CountdownBuilder {
     private org.bukkit.boss.BarStyle bossBarStyle = org.bukkit.boss.BarStyle.SOLID;
 
     private boolean ephemeral = false;
+    private Set<UUID> targetPlayers = null;
 
     /* optional runtime values that the builder can configure */
     private long durationSeconds = -1L;
@@ -182,6 +189,7 @@ public Countdown build() {
         if (recurringDay > 0) countdown.setRecurringDay(recurringDay);
         if (recurringTime != null) countdown.setRecurringTime(recurringTime);
         if (ephemeral) countdown.setEphemeral(true);
+        if (targetPlayers != null) countdown.setTargetPlayers(targetPlayers);
 
         return countdown;
     }
@@ -196,6 +204,20 @@ public CountdownBuilder bossBarStyle(org.bukkit.boss.BarStyle style) {
         return this;
     }
 
+    /**
+     * Restrict display of this countdown to the given players only.
+     * Pass {@code null} or an empty collection to target all online players.
+     *
+     * @param players players to show the countdown to
+     * @return this builder
+     */
+    public CountdownBuilder targetPlayers(Collection<? extends Player> players) {
+        this.targetPlayers = (players == null || players.isEmpty()) ? null
+                : players.stream().map(Player::getUniqueId)
+                         .collect(Collectors.toCollection(HashSet::new));
+        return this;
+    }
+
     /**
      * Mark the countdown as ephemeral — it will never be persisted to storage
      * and will be automatically removed from memory once it ends.
diff --git a/src/main/java/com/skyblockexp/ezcountdown/api/model/Notification.java b/src/main/java/com/skyblockexp/ezcountdown/api/model/Notification.java
index 9ebd6ed..dd6b67b 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/api/model/Notification.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/api/model/Notification.java
@@ -3,8 +3,14 @@
 import com.skyblockexp.ezcountdown.display.DisplayType;
 
 import java.time.Duration;
+import java.util.Collection;
+import java.util.Collections;
 import java.util.EnumSet;
+import java.util.HashSet;
 import java.util.Objects;
+import java.util.Set;
+import java.util.UUID;
+import org.bukkit.entity.Player;
 
 /**
  * A lightweight, immutable descriptor for an ephemeral countdown notification.
@@ -50,12 +56,15 @@ public final class Notification {
     private final String formatMessage;
     private final String startMessage;
     private final String endMessage;
+    /** Non-null → only these players see the notification. Null → all players. */
+    private final Set<UUID> targetPlayers;
 
     Notification(long durationSeconds,
                  EnumSet<DisplayType> displayTypes,
                  String formatMessage,
                  String startMessage,
-                 String endMessage) {
+                 String endMessage,
+                 Set<UUID> targetPlayers) {
         if (durationSeconds <= 0) throw new IllegalArgumentException("durationSeconds must be > 0, got " + durationSeconds);
         this.durationSeconds = durationSeconds;
         this.displayTypes = displayTypes == null || displayTypes.isEmpty()
@@ -66,6 +75,17 @@ public final class Notification {
                 : formatMessage;
         this.startMessage = startMessage;
         this.endMessage = endMessage;
+        this.targetPlayers = (targetPlayers == null || targetPlayers.isEmpty()) ? null
+                : Collections.unmodifiableSet(new HashSet<>(targetPlayers));
+    }
+
+    /** Package-private backwards-compat constructor (no target players → global). */
+    Notification(long durationSeconds,
+                 EnumSet<DisplayType> displayTypes,
+                 String formatMessage,
+                 String startMessage,
+                 String endMessage) {
+        this(durationSeconds, displayTypes, formatMessage, startMessage, endMessage, null);
     }
 
     // -----------------------------------------------------------------------
@@ -131,12 +151,22 @@ public String getEndMessage() {
         return endMessage;
     }
 
+    /**
+     * Returns an unmodifiable set of player UUIDs that should receive this
+     * notification, or {@code null} if the notification targets all online
+     * players (the default).
+     */
+    public Set<UUID> getTargetPlayers() {
+        return targetPlayers;
+    }
+
     @Override
     public String toString() {
         return "Notification{durationSeconds=" + durationSeconds
                 + ", displayTypes=" + displayTypes
                 + ", formatMessage='" + formatMessage + "'"
                 + ", startMessage=" + startMessage
-                + ", endMessage=" + endMessage + '}';
+                + ", endMessage=" + endMessage
+                + ", targetPlayers=" + targetPlayers + '}';
     }
 }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/api/model/NotificationBuilder.java b/src/main/java/com/skyblockexp/ezcountdown/api/model/NotificationBuilder.java
index 9ade9b3..525550f 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/api/model/NotificationBuilder.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/api/model/NotificationBuilder.java
@@ -1,11 +1,18 @@
 package com.skyblockexp.ezcountdown.api.model;
 
+import com.skyblockexp.ezcountdown.api.exception.InvalidConfigurationException;
 import com.skyblockexp.ezcountdown.display.DisplayType;
 
 import java.time.Duration;
 import java.util.Arrays;
+import java.util.Collection;
 import java.util.EnumSet;
+import java.util.HashSet;
 import java.util.Objects;
+import java.util.Set;
+import java.util.UUID;
+import java.util.stream.Collectors;
+import org.bukkit.entity.Player;
 
 /**
  * Fluent builder for {@link Notification}.
@@ -26,6 +33,7 @@ public final class NotificationBuilder {
     private String formatMessage = Notification.DEFAULT_FORMAT_MESSAGE;
     private String startMessage = null;
     private String endMessage = null;
+    private Set<UUID> targetPlayers = null;
 
     // package-private — created via Notification.builder()
     NotificationBuilder() {}
@@ -129,6 +137,20 @@ public NotificationBuilder endMessage(String message) {
         return this;
     }
 
+    /**
+     * Restrict this notification to the given players only.
+     * Pass {@code null} or an empty collection to target all online players.
+     *
+     * @param players players to receive the notification
+     * @return this builder
+     */
+    public NotificationBuilder players(Collection<? extends Player> players) {
+        this.targetPlayers = (players == null || players.isEmpty()) ? null
+                : players.stream().map(Player::getUniqueId)
+                         .collect(Collectors.toCollection(HashSet::new));
+        return this;
+    }
+
     // -----------------------------------------------------------------------
     // Build
     // -----------------------------------------------------------------------
@@ -137,14 +159,14 @@ public NotificationBuilder endMessage(String message) {
      * Build the {@link Notification}.
      *
      * @return the configured notification
-     * @throws IllegalStateException if no duration was set
+     * @throws InvalidConfigurationException if no positive duration was set
      */
     public Notification build() {
         if (durationSeconds <= 0) {
-            throw new IllegalStateException(
+            throw new InvalidConfigurationException(
                     "A positive duration must be set before calling build(). "
                     + "Use duration(long) or duration(Duration).");
         }
-        return new Notification(durationSeconds, displayTypes, formatMessage, startMessage, endMessage);
+        return new Notification(durationSeconds, displayTypes, formatMessage, startMessage, endMessage, targetPlayers);
     }
 }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/bootstrap/PluginBootstrap.java b/src/main/java/com/skyblockexp/ezcountdown/bootstrap/PluginBootstrap.java
index 9dd21e1..9d3acf1 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/bootstrap/PluginBootstrap.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/bootstrap/PluginBootstrap.java
@@ -32,6 +32,8 @@
 import org.bukkit.plugin.ServicePriority;
 import org.bukkit.configuration.file.FileConfiguration;
 import org.bstats.bukkit.Metrics;
+import com.skyblockexp.ezcountdown.compat.scheduler.SchedulerAdapter;
+import com.skyblockexp.ezcountdown.compat.scheduler.SchedulerAdapterFactory;
 import org.bstats.charts.SingleLineChart;
 
 import java.io.File;
@@ -68,8 +70,12 @@ public static Registry start(EzCountdownPlugin plugin) {
         // Load Discord config
         DiscordWebhookConfig discordWebhookConfig = configService.loadDiscordConfig();
 
+        // Scheduler abstraction — Folia uses GlobalRegionScheduler, Paper/Spigot uses BukkitScheduler
+        SchedulerAdapter scheduler = SchedulerAdapterFactory.create(plugin);
+        plugin.getLogger().info("Scheduler: " + scheduler.getClass().getSimpleName());
+
         // Create a registry placeholder so CountdownManager can reference plugin and other services
-        Registry registry = new Registry(plugin, messageManager, defaults, permissions, displayManager, storage, locationManager, locationPermissions, null, null);
+        Registry registry = new Registry(plugin, messageManager, defaults, permissions, displayManager, storage, locationManager, locationPermissions, null, null, scheduler);
 
         // Register default countdown type handlers
         registry.registerHandler(new FixedDateHandler());
@@ -82,6 +88,9 @@ public static Registry start(EzCountdownPlugin plugin) {
             yamlStorage.setHandlerRegistry(registry.handlersMap());
         }
 
+        registry.setDebug(configService.loadDebug());
+        displayManager.setDebug(registry.debug());
+
         CountdownManager countdownManager = new CountdownManager(registry, discordWebhookConfig, storage, displayManager, messageManager, locationManager);
         // register into registry
         registry.setCountdownManager(countdownManager);
@@ -92,7 +101,7 @@ public static Registry start(EzCountdownPlugin plugin) {
         plugin.getLogger().info("Loaded " + loadedCount + " countdown(s) (" + runningCount + " running).");
 
         // GUI and input handlers
-        ChatInputListener chatInput = new ChatInputListener(plugin);
+        ChatInputListener chatInput = new ChatInputListener(plugin, scheduler);
         // register chat input listener
         Bukkit.getPluginManager().registerEvents(chatInput, plugin);
 
@@ -142,6 +151,13 @@ public static Registry start(EzCountdownPlugin plugin) {
                     plugin.getLogger().log(java.util.logging.Level.WARNING, "Failed to reload defaults or permissions", ex);
                 }
 
+                try {
+                    registry.setDebug(configService.loadDebug());
+                    displayManager.setDebug(registry.debug());
+                } catch (Exception ex) {
+                    plugin.getLogger().log(java.util.logging.Level.WARNING, "Failed to reload debug flag", ex);
+                }
+
                 try {
                     // refresh display manager configuration (clears handlers)
                     displayManager.reload(configService);
diff --git a/src/main/java/com/skyblockexp/ezcountdown/bootstrap/Registry.java b/src/main/java/com/skyblockexp/ezcountdown/bootstrap/Registry.java
index de23e1d..bad3d7b 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/bootstrap/Registry.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/bootstrap/Registry.java
@@ -14,6 +14,7 @@
 import com.skyblockexp.ezcountdown.api.EzCountdownApi;
 import com.skyblockexp.ezcountdown.type.CountdownTypeHandler;
 import com.skyblockexp.ezcountdown.api.model.CountdownType;
+import com.skyblockexp.ezcountdown.compat.scheduler.SchedulerAdapter;
 import com.skyblockexp.ezcountdown.integration.placeholder.EzCountdownPlaceholderExpansion;
 import java.util.Map;
 import java.util.EnumMap;
@@ -31,9 +32,11 @@ public final class Registry {
     private GuiManager guiManager;
     private EzCountdownPlaceholderExpansion placeholderExpansion;
     private EzCountdownApi api;
+    private final SchedulerAdapter scheduler;
     private final Map<CountdownType, CountdownTypeHandler> handlers = new EnumMap<>(CountdownType.class);
+    private volatile boolean debug = false;
 
-    public Registry(EzCountdownPlugin plugin, MessageManager messageManager, CountdownDefaults defaults, CountdownPermissions permissions, DisplayManager displayManager, CountdownStorage storage, LocationManager locationManager, LocationPermissions locationPermissions, CountdownManager countdownManager, GuiManager guiManager) {
+    public Registry(EzCountdownPlugin plugin, MessageManager messageManager, CountdownDefaults defaults, CountdownPermissions permissions, DisplayManager displayManager, CountdownStorage storage, LocationManager locationManager, LocationPermissions locationPermissions, CountdownManager countdownManager, GuiManager guiManager, SchedulerAdapter scheduler) {
         this.plugin = plugin;
         this.messageManager = messageManager;
         this.defaults = defaults;
@@ -44,6 +47,7 @@ public Registry(EzCountdownPlugin plugin, MessageManager messageManager, Countdo
         this.locationPermissions = locationPermissions;
         this.countdownManager = countdownManager;
         this.guiManager = guiManager;
+        this.scheduler = scheduler;
     }
 
     public void setDefaults(CountdownDefaults defaults) {
@@ -91,9 +95,13 @@ public java.util.Map<CountdownType, CountdownTypeHandler> handlersMap() {
     public LocationManager locations() { return locationManager; }
     public LocationPermissions locationPermissions() { return locationPermissions; }
     public CountdownManager countdowns() { return countdownManager; }
+    public boolean debug() { return debug; }
+    public void setDebug(boolean debug) { this.debug = debug; }
 
     public GuiManager gui() { return guiManager; }
 
+    public SchedulerAdapter scheduler() { return scheduler; }
+
     public PluginManager pluginManager() { return plugin.getServer().getPluginManager(); }
 
     public void shutdown() {
diff --git a/src/main/java/com/skyblockexp/ezcountdown/compat/material/MaterialCompat.java b/src/main/java/com/skyblockexp/ezcountdown/compat/material/MaterialCompat.java
new file mode 100644
index 0000000..b0baf41
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/compat/material/MaterialCompat.java
@@ -0,0 +1,50 @@
+package com.skyblockexp.ezcountdown.compat.material;
+
+import org.bukkit.Material;
+
+/**
+ * Compatibility helper for resolving {@link Material} names across Minecraft
+ * versions.
+ *
+ * <p>Material names changed between 1.12 (pre-flattening) and 1.13
+ * (post-flattening). This utility tries each provided name in order and
+ * returns the first non-null match, falling back to {@code PAPER} if none
+ * match.
+ */
+public final class MaterialCompat {
+
+    private MaterialCompat() {}
+
+    /**
+     * Resolves the first matching {@link Material} from the given candidate
+     * names and falls back to {@code PAPER} if none match.
+     *
+     * <p>Both {@link Material#matchMaterial(String)} and
+     * {@link Material#getMaterial(String)} are tried for each name so that
+     * flattened and legacy names are both handled.
+     *
+     * @param names candidate material names in preference order
+     * @return a non-null {@link Material}
+     */
+    public static Material resolve(String... names) {
+        if (names != null) {
+            for (String n : names) {
+                if (n == null) continue;
+                try {
+                    Material m = Material.matchMaterial(n);
+                    if (m != null) return m;
+                } catch (Throwable ignored) {}
+                try {
+                    Material m2 = Material.getMaterial(n);
+                    if (m2 != null) return m2;
+                } catch (Throwable ignored) {}
+            }
+        }
+        try {
+            Material paper = Material.matchMaterial("PAPER");
+            return paper == null ? Material.PAPER : paper;
+        } catch (Throwable ignored) {
+            return Material.PAPER;
+        }
+    }
+}
diff --git a/src/main/java/com/skyblockexp/ezcountdown/compat/platform/PlatformDetector.java b/src/main/java/com/skyblockexp/ezcountdown/compat/platform/PlatformDetector.java
new file mode 100644
index 0000000..f625c59
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/compat/platform/PlatformDetector.java
@@ -0,0 +1,47 @@
+package com.skyblockexp.ezcountdown.compat.platform;
+
+/**
+ * Detects the server platform at class-load time and caches the result.
+ *
+ * <p>Folia is identified by the presence of
+ * {@code io.papermc.paper.threadedregions.RegionizedServer}, a class that
+ * exists only in Folia and is absent from Paper and Spigot. The check is
+ * performed once via {@link Class#forName(String)} and the result is stored
+ * in a {@code static final} field so subsequent calls are free.
+ */
+public final class PlatformDetector {
+
+    /** {@code true} when the server runtime is Folia. */
+    private static final boolean FOLIA;
+
+    static {
+        boolean folia;
+        try {
+            Class.forName("io.papermc.paper.threadedregions.RegionizedServer");
+            folia = true;
+        } catch (ClassNotFoundException ignored) {
+            folia = false;
+        }
+        FOLIA = folia;
+    }
+
+    private PlatformDetector() {}
+
+    /**
+     * Returns {@code true} if the current server runtime is Folia.
+     *
+     * @return {@code true} on Folia, {@code false} on Paper/Spigot
+     */
+    public static boolean isFolia() {
+        return FOLIA;
+    }
+
+    /**
+     * Returns a human-readable platform name suitable for log messages.
+     *
+     * @return {@code "Folia"} or {@code "Paper/Spigot"}
+     */
+    public static String platformName() {
+        return FOLIA ? "Folia" : "Paper/Spigot";
+    }
+}
diff --git a/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/BukkitSchedulerAdapter.java b/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/BukkitSchedulerAdapter.java
new file mode 100644
index 0000000..c0e50d4
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/BukkitSchedulerAdapter.java
@@ -0,0 +1,55 @@
+package com.skyblockexp.ezcountdown.compat.scheduler;
+
+import org.bukkit.Bukkit;
+import org.bukkit.plugin.Plugin;
+import org.bukkit.scheduler.BukkitTask;
+
+/**
+ * {@link SchedulerAdapter} backed by the Bukkit scheduler.
+ *
+ * <p>Suitable for Paper and Spigot 1.18+. <b>Do not use on Folia</b> — the
+ * Bukkit scheduler is not supported on Folia and will throw when tasks are
+ * submitted.
+ *
+ * @see FoliaSchedulerAdapter
+ */
+public final class BukkitSchedulerAdapter implements SchedulerAdapter {
+
+    private final Plugin plugin;
+
+    public BukkitSchedulerAdapter(Plugin plugin) {
+        this.plugin = plugin;
+    }
+
+    @Override
+    public TaskHandle runTask(Runnable task) {
+        BukkitTask t = Bukkit.getScheduler().runTask(plugin, task);
+        return wrap(t);
+    }
+
+    @Override
+    public TaskHandle runTaskTimer(Runnable task, long delayTicks, long periodTicks) {
+        BukkitTask t = Bukkit.getScheduler().runTaskTimer(plugin, task, delayTicks, periodTicks);
+        return wrap(t);
+    }
+
+    @Override
+    public TaskHandle runTaskLater(Runnable task, long delayTicks) {
+        BukkitTask t = delayTicks <= 0
+                ? Bukkit.getScheduler().runTask(plugin, task)
+                : Bukkit.getScheduler().runTaskLater(plugin, task, delayTicks);
+        return wrap(t);
+    }
+
+    @Override
+    public void runTaskAsync(Runnable task) {
+        Bukkit.getScheduler().runTaskAsynchronously(plugin, task);
+    }
+
+    private static TaskHandle wrap(BukkitTask task) {
+        return new TaskHandle() {
+            @Override public void cancel()         { task.cancel(); }
+            @Override public boolean isCancelled() { return task.isCancelled(); }
+        };
+    }
+}
diff --git a/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/FoliaSchedulerAdapter.java b/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/FoliaSchedulerAdapter.java
new file mode 100644
index 0000000..afba9ca
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/FoliaSchedulerAdapter.java
@@ -0,0 +1,70 @@
+package com.skyblockexp.ezcountdown.compat.scheduler;
+
+import io.papermc.paper.threadedregions.scheduler.GlobalRegionScheduler;
+import io.papermc.paper.threadedregions.scheduler.ScheduledTask;
+import org.bukkit.plugin.Plugin;
+
+/**
+ * {@link SchedulerAdapter} backed by Folia's {@link GlobalRegionScheduler}.
+ *
+ * <p>This class directly imports Folia API types, so it must <b>never be
+ * instantiated on servers that do not provide those types</b> (i.e. Paper
+ * 1.18-1.20.4 and Spigot). The {@link SchedulerAdapterFactory} guards the
+ * instantiation so that the JVM only class-loads this type when Folia is
+ * detected at runtime; if the Folia API is absent the resulting
+ * {@link NoClassDefFoundError} is caught and a {@link BukkitSchedulerAdapter}
+ * is used as a fallback.
+ *
+ * <p>Async work is dispatched via a daemon {@link Thread} to avoid the
+ * complexity of Folia's {@code AsyncScheduler} for simple fire-and-forget
+ * tasks (update checks, webhook calls).
+ *
+ * @see BukkitSchedulerAdapter
+ * @see SchedulerAdapterFactory
+ */
+public final class FoliaSchedulerAdapter implements SchedulerAdapter {
+
+    private final Plugin plugin;
+    private final GlobalRegionScheduler global;
+
+    public FoliaSchedulerAdapter(Plugin plugin) {
+        this.plugin = plugin;
+        this.global = plugin.getServer().getGlobalRegionScheduler();
+    }
+
+    @Override
+    public TaskHandle runTask(Runnable task) {
+        ScheduledTask t = global.run(plugin, st -> task.run());
+        return wrap(t);
+    }
+
+    @Override
+    public TaskHandle runTaskTimer(Runnable task, long delayTicks, long periodTicks) {
+        // Folia's runAtFixedRate requires initialDelayTicks >= 1
+        ScheduledTask t = global.runAtFixedRate(plugin, st -> task.run(),
+                Math.max(1L, delayTicks), periodTicks);
+        return wrap(t);
+    }
+
+    @Override
+    public TaskHandle runTaskLater(Runnable task, long delayTicks) {
+        ScheduledTask t = delayTicks <= 0
+                ? global.run(plugin, st -> task.run())
+                : global.runDelayed(plugin, st -> task.run(), delayTicks);
+        return wrap(t);
+    }
+
+    @Override
+    public void runTaskAsync(Runnable task) {
+        Thread thread = new Thread(task, "EzCountdown-Async");
+        thread.setDaemon(true);
+        thread.start();
+    }
+
+    private static TaskHandle wrap(ScheduledTask task) {
+        return new TaskHandle() {
+            @Override public void cancel()         { task.cancel(); }
+            @Override public boolean isCancelled() { return task.isCancelled(); }
+        };
+    }
+}
diff --git a/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/SchedulerAdapter.java b/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/SchedulerAdapter.java
new file mode 100644
index 0000000..b20c3bc
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/SchedulerAdapter.java
@@ -0,0 +1,56 @@
+package com.skyblockexp.ezcountdown.compat.scheduler;
+
+/**
+ * Platform-agnostic scheduler abstraction.
+ *
+ * <p>Implementations route task submissions to either the Bukkit scheduler
+ * (Paper/Spigot via {@link BukkitSchedulerAdapter}) or Folia's
+ * {@code GlobalRegionScheduler} / {@code AsyncScheduler} (via
+ * {@link FoliaSchedulerAdapter}), depending on the detected runtime.
+ *
+ * <p>Use {@link SchedulerAdapterFactory#create(org.bukkit.plugin.Plugin)} to
+ * obtain the correct implementation at start-up.
+ *
+ * @see BukkitSchedulerAdapter
+ * @see FoliaSchedulerAdapter
+ * @see SchedulerAdapterFactory
+ */
+public interface SchedulerAdapter {
+
+    /**
+     * Schedules {@code task} to run on the next available server tick
+     * on the global (main-thread) scheduler.
+     *
+     * @param task the task to run
+     * @return a handle that can cancel the pending execution
+     */
+    TaskHandle runTask(Runnable task);
+
+    /**
+     * Schedules {@code task} to run at a fixed rate on the global scheduler.
+     *
+     * @param task        the task to repeat
+     * @param delayTicks  ticks to wait before the first run (minimum 1 on Folia)
+     * @param periodTicks ticks between subsequent runs
+     * @return a handle that cancels the repeating task
+     */
+    TaskHandle runTaskTimer(Runnable task, long delayTicks, long periodTicks);
+
+    /**
+     * Schedules {@code task} to run once after a delay on the global scheduler.
+     *
+     * @param task       the task to run
+     * @param delayTicks ticks to wait; {@code 0} runs on the next tick
+     * @return a handle that cancels the pending task
+     */
+    TaskHandle runTaskLater(Runnable task, long delayTicks);
+
+    /**
+     * Submits {@code task} for execution on an off-thread worker.
+     *
+     * <p>The task must not call Bukkit API directly from its thread.
+     *
+     * @param task the work to execute asynchronously
+     */
+    void runTaskAsync(Runnable task);
+}
diff --git a/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/SchedulerAdapterFactory.java b/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/SchedulerAdapterFactory.java
new file mode 100644
index 0000000..2cbb3d2
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/SchedulerAdapterFactory.java
@@ -0,0 +1,45 @@
+package com.skyblockexp.ezcountdown.compat.scheduler;
+
+import com.skyblockexp.ezcountdown.compat.platform.PlatformDetector;
+import org.bukkit.plugin.Plugin;
+
+/**
+ * Creates the most appropriate {@link SchedulerAdapter} for the current
+ * server runtime.
+ *
+ * <ul>
+ *   <li>On <b>Folia</b>: returns a {@link FoliaSchedulerAdapter} that uses
+ *       Folia's {@code GlobalRegionScheduler}.</li>
+ *   <li>On <b>Paper / Spigot</b>: returns a {@link BukkitSchedulerAdapter}
+ *       that wraps the legacy Bukkit scheduler.</li>
+ * </ul>
+ *
+ * <p>If Folia is detected but its API classes are unexpectedly absent at
+ * runtime, a warning is logged and the factory falls back to
+ * {@link BukkitSchedulerAdapter}.
+ */
+public final class SchedulerAdapterFactory {
+
+    private SchedulerAdapterFactory() {}
+
+    /**
+     * Returns the best {@link SchedulerAdapter} for the running platform.
+     *
+     * @param plugin the owning plugin; used to bind scheduled tasks
+     * @return a non-null {@link SchedulerAdapter}
+     */
+    public static SchedulerAdapter create(Plugin plugin) {
+        if (PlatformDetector.isFolia()) {
+            try {
+                return new FoliaSchedulerAdapter(plugin);
+            } catch (NoClassDefFoundError e) {
+                plugin.getLogger().warning("[EzCountdown] Folia classes not found, falling back to Bukkit scheduler. Reason: " + e.getMessage());
+            } catch (Throwable e) {
+                plugin.getLogger().warning(
+                        "[EzCountdown] Folia detected but Folia scheduler API is unavailable — "
+                        + "falling back to Bukkit scheduler. Some features may not work correctly.");
+            }
+        }
+        return new BukkitSchedulerAdapter(plugin);
+    }
+}
diff --git a/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/TaskHandle.java b/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/TaskHandle.java
new file mode 100644
index 0000000..274eb6c
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/compat/scheduler/TaskHandle.java
@@ -0,0 +1,31 @@
+package com.skyblockexp.ezcountdown.compat.scheduler;
+
+/**
+ * A handle to a scheduled task that can be cancelled.
+ *
+ * <p>Abstracts over {@link org.bukkit.scheduler.BukkitTask} (Paper/Spigot) and
+ * {@code io.papermc.paper.threadedregions.scheduler.ScheduledTask} (Folia)
+ * so callers never need to import platform-specific types.
+ */
+public interface TaskHandle {
+
+    /** Cancels this task. No-op if already cancelled or already run. */
+    void cancel();
+
+    /** Returns {@code true} if this task has been cancelled. */
+    boolean isCancelled();
+
+    /**
+     * Returns a no-op handle that is immediately in the cancelled state.
+     * Useful as a null-safe sentinel value.
+     *
+     * @return an already-cancelled handle
+     */
+    static TaskHandle empty() {
+        return new TaskHandle() {
+            private volatile boolean cancelled;
+            @Override public void cancel()           { cancelled = true; }
+            @Override public boolean isCancelled()   { return cancelled; }
+        };
+    }
+}
diff --git a/src/main/java/com/skyblockexp/ezcountdown/compat/scoreboard/ScoreboardCompat.java b/src/main/java/com/skyblockexp/ezcountdown/compat/scoreboard/ScoreboardCompat.java
new file mode 100644
index 0000000..2be9caa
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/compat/scoreboard/ScoreboardCompat.java
@@ -0,0 +1,87 @@
+package com.skyblockexp.ezcountdown.compat.scoreboard;
+
+import net.kyori.adventure.text.Component;
+import org.bukkit.scoreboard.Objective;
+import org.bukkit.scoreboard.Scoreboard;
+
+/**
+ * Cross-version helpers for the Bukkit scoreboard API.
+ *
+ * <ul>
+ *   <li>{@code registerObjective} — uses {@code Criteria.DUMMY} + Adventure {@link Component} on
+ *       Paper 1.20.3+ where the legacy {@code (name, "dummy", String)} overload is deprecated, and
+ *       falls back to the string overload on older builds or vanilla Spigot.
+ *   <li>{@code clearObjective} — unregisters the objective to drop all stale score entries without
+ *       calling the deprecated {@code Scoreboard.resetScores(String)}.
+ * </ul>
+ */
+public final class ScoreboardCompat {
+
+    /** {@code true} when {@code org.bukkit.scoreboard.Criteria} (Paper 1.20.3+) is available. */
+    private static final boolean HAS_CRITERIA = detectCriteria();
+
+    private ScoreboardCompat() {}
+
+    private static boolean detectCriteria() {
+        try {
+            Class.forName("org.bukkit.scoreboard.Criteria");
+            return true;
+        } catch (ClassNotFoundException ignored) {
+            return false;
+        }
+    }
+
+    /**
+     * Registers a new sidebar objective on {@code scoreboard} using the most modern overload
+     * available at runtime.
+     *
+     * <p>On Paper 1.20.3+ this calls
+     * {@code Scoreboard.registerNewObjective(name, Criteria.DUMMY, Component)} to avoid
+     * the deprecation warning from the legacy string-criteria version. On older builds it
+     * falls back to {@code registerNewObjective(name, "dummy", displayName)}.
+     *
+     * @param scoreboard  the scoreboard to register on
+     * @param name        objective name (max 16 chars)
+     * @param displayName human-readable display name
+     * @return the newly registered {@link Objective}
+     */
+    @SuppressWarnings("deprecation")
+    public static Objective registerObjective(Scoreboard scoreboard, String name, String displayName) {
+        if (HAS_CRITERIA) {
+            try {
+                org.bukkit.scoreboard.Criteria dummy = org.bukkit.scoreboard.Criteria.DUMMY;
+                if (dummy != null) {
+                    return scoreboard.registerNewObjective(
+                            name,
+                            dummy,
+                            net.kyori.adventure.text.Component.text(displayName));
+                }
+            } catch (NoSuchMethodError | NoClassDefFoundError ignored) {
+                // Criteria class exists but overload mismatch — fall through to legacy
+            }
+        }
+        return scoreboard.registerNewObjective(name, "dummy", displayName);
+    }
+
+    /**
+     * Clears all score entries from {@code scoreboard} by unregistering the given objective and
+     * returning the caller a fresh replacement — this avoids calling the deprecated
+     * {@code Scoreboard.resetScores(String)}.
+     *
+     * <p>Usage:
+     * <pre>{@code
+     *   objective = ScoreboardCompat.resetObjective(scoreboard, objective, displayName);
+     *   objective.setDisplaySlot(DisplaySlot.SIDEBAR);
+     * }</pre>
+     *
+     * @param scoreboard  the scoreboard that owns the objective
+     * @param objective   the objective to clear; unregistered on return
+     * @param displayName display name for the re-registered objective
+     * @return a freshly registered objective with the same name and display slot
+     */
+    public static Objective resetObjective(Scoreboard scoreboard, Objective objective, String displayName) {
+        String name = objective.getName();
+        objective.unregister();
+        return registerObjective(scoreboard, name, displayName);
+    }
+}
diff --git a/src/main/java/com/skyblockexp/ezcountdown/compat/title/TitleCompat.java b/src/main/java/com/skyblockexp/ezcountdown/compat/title/TitleCompat.java
new file mode 100644
index 0000000..35cb2ea
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/compat/title/TitleCompat.java
@@ -0,0 +1,88 @@
+package com.skyblockexp.ezcountdown.compat.title;
+
+import org.bukkit.entity.Player;
+
+/**
+ * Cross-version helpers for sending and clearing player titles.
+ *
+ * <ul>
+ *   <li>{@link #sendTitle} — uses the Bukkit {@code sendTitle(String, String, int, int, int)} API,
+ *       which is present on Paper 1.8+ and all Spigot versions. The method is marked deprecated
+ *       in newer Paper builds but is not removed and works correctly across all supported servers.
+ *   <li>{@link #clearTitle} — prefers the Adventure {@code clearTitle()} (Paper 1.18+) which
+ *       instantly removes the title; falls back to {@code resetTitle()} on Spigot.
+ * </ul>
+ *
+ * <p>Note: the Adventure {@code Player.showTitle(Title)} API cannot be used here because
+ * MockBukkit does not bridge it to the tracked title queue and real-server implementations
+ * vary. {@code sendTitle} is universally reliable.</p>
+ */
+public final class TitleCompat {
+
+    /** {@code true} when Adventure {@code Player#clearTitle()} is available (Paper 1.18+). */
+    private static final boolean HAS_CLEAR_TITLE = detectClearTitle();
+
+    private TitleCompat() {}
+
+    private static boolean detectClearTitle() {
+        try {
+            Player.class.getMethod("clearTitle");
+            return true;
+        } catch (NoSuchMethodException ignored) {
+            return false;
+        } catch (NoClassDefFoundError ignored) {
+            return false;
+        }
+    }
+
+    /**
+     * Sends a title to {@code player}.
+     *
+     * <p>Uses {@code Player.sendTitle(String, String, int, int, int)} which is available
+     * on all supported server variants (Paper and Spigot 1.18+). Falls back to the
+     * action-bar / chat if the method is unexpectedly absent.
+     *
+     * @param player   the player to send the title to
+     * @param title    main title text
+     * @param fadeIn   fade-in ticks
+     * @param stay     stay ticks
+     * @param fadeOut  fade-out ticks
+     */
+    @SuppressWarnings("deprecation")
+    public static void sendTitle(Player player, String title, int fadeIn, int stay, int fadeOut) {
+        try {
+            player.sendTitle(title, "", fadeIn, stay, fadeOut);
+        } catch (NoSuchMethodError | NoClassDefFoundError ex) {
+            // last resort: action bar, then chat
+            try {
+                player.sendActionBar(title);
+            } catch (NoSuchMethodError | NoClassDefFoundError ignored) {
+                player.sendMessage(title);
+            }
+        }
+    }
+
+    /**
+     * Clears any title currently shown to {@code player}.
+     *
+     * <p>Prefers the Adventure {@code clearTitle()} on Paper 1.18+; falls back to
+     * {@code resetTitle()} for Spigot.
+     */
+    @SuppressWarnings("deprecation")
+    public static void clearTitle(Player player) {
+        if (HAS_CLEAR_TITLE) {
+            try {
+                player.clearTitle();
+                return;
+            } catch (NoSuchMethodError | NoClassDefFoundError ignored) {
+                // fall through
+            }
+        }
+        try {
+            player.resetTitle();
+        } catch (NoSuchMethodError | NoClassDefFoundError ignored) {
+            // nothing to clear
+        }
+    }
+}
+
diff --git a/src/main/java/com/skyblockexp/ezcountdown/compat/version/ServerVersionUtil.java b/src/main/java/com/skyblockexp/ezcountdown/compat/version/ServerVersionUtil.java
new file mode 100644
index 0000000..001fd7f
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/compat/version/ServerVersionUtil.java
@@ -0,0 +1,102 @@
+package com.skyblockexp.ezcountdown.compat.version;
+
+import org.bukkit.Bukkit;
+
+/**
+ * Lightweight utility for querying the running Minecraft minor version at
+ * runtime.
+ *
+ * <p>Two Bukkit version string formats are supported:
+ * <ul>
+ *   <li><b>Legacy</b>: {@code 1.21.1-R0.1-SNAPSHOT} — through MC 1.x.
+ *       {@link #minorVersion()} returns {@code 21}.
+ *   <li><b>New-format</b>: {@code 26.1-R0.1-SNAPSHOT} — when the leading
+ *       {@code 1.} prefix is dropped. {@link #minorVersion()} returns
+ *       {@code 26} so all {@link #atLeast} comparisons remain valid.
+ * </ul>
+ */
+public final class ServerVersionUtil {
+
+    private static final int MINOR;
+    private static final String DISPLAY;
+
+    static {
+        String[] parsed = parseFrom(safeBukkitVersion());
+        MINOR   = Integer.parseInt(parsed[0]);
+        DISPLAY = parsed[1];
+    }
+
+    private ServerVersionUtil() {}
+
+    /** Returns the effective Minecraft minor version (e.g. 21 or 26). */
+    public static int minorVersion() {
+        return MINOR;
+    }
+
+    /**
+     * Returns a human-readable MC version string for log messages,
+     * e.g. {@code "1.21"} or {@code "26.1"}.
+     */
+    public static String versionDisplay() {
+        return DISPLAY;
+    }
+
+    /**
+     * Returns {@code true} if the server is running Minecraft 1.{@code minor}
+     * or newer.
+     */
+    public static boolean atLeast(int minor) {
+        return MINOR >= minor;
+    }
+
+    // -------------------------------------------------------------------------
+    // Package-private for unit testing
+    // -------------------------------------------------------------------------
+
+    /**
+     * Parses a Bukkit version string and returns [effectiveMinor, displayString].
+     * Examples:
+     *   "1.21.1-R0.1-SNAPSHOT"  -> ["21", "1.21"]
+     *   "26.1-R0.1-SNAPSHOT"    -> ["26", "26.1"]
+     *   "27-R0.1-SNAPSHOT"      -> ["27", "27"]
+     */
+    static String[] parseFrom(String bukkit) {
+        try {
+            String clean = bukkit.split("-")[0]; // strip -R0.1-SNAPSHOT
+            String[] parts = clean.split("\\.");
+            if (parts.length >= 2 && "1".equals(parts[0])) {
+                // Legacy: 1.21.1 -> minor=21, display="1.21"
+                String minorStr = digits(parts[1]);
+                Integer.parseInt(minorStr); // validate; throws on empty
+                return new String[]{minorStr, "1." + minorStr};
+            } else if (parts.length >= 2) {
+                // New-format: 26.1 -> effective-minor=26, display="26.1"
+                String majorStr = digits(parts[0]);
+                Integer.parseInt(majorStr); // validate
+                String subStr   = digits(parts[1]);
+                return new String[]{majorStr, majorStr + "." + subStr};
+            } else if (parts.length == 1) {
+                // Bare major: 27 -> effective-minor=27, display="27"
+                String majorStr = digits(parts[0]);
+                Integer.parseInt(majorStr); // validate
+                return new String[]{majorStr, majorStr};
+            }
+        } catch (Throwable ignored) {
+            // Unexpected format; fall through to default
+        }
+        return new String[]{"21", "1.21"};
+    }
+
+    /** Strips everything from the first non-digit character onward. */
+    private static String digits(String s) {
+        return s.replaceAll("[^0-9].*", "");
+    }
+
+    private static String safeBukkitVersion() {
+        try {
+            return Bukkit.getBukkitVersion();
+        } catch (Throwable t) {
+            return "1.21-R0.1-SNAPSHOT";
+        }
+    }
+}
diff --git a/src/main/java/com/skyblockexp/ezcountdown/config/ConfigService.java b/src/main/java/com/skyblockexp/ezcountdown/config/ConfigService.java
index c5989ba..3196fad 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/config/ConfigService.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/config/ConfigService.java
@@ -113,6 +113,10 @@ public TimeFormat.FormatConfig loadTimeFormatConfig() {
         return new TimeFormat.FormatConfig(pattern, hideLeadingZeros);
     }
 
+    public boolean loadDebug() {
+        return plugin.getConfig().getBoolean("debug", false);
+    }
+
     private void ensureResource(String name) {
         File file = new File(plugin.getDataFolder(), name);
         if (!file.exists()) plugin.saveResource(name, false);
diff --git a/src/main/java/com/skyblockexp/ezcountdown/display/DisplayManager.java b/src/main/java/com/skyblockexp/ezcountdown/display/DisplayManager.java
index be8949a..cb7a320 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/display/DisplayManager.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/display/DisplayManager.java
@@ -89,8 +89,7 @@ public void clearAll() {
     }
 
     private boolean canSee(Player player, Countdown countdown) {
-        String permission = countdown.getVisibilityPermission();
-        return permission == null || permission.isBlank() || player.hasPermission(permission);
+        return countdown.isVisibleTo(player);
     }
 
     private void updateBossBar(Countdown countdown, String message, long remainingSeconds) {
diff --git a/src/main/java/com/skyblockexp/ezcountdown/display/actionbar/ActionBarDisplay.java b/src/main/java/com/skyblockexp/ezcountdown/display/actionbar/ActionBarDisplay.java
index 94363d6..04f60f6 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/display/actionbar/ActionBarDisplay.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/display/actionbar/ActionBarDisplay.java
@@ -12,8 +12,7 @@ public class ActionBarDisplay implements DisplayHandler {
     public void display(Countdown countdown, String message, long remainingSeconds) {
         if (remainingSeconds <= 0L) return;
         for (Player player : Bukkit.getOnlinePlayers()) {
-            String perm = countdown.getVisibilityPermission();
-            if (perm == null || perm.isBlank() || player.hasPermission(perm)) {
+            if (countdown.isVisibleTo(player)) {
                 try {
                     player.sendActionBar(message);
                 } catch (NoSuchMethodError err) {
@@ -32,8 +31,7 @@ public void display(Countdown countdown, String message, long remainingSeconds)
     public void displayBatched(Countdown countdown, String message, long remainingSeconds, MessageBatch batch) {
         if (remainingSeconds <= 0L) return;
         for (Player player : Bukkit.getOnlinePlayers()) {
-            String perm = countdown.getVisibilityPermission();
-            if (perm == null || perm.isBlank() || player.hasPermission(perm)) {
+            if (countdown.isVisibleTo(player)) {
                 try {
                     player.sendActionBar(message);
                 } catch (NoSuchMethodError err) {
diff --git a/src/main/java/com/skyblockexp/ezcountdown/display/bossbar/BossBarDisplay.java b/src/main/java/com/skyblockexp/ezcountdown/display/bossbar/BossBarDisplay.java
index b1084bf..bbd066c 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/display/bossbar/BossBarDisplay.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/display/bossbar/BossBarDisplay.java
@@ -32,9 +32,8 @@ private void updateSingle(Countdown countdown, String message, long remainingSec
             bossBar.setTitle(message);
             bossBar.setProgress(calculateProgress(countdown, remainingSeconds));
             for (Player player : Bukkit.getOnlinePlayers()) {
-                String perm = countdown.getVisibilityPermission();
                 try {
-                    if (perm == null || perm.isBlank() || player.hasPermission(perm)) {
+                    if (countdown.isVisibleTo(player)) {
                         bossBar.addPlayer(player);
                     } else {
                         bossBar.removePlayer(player);
diff --git a/src/main/java/com/skyblockexp/ezcountdown/display/chat/ChatDisplay.java b/src/main/java/com/skyblockexp/ezcountdown/display/chat/ChatDisplay.java
index 7ad2e2f..9a88058 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/display/chat/ChatDisplay.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/display/chat/ChatDisplay.java
@@ -12,8 +12,7 @@ public class ChatDisplay implements DisplayHandler {
     public void display(Countdown countdown, String message, long remainingSeconds) {
         if (remainingSeconds <= 0L) return;
         for (Player player : Bukkit.getOnlinePlayers()) {
-            String perm = countdown.getVisibilityPermission();
-            if (perm == null || perm.isBlank() || player.hasPermission(perm)) {
+            if (countdown.isVisibleTo(player)) {
                 player.sendMessage(message);
             }
         }
@@ -23,8 +22,7 @@ public void display(Countdown countdown, String message, long remainingSeconds)
     public void displayBatched(Countdown countdown, String message, long remainingSeconds, MessageBatch batch) {
         if (remainingSeconds <= 0L) return;
         for (Player player : Bukkit.getOnlinePlayers()) {
-            String perm = countdown.getVisibilityPermission();
-            if (perm == null || perm.isBlank() || player.hasPermission(perm)) {
+            if (countdown.isVisibleTo(player)) {
                 batch.add(player, countdown, message);
             }
         }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/display/dialog/DialogDisplay.java b/src/main/java/com/skyblockexp/ezcountdown/display/dialog/DialogDisplay.java
index d57fd04..4eae8ac 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/display/dialog/DialogDisplay.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/display/dialog/DialogDisplay.java
@@ -61,10 +61,9 @@ public void display(Countdown countdown, String message, long remainingSeconds)
         }
 
         String cdName = countdown.getName();
-        String perm = countdown.getVisibilityPermission();
 
         for (Player player : Bukkit.getOnlinePlayers()) {
-            if (perm != null && !perm.isBlank() && !player.hasPermission(perm)) {
+            if (!countdown.isVisibleTo(player)) {
                 // Player lost permission — close any open dialog from this countdown
                 UUID uid = player.getUniqueId();
                 LastShown prev = lastShown.get(uid);
diff --git a/src/main/java/com/skyblockexp/ezcountdown/display/scoreboard/ScoreboardDisplay.java b/src/main/java/com/skyblockexp/ezcountdown/display/scoreboard/ScoreboardDisplay.java
index 1045be8..8b074f3 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/display/scoreboard/ScoreboardDisplay.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/display/scoreboard/ScoreboardDisplay.java
@@ -1,6 +1,7 @@
 package com.skyblockexp.ezcountdown.display.scoreboard;
 
 import com.skyblockexp.ezcountdown.api.model.Countdown;
+import com.skyblockexp.ezcountdown.compat.scoreboard.ScoreboardCompat;
 import com.skyblockexp.ezcountdown.display.DisplayHandler;
 import com.skyblockexp.ezcountdown.display.StackableDisplay;
 import java.util.Collection;
@@ -10,7 +11,6 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.Locale;
 import org.bukkit.Bukkit;
-import org.bukkit.ChatColor;
 import org.bukkit.entity.Player;
 import org.bukkit.scoreboard.DisplaySlot;
 import org.bukkit.scoreboard.Objective;
@@ -43,8 +43,7 @@ public void display(Countdown countdown, String message, long remainingSeconds)
         ScoreboardManager manager = Bukkit.getScoreboardManager();
         if (manager == null) return;
         for (Player player : Bukkit.getOnlinePlayers()) {
-            String perm = countdown.getVisibilityPermission();
-            if (perm == null || perm.isBlank() || player.hasPermission(perm)) {
+            if (countdown.isVisibleTo(player)) {
                 try {
                     Scoreboard scoreboard = player.getScoreboard();
                     if (scoreboard == manager.getMainScoreboard()) {
@@ -54,12 +53,13 @@ public void display(Countdown countdown, String message, long remainingSeconds)
                     String objectiveName = buildObjectiveName(countdown.getName());
                     Objective objective = scoreboard.getObjective(objectiveName);
                     if (objective == null) {
-                        objective = scoreboard.registerNewObjective(objectiveName, "dummy", ChatColor.AQUA + "Countdown");
+                        objective = ScoreboardCompat.registerObjective(scoreboard, objectiveName, "Countdown");
+                    } else {
+                        objective = ScoreboardCompat.resetObjective(scoreboard, objective, "Countdown");
                     }
                     objective.setDisplaySlot(DisplaySlot.SIDEBAR);
-                    scoreboard.getEntries().forEach(scoreboard::resetScores);
                     objective.getScore(message).setScore(1);
-                } catch (NoClassDefFoundError | UnsupportedOperationException | IllegalArgumentException e) {
+                } catch (NoClassDefFoundError | NoSuchMethodError | UnsupportedOperationException | IllegalArgumentException e) {
                     // Scoreboard operations failed; fall back to chat for compatibility
                     player.sendMessage(message);
                 }
@@ -116,8 +116,7 @@ public void displayMultiple(Collection<com.skyblockexp.ezcountdown.api.model.Cou
                     long rem = remaining.getOrDefault(c, 0L);
                     if (rem <= 0L) continue; // skip timers at zero
                     if (!c.getDisplayTypes().contains(com.skyblockexp.ezcountdown.display.DisplayType.SCOREBOARD)) continue;
-                    String perm = c.getVisibilityPermission();
-                    if (perm == null || perm.isBlank() || player.hasPermission(perm)) {
+                    if (c.isVisibleTo(player)) {
                         String msg = messages.get(c);
                         if (msg != null) visible.add(msg);
                     }
@@ -148,28 +147,28 @@ public void displayMultiple(Collection<com.skyblockexp.ezcountdown.api.model.Cou
 
                 Objective objective = scoreboard.getObjective(objectiveName);
                 if (objective == null) {
-                    objective = scoreboard.registerNewObjective(objectiveName, "dummy", ChatColor.AQUA + "Countdowns");
+                    objective = ScoreboardCompat.registerObjective(scoreboard, objectiveName, "Countdowns");
+                } else {
+                    objective = ScoreboardCompat.resetObjective(scoreboard, objective, "Countdowns");
                 }
                 objective.setDisplaySlot(DisplaySlot.SIDEBAR);
-                scoreboard.getEntries().forEach(scoreboard::resetScores);
 
                 // Add entries (higher score displays higher on sidebar)
                 int score = visible.size();
                 for (String msg : visible) {
                     try {
                         objective.getScore(msg).setScore(score--);
-                    } catch (NoClassDefFoundError | UnsupportedOperationException | IllegalArgumentException e) {
+                    } catch (NoClassDefFoundError | NoSuchMethodError | UnsupportedOperationException | IllegalArgumentException e) {
                         player.sendMessage(msg);
                     }
                 }
-            } catch (NoClassDefFoundError | UnsupportedOperationException | IllegalArgumentException e) {
+            } catch (NoClassDefFoundError | NoSuchMethodError | UnsupportedOperationException | IllegalArgumentException e) {
                 // fallback to chat if scoreboard ops fail — mirror the same guards used in the happy path
                 for (com.skyblockexp.ezcountdown.api.model.Countdown c : countdowns) {
                     long rem = remaining.getOrDefault(c, 0L);
                     if (rem <= 0L) continue; // skip countdown whose timer has reached zero
                     if (!c.getDisplayTypes().contains(com.skyblockexp.ezcountdown.display.DisplayType.SCOREBOARD)) continue;
-                    String perm = c.getVisibilityPermission();
-                    if (perm == null || perm.isBlank() || player.hasPermission(perm)) {
+                    if (c.isVisibleTo(player)) {
                         String msg = messages.get(c);
                         if (msg != null) player.sendMessage(msg);
                     }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/display/title/TitleDisplay.java b/src/main/java/com/skyblockexp/ezcountdown/display/title/TitleDisplay.java
index 31d9906..f4cc25b 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/display/title/TitleDisplay.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/display/title/TitleDisplay.java
@@ -1,6 +1,7 @@
 package com.skyblockexp.ezcountdown.display.title;
 
 import com.skyblockexp.ezcountdown.api.model.Countdown;
+import com.skyblockexp.ezcountdown.compat.title.TitleCompat;
 import com.skyblockexp.ezcountdown.display.DisplayHandler;
 import com.skyblockexp.ezcountdown.display.MessageBatch;
 import org.bukkit.Bukkit;
@@ -12,18 +13,8 @@ public class TitleDisplay implements DisplayHandler {
     public void display(Countdown countdown, String message, long remainingSeconds) {
         if (remainingSeconds <= 0L) return;
         for (Player player : Bukkit.getOnlinePlayers()) {
-            String perm = countdown.getVisibilityPermission();
-            if (perm == null || perm.isBlank() || player.hasPermission(perm)) {
-                try {
-                    player.sendTitle(message, "", 10, 40, 10);
-                } catch (NoSuchMethodError | NoClassDefFoundError err) {
-                    // Fallback to action bar if available, otherwise send chat
-                    try {
-                        player.sendActionBar(message);
-                    } catch (NoSuchMethodError | NoClassDefFoundError ex) {
-                        player.sendMessage(message);
-                    }
-                }
+            if (countdown.isVisibleTo(player)) {
+                TitleCompat.sendTitle(player, message, 10, 40, 10);
             }
         }
     }
@@ -32,18 +23,8 @@ public void display(Countdown countdown, String message, long remainingSeconds)
     public void displayBatched(Countdown countdown, String message, long remainingSeconds, MessageBatch batch) {
         if (remainingSeconds <= 0L) return;
         for (Player player : Bukkit.getOnlinePlayers()) {
-            String perm = countdown.getVisibilityPermission();
-            if (perm == null || perm.isBlank() || player.hasPermission(perm)) {
-                try {
-                    player.sendTitle(message, "", 10, 40, 10);
-                } catch (NoSuchMethodError | NoClassDefFoundError err) {
-                    // Fallback to action bar if available, otherwise route through batch
-                    try {
-                        player.sendActionBar(message);
-                    } catch (NoSuchMethodError | NoClassDefFoundError ex) {
-                        batch.add(player, countdown, message);
-                    }
-                }
+            if (countdown.isVisibleTo(player)) {
+                TitleCompat.sendTitle(player, message, 10, 40, 10);
             }
         }
     }
@@ -51,13 +32,8 @@ public void displayBatched(Countdown countdown, String message, long remainingSe
     @Override
     public void clear(Countdown countdown) {
         for (Player player : Bukkit.getOnlinePlayers()) {
-            String perm = countdown.getVisibilityPermission();
-            if (perm == null || perm.isBlank() || player.hasPermission(perm)) {
-                try {
-                    player.resetTitle();
-                } catch (NoSuchMethodError | NoClassDefFoundError ignored) {
-                    // nothing to clear when titles aren't supported
-                }
+            if (countdown.isVisibleTo(player)) {
+                TitleCompat.clearTitle(player);
             }
         }
     }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/display/title/TitleValidator.java b/src/main/java/com/skyblockexp/ezcountdown/display/title/TitleValidator.java
index ae93bc9..c70c6c3 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/display/title/TitleValidator.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/display/title/TitleValidator.java
@@ -4,17 +4,27 @@
 import org.bukkit.entity.Player;
 
 /**
- * Validate whether title API is present (Player.sendTitle).
+ * Validates that the title API is available at runtime.
+ * Accepts either {@code Player.sendTitle(String...)} (Spigot/Paper) or the
+ * Adventure {@code Player.showTitle(Title)} (Paper 1.18+).
  */
 public class TitleValidator extends Validator {
 
     @Override
     public ValidationResult validate() {
+        // Legacy String-based sendTitle — present on all supported servers (Paper + Spigot 1.18+)
         try {
             Player.class.getMethod("sendTitle", String.class, String.class, int.class, int.class, int.class);
             return ValidationResult.ok();
-        } catch (NoSuchMethodException e) {
-            return ValidationResult.fail("Title unsupported: Player.sendTitle method not found.");
+        } catch (NoSuchMethodException ignored) {
+            // fall through
+        }
+        // Adventure showTitle — Paper 1.18+ (secondary check)
+        try {
+            Player.class.getMethod("showTitle", net.kyori.adventure.title.Title.class);
+            return ValidationResult.ok();
+        } catch (NoSuchMethodException | NoClassDefFoundError e) {
+            return ValidationResult.fail("Title unsupported: neither Player.sendTitle nor Player.showTitle found.");
         }
     }
 }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/firework/FireworkShowManager.java b/src/main/java/com/skyblockexp/ezcountdown/firework/FireworkShowManager.java
index fd1ff4d..382fc5c 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/firework/FireworkShowManager.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/firework/FireworkShowManager.java
@@ -1,6 +1,7 @@
 package com.skyblockexp.ezcountdown.firework;
 
 import com.skyblockexp.ezcountdown.api.model.Countdown;
+import com.skyblockexp.ezcountdown.compat.scheduler.SchedulerAdapter;
 import org.bukkit.Bukkit;
 import org.bukkit.Color;
 import org.bukkit.FireworkEffect;
@@ -11,7 +12,6 @@
 import org.bukkit.entity.Firework;
 import org.bukkit.inventory.meta.FireworkMeta;
 import org.bukkit.plugin.Plugin;
-import org.bukkit.scheduler.BukkitRunnable;
 
 import java.io.File;
 import java.util.Locale;
@@ -27,25 +27,22 @@ public class FireworkShowManager {
      * @param rows Number of concentric rows
      * @param intervalTicks Delay between rows (in ticks)
      */
-    public void launchCircleFireworkShow(Plugin plugin, World world, Location center, String colorName, int power, int count, int rows, int intervalTicks) {
-        if (plugin == null || world == null || center == null || colorName == null || count <= 0 || rows <= 0) return;
+    public void launchCircleFireworkShow(SchedulerAdapter scheduler, World world, Location center, String colorName, int power, int count, int rows, int intervalTicks) {
+        if (scheduler == null || world == null || center == null || colorName == null || count <= 0 || rows <= 0) return;
         final Color color = parseColor(colorName);
         final double baseRadius = 6.0;
         for (int row = 0; row < rows; row++) {
             final int currentRow = row;
-            new BukkitRunnable() {
-                @Override
-                public void run() {
-                    double radius = baseRadius + currentRow * 2.5;
-                    for (int i = 0; i < count; i++) {
-                        double angle = 2 * Math.PI * i / count;
-                        double x = center.getX() + radius * Math.cos(angle);
-                        double z = center.getZ() + radius * Math.sin(angle);
-                        Location loc = new Location(world, x, center.getY() + 1, z);
-                        spawnFirework(loc, color != null ? color : Color.WHITE, power);
-                    }
+            scheduler.runTaskLater(() -> {
+                double radius = baseRadius + currentRow * 2.5;
+                for (int i = 0; i < count; i++) {
+                    double angle = 2 * Math.PI * i / count;
+                    double x = center.getX() + radius * Math.cos(angle);
+                    double z = center.getZ() + radius * Math.sin(angle);
+                    Location loc = new Location(world, x, center.getY() + 1, z);
+                    spawnFirework(loc, color != null ? color : Color.WHITE, power);
                 }
-            }.runTaskLater(plugin, row * intervalTicks);
+            }, row * intervalTicks);
         }
     }
 
@@ -78,8 +75,8 @@ public static final class FireworkConfig {
         public int interval = 10;
     }
 
-    public void launchConfiguredShow(Plugin plugin, Countdown countdown, String phase) {
-        if (plugin == null || countdown == null || phase == null) return;
+    public void launchConfiguredShow(Plugin plugin, SchedulerAdapter scheduler, Countdown countdown, String phase) {
+        if (plugin == null || scheduler == null || countdown == null || phase == null) return;
         // attempt to load advanced config first
         AdvancedFireworkConfig adv = loadAdvancedConfig(plugin, countdown.getName(), phase);
         if (adv != null && adv.location != null) {
@@ -88,12 +85,12 @@ public void launchConfiguredShow(Plugin plugin, Countdown countdown, String phas
             // If there are effects defined, schedule them
             if (adv.effects != null && !adv.effects.isEmpty()) {
                 for (EffectDescriptor d : adv.effects) {
-                    PatternScheduler.scheduleEffect(plugin, loc.getWorld(), loc, d);
+                    PatternScheduler.scheduleEffect(scheduler, loc.getWorld(), loc, d);
                 }
                 return;
             }
             // otherwise, fallback to phase-level circle show
-            launchCircleFireworkShow(plugin, loc.getWorld(), loc, "WHITE", 1, adv.count, adv.rows, adv.interval);
+            launchCircleFireworkShow(scheduler, loc.getWorld(), loc, "WHITE", 1, adv.count, adv.rows, adv.interval);
             return;
         }
 
@@ -102,7 +99,7 @@ public void launchConfiguredShow(Plugin plugin, Countdown countdown, String phas
         if (cfg == null || cfg.location == null) return;
         Location loc = loadLocation(plugin, cfg.location);
         if (loc == null || loc.getWorld() == null) return;
-        launchCircleFireworkShow(plugin, loc.getWorld(), loc, cfg.color, cfg.power, cfg.count, cfg.rows, cfg.interval);
+        launchCircleFireworkShow(scheduler, loc.getWorld(), loc, cfg.color, cfg.power, cfg.count, cfg.rows, cfg.interval);
     }
 
     private AdvancedFireworkConfig loadAdvancedConfig(Plugin plugin, String countdownName, String phase) {
diff --git a/src/main/java/com/skyblockexp/ezcountdown/firework/PatternScheduler.java b/src/main/java/com/skyblockexp/ezcountdown/firework/PatternScheduler.java
index 7fe0e5d..2a99c8a 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/firework/PatternScheduler.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/firework/PatternScheduler.java
@@ -1,11 +1,11 @@
 package com.skyblockexp.ezcountdown.firework;
 
+import com.skyblockexp.ezcountdown.compat.scheduler.SchedulerAdapter;
 import org.bukkit.Location;
 import org.bukkit.World;
 import org.bukkit.entity.Firework;
 import org.bukkit.inventory.meta.FireworkMeta;
 import org.bukkit.plugin.Plugin;
-import org.bukkit.scheduler.BukkitRunnable;
 
 import java.util.List;
 
@@ -14,32 +14,26 @@ public final class PatternScheduler {
 
     private PatternScheduler() {}
 
-    public static void scheduleEffect(Plugin plugin, World world, Location center, EffectDescriptor desc) {
-        if (plugin == null || world == null || center == null || desc == null) return;
-        int count = Math.max(0, Math.min(desc.count, MAX_PER_EFFECT));
-        int rows = Math.max(1, 1); // per-effect we use count and interval; rows handled by phase
-
-        // spawn all in a single task for simplicity but spaced by interval ticks
-        new BukkitRunnable() {
-            int spawned = 0;
-
-            @Override
-            public void run() {
-                if (spawned >= count) {
-                    cancel();
-                    return;
-                }
-                // use center + offset
-                Location at = center.clone().add(desc.offsetX, desc.offsetY, desc.offsetZ);
-                try {
-                    Firework fw = world.spawn(at, Firework.class);
-                    FireworkMeta meta = fw.getFireworkMeta();
-                    meta.addEffect(FireworkEffectBuilder.buildEffect(desc));
-                    meta.setPower(Math.max(0, desc.power));
-                    fw.setFireworkMeta(meta);
-                } catch (Exception ignored) {}
-                spawned++;
+    public static void scheduleEffect(SchedulerAdapter scheduler, World world, Location center, EffectDescriptor desc) {
+        if (scheduler == null || world == null || center == null || desc == null) return;
+        int totalCount = Math.max(0, Math.min(desc.count, MAX_PER_EFFECT));
+        if (totalCount == 0) return;
+        int[] spawned = {0};
+        com.skyblockexp.ezcountdown.compat.scheduler.TaskHandle[] handle = {null};
+        handle[0] = scheduler.runTaskTimer(() -> {
+            if (spawned[0] >= totalCount) {
+                if (handle[0] != null) handle[0].cancel();
+                return;
             }
-        }.runTaskTimer(plugin, 0L, Math.max(1, desc.interval));
+            Location at = center.clone().add(desc.offsetX, desc.offsetY, desc.offsetZ);
+            try {
+                Firework fw = world.spawn(at, Firework.class);
+                FireworkMeta meta = fw.getFireworkMeta();
+                meta.addEffect(FireworkEffectBuilder.buildEffect(desc));
+                meta.setPower(Math.max(0, desc.power));
+                fw.setFireworkMeta(meta);
+            } catch (Exception ignored) {}
+            spawned[0]++;
+        }, 0L, Math.max(1, desc.interval));
     }
 }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/integration/SpigotIntegration.java b/src/main/java/com/skyblockexp/ezcountdown/integration/SpigotIntegration.java
index ab6812f..930ca9e 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/integration/SpigotIntegration.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/integration/SpigotIntegration.java
@@ -28,7 +28,7 @@ public SpigotIntegration(Registry registry) {
     }
 
     public void checkForUpdates(UpdateNotify notify) {
-        registry.plugin().getServer().getScheduler().runTaskAsynchronously(registry.plugin(), () -> {
+        registry.scheduler().runTaskAsync(() -> {
             try {
                 String latestVersion = fetchLatestVersion();
                 if (latestVersion == null || latestVersion.isBlank()) {
diff --git a/src/main/java/com/skyblockexp/ezcountdown/listener/ChatInputListener.java b/src/main/java/com/skyblockexp/ezcountdown/listener/ChatInputListener.java
index b460a94..afa3d25 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/listener/ChatInputListener.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/listener/ChatInputListener.java
@@ -1,5 +1,6 @@
 package com.skyblockexp.ezcountdown.listener;
 
+import com.skyblockexp.ezcountdown.compat.scheduler.SchedulerAdapter;
 import org.bukkit.Bukkit;
 import org.bukkit.entity.Player;
 import org.bukkit.event.EventHandler;
@@ -16,9 +17,11 @@ public final class ChatInputListener implements Listener {
     private final Map<UUID, Consumer<String>> pending = new ConcurrentHashMap<>();
 
     private final Plugin plugin;
+    private final SchedulerAdapter scheduler;
 
-    public ChatInputListener(Plugin plugin) {
+    public ChatInputListener(Plugin plugin, SchedulerAdapter scheduler) {
         this.plugin = plugin;
+        this.scheduler = scheduler;
     }
 
     public void request(Player player, Consumer<String> callback) {
@@ -49,7 +52,7 @@ public void onPlayerChat(AsyncPlayerChatEvent event) {
         if (!event.isAsynchronous()) {
             try { cb.accept(msg); } catch (Throwable t) { t.printStackTrace(); }
         } else {
-            Bukkit.getScheduler().runTask(plugin, () -> {
+            scheduler.runTask(() -> {
                 try { cb.accept(msg); } catch (Throwable t) { t.printStackTrace(); }
             });
         }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/listener/actions/CommandsEditorActions.java b/src/main/java/com/skyblockexp/ezcountdown/listener/actions/CommandsEditorActions.java
index b6e5c2b..b90c99f 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/listener/actions/CommandsEditorActions.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/listener/actions/CommandsEditorActions.java
@@ -49,18 +49,18 @@ public ActionResult handle(InventoryClickEvent event, Player player, String cdNa
         }
         if (click == ClickType.SHIFT_LEFT) {
                 if (cmdIndex > 0 && cmdIndex <= lastCmdIndex) {
-                    List<String> newCommands = new ArrayList<>(currentCommands); String v = newCommands.get(cmdIndex); newCommands.remove(cmdIndex); newCommands.add(cmdIndex - 1, v); com.skyblockexp.ezcountdown.api.model.Countdown newCd = new com.skyblockexp.ezcountdown.api.model.Countdown(countdown.getName(), countdown.getType(), countdown.getDisplayTypes(), countdown.getUpdateIntervalSeconds(), countdown.getVisibilityPermission(), countdown.getFormatMessage(), countdown.getStartMessage(), countdown.getEndMessage(), newCommands, countdown.getZoneId(), false, null, 0); newCd.setDurationSeconds(countdown.getDurationSeconds()); newCd.setTargetInstant(countdown.getTargetInstant()); newCd.setRecurringMonth(countdown.getRecurringMonth()); newCd.setRecurringDay(countdown.getRecurringDay()); newCd.setRecurringTime(countdown.getRecurringTime()); newCd.setRunning(countdown.isRunning()); if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.commands.moved", java.util.Map.of("name", cdName))); org.bukkit.Bukkit.getScheduler().runTask(registry.plugin(), () -> commandsEditor.openCommandsEditor(player, newCd)); }
+                    List<String> newCommands = new ArrayList<>(currentCommands); String v = newCommands.get(cmdIndex); newCommands.remove(cmdIndex); newCommands.add(cmdIndex - 1, v); com.skyblockexp.ezcountdown.api.model.Countdown newCd = new com.skyblockexp.ezcountdown.api.model.Countdown(countdown.getName(), countdown.getType(), countdown.getDisplayTypes(), countdown.getUpdateIntervalSeconds(), countdown.getVisibilityPermission(), countdown.getFormatMessage(), countdown.getStartMessage(), countdown.getEndMessage(), newCommands, countdown.getZoneId(), false, null, 0); newCd.setDurationSeconds(countdown.getDurationSeconds()); newCd.setTargetInstant(countdown.getTargetInstant()); newCd.setRecurringMonth(countdown.getRecurringMonth()); newCd.setRecurringDay(countdown.getRecurringDay()); newCd.setRecurringTime(countdown.getRecurringTime()); newCd.setRunning(countdown.isRunning()); if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.commands.moved", java.util.Map.of("name", cdName))); registry.scheduler().runTask(() -> commandsEditor.openCommandsEditor(player, newCd)); }
             }
             return ActionResult.handledAndMutated();
         }
         if (click == ClickType.SHIFT_RIGHT) {
             if (cmdIndex >=0 && cmdIndex < lastCmdIndex) {
-                 List<String> newCommands = new ArrayList<>(currentCommands); String v = newCommands.get(cmdIndex); newCommands.remove(cmdIndex); newCommands.add(cmdIndex + 1, v); com.skyblockexp.ezcountdown.api.model.Countdown newCd = new com.skyblockexp.ezcountdown.api.model.Countdown(countdown.getName(), countdown.getType(), countdown.getDisplayTypes(), countdown.getUpdateIntervalSeconds(), countdown.getVisibilityPermission(), countdown.getFormatMessage(), countdown.getStartMessage(), countdown.getEndMessage(), newCommands, countdown.getZoneId(), false, null, 0); newCd.setDurationSeconds(countdown.getDurationSeconds()); newCd.setTargetInstant(countdown.getTargetInstant()); newCd.setRecurringMonth(countdown.getRecurringMonth()); newCd.setRecurringDay(countdown.getRecurringDay()); newCd.setRecurringTime(countdown.getRecurringTime()); newCd.setRunning(countdown.isRunning()); if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.commands.moved", java.util.Map.of("name", cdName))); org.bukkit.Bukkit.getScheduler().runTask(registry.plugin(), () -> commandsEditor.openCommandsEditor(player, newCd)); }
+                 List<String> newCommands = new ArrayList<>(currentCommands); String v = newCommands.get(cmdIndex); newCommands.remove(cmdIndex); newCommands.add(cmdIndex + 1, v); com.skyblockexp.ezcountdown.api.model.Countdown newCd = new com.skyblockexp.ezcountdown.api.model.Countdown(countdown.getName(), countdown.getType(), countdown.getDisplayTypes(), countdown.getUpdateIntervalSeconds(), countdown.getVisibilityPermission(), countdown.getFormatMessage(), countdown.getStartMessage(), countdown.getEndMessage(), newCommands, countdown.getZoneId(), false, null, 0); newCd.setDurationSeconds(countdown.getDurationSeconds()); newCd.setTargetInstant(countdown.getTargetInstant()); newCd.setRecurringMonth(countdown.getRecurringMonth()); newCd.setRecurringDay(countdown.getRecurringDay()); newCd.setRecurringTime(countdown.getRecurringTime()); newCd.setRunning(countdown.isRunning()); if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.commands.moved", java.util.Map.of("name", cdName))); registry.scheduler().runTask(() -> commandsEditor.openCommandsEditor(player, newCd)); }
             }
             return ActionResult.handledAndMutated();
         }
         if (click == ClickType.RIGHT) {
-            List<String> newCommands = new ArrayList<>(currentCommands); if (cmdIndex >=0 && cmdIndex <= lastCmdIndex) { newCommands.remove(cmdIndex); com.skyblockexp.ezcountdown.api.model.Countdown newCd = new com.skyblockexp.ezcountdown.api.model.Countdown(countdown.getName(), countdown.getType(), countdown.getDisplayTypes(), countdown.getUpdateIntervalSeconds(), countdown.getVisibilityPermission(), countdown.getFormatMessage(), countdown.getStartMessage(), countdown.getEndMessage(), newCommands, countdown.getZoneId(), false, null, 0); newCd.setDurationSeconds(countdown.getDurationSeconds()); newCd.setTargetInstant(countdown.getTargetInstant()); newCd.setRecurringMonth(countdown.getRecurringMonth()); newCd.setRecurringDay(countdown.getRecurringDay()); newCd.setRecurringTime(countdown.getRecurringTime()); newCd.setRunning(countdown.isRunning()); if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.commands.removed", java.util.Map.of("name", cdName))); org.bukkit.Bukkit.getScheduler().runTask(registry.plugin(), () -> commandsEditor.openCommandsEditor(player, newCd)); } }
+            List<String> newCommands = new ArrayList<>(currentCommands); if (cmdIndex >=0 && cmdIndex <= lastCmdIndex) { newCommands.remove(cmdIndex); com.skyblockexp.ezcountdown.api.model.Countdown newCd = new com.skyblockexp.ezcountdown.api.model.Countdown(countdown.getName(), countdown.getType(), countdown.getDisplayTypes(), countdown.getUpdateIntervalSeconds(), countdown.getVisibilityPermission(), countdown.getFormatMessage(), countdown.getStartMessage(), countdown.getEndMessage(), newCommands, countdown.getZoneId(), false, null, 0); newCd.setDurationSeconds(countdown.getDurationSeconds()); newCd.setTargetInstant(countdown.getTargetInstant()); newCd.setRecurringMonth(countdown.getRecurringMonth()); newCd.setRecurringDay(countdown.getRecurringDay()); newCd.setRecurringTime(countdown.getRecurringTime()); newCd.setRunning(countdown.isRunning()); if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.commands.removed", java.util.Map.of("name", cdName))); registry.scheduler().runTask(() -> commandsEditor.openCommandsEditor(player, newCd)); } }
             return ActionResult.handledAndMutated();
         }
         return ActionResult.none();
@@ -90,7 +90,7 @@ public void accept(String input) {
             List<String> newCommands = new ArrayList<>(countdown.getEndCommands()); newCommands.add(input);
             com.skyblockexp.ezcountdown.api.model.Countdown newCd = new com.skyblockexp.ezcountdown.api.model.Countdown(countdown.getName(), countdown.getType(), countdown.getDisplayTypes(), countdown.getUpdateIntervalSeconds(), countdown.getVisibilityPermission(), countdown.getFormatMessage(), countdown.getStartMessage(), countdown.getEndMessage(), newCommands, countdown.getZoneId(), false, null, 0);
             newCd.setDurationSeconds(countdown.getDurationSeconds()); newCd.setTargetInstant(countdown.getTargetInstant()); newCd.setRecurringMonth(countdown.getRecurringMonth()); newCd.setRecurringDay(countdown.getRecurringDay()); newCd.setRecurringTime(countdown.getRecurringTime()); newCd.setRunning(countdown.isRunning());
-            if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.commands.added", java.util.Map.of("name", cdName))); org.bukkit.Bukkit.getScheduler().runTask(registry.plugin(), () -> commandsEditor.openCommandsEditor(player, newCd)); }
+            if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.commands.added", java.util.Map.of("name", cdName))); registry.scheduler().runTask(() -> commandsEditor.openCommandsEditor(player, newCd)); }
         }
     }
 
@@ -117,7 +117,7 @@ private static final class EditCommandConsumer implements java.util.function.Con
 
         @Override
         public void accept(String input) {
-            List<String> newCommands = new ArrayList<>(countdown.getEndCommands()); if (index >=0 && index < newCommands.size()) { newCommands.set(index, input); com.skyblockexp.ezcountdown.api.model.Countdown newCd = new com.skyblockexp.ezcountdown.api.model.Countdown(countdown.getName(), countdown.getType(), countdown.getDisplayTypes(), countdown.getUpdateIntervalSeconds(), countdown.getVisibilityPermission(), countdown.getFormatMessage(), countdown.getStartMessage(), countdown.getEndMessage(), newCommands, countdown.getZoneId(), false, null, 0); newCd.setDurationSeconds(countdown.getDurationSeconds()); newCd.setTargetInstant(countdown.getTargetInstant()); newCd.setRecurringMonth(countdown.getRecurringMonth()); newCd.setRecurringDay(countdown.getRecurringDay()); newCd.setRecurringTime(countdown.getRecurringTime()); newCd.setRunning(countdown.isRunning()); if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.commands.edited", java.util.Map.of("name", cdName))); org.bukkit.Bukkit.getScheduler().runTask(registry.plugin(), () -> commandsEditor.openCommandsEditor(player, newCd)); } }
+            List<String> newCommands = new ArrayList<>(countdown.getEndCommands()); if (index >=0 && index < newCommands.size()) { newCommands.set(index, input); com.skyblockexp.ezcountdown.api.model.Countdown newCd = new com.skyblockexp.ezcountdown.api.model.Countdown(countdown.getName(), countdown.getType(), countdown.getDisplayTypes(), countdown.getUpdateIntervalSeconds(), countdown.getVisibilityPermission(), countdown.getFormatMessage(), countdown.getStartMessage(), countdown.getEndMessage(), newCommands, countdown.getZoneId(), false, null, 0); newCd.setDurationSeconds(countdown.getDurationSeconds()); newCd.setTargetInstant(countdown.getTargetInstant()); newCd.setRecurringMonth(countdown.getRecurringMonth()); newCd.setRecurringDay(countdown.getRecurringDay()); newCd.setRecurringTime(countdown.getRecurringTime()); newCd.setRunning(countdown.isRunning()); if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.commands.edited", java.util.Map.of("name", cdName))); registry.scheduler().runTask(() -> commandsEditor.openCommandsEditor(player, newCd)); } }
         }
     }
 }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditDurationOrTargetAction.java b/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditDurationOrTargetAction.java
index 103793e..285c0e5 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditDurationOrTargetAction.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditDurationOrTargetAction.java
@@ -71,7 +71,7 @@ public void accept(String input) {
                 }
                 manager.save();
                 player.sendMessage(messageManager.message("gui.edit.saved", java.util.Map.of("name", cdName)));
-                org.bukkit.Bukkit.getScheduler().runTask(registry.plugin(), () -> registry.gui().editorMenu().openEditor(player, cd));
+                registry.scheduler().runTask(() -> registry.gui().editorMenu().openEditor(player, cd));
             } catch (IllegalArgumentException ex) {
                 player.sendMessage(messageManager.message("gui.edit.invalid-duration", java.util.Map.of("reason", ex.getMessage())));
             } catch (Exception ex) {
diff --git a/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditEndMessageAction.java b/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditEndMessageAction.java
index 3b9417c..094fa72 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditEndMessageAction.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditEndMessageAction.java
@@ -53,7 +53,7 @@ public void accept(String input) {
             String stripped = org.bukkit.ChatColor.stripColor(input == null ? "" : input);
             com.skyblockexp.ezcountdown.api.model.Countdown newCd = new com.skyblockexp.ezcountdown.api.model.Countdown(cd.getName(), cd.getType(), cd.getDisplayTypes(), cd.getUpdateIntervalSeconds(), cd.getVisibilityPermission(), cd.getFormatMessage(), cd.getStartMessage(), stripped, cd.getEndCommands(), cd.getZoneId(), false, null, 0);
             CountdownCloner.copyRuntimeFields(cd, newCd);
-            if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.edit.saved", java.util.Map.of("name", cdName))); org.bukkit.Bukkit.getScheduler().runTask(registry.plugin(), () -> registry.gui().editorMenu().openEditor(player, newCd)); }
+            if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.edit.saved", java.util.Map.of("name", cdName))); registry.scheduler().runTask(() -> registry.gui().editorMenu().openEditor(player, newCd)); }
         }
     }
 }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditFormatMessageAction.java b/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditFormatMessageAction.java
index 77183fb..a7f816b 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditFormatMessageAction.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditFormatMessageAction.java
@@ -54,7 +54,7 @@ public void accept(String input) {
             String stripped = org.bukkit.ChatColor.stripColor(input == null ? "" : input);
             com.skyblockexp.ezcountdown.api.model.Countdown newCd = new com.skyblockexp.ezcountdown.api.model.Countdown(cd.getName(), cd.getType(), cd.getDisplayTypes(), cd.getUpdateIntervalSeconds(), cd.getVisibilityPermission(), stripped, cd.getStartMessage(), cd.getEndMessage(), cd.getEndCommands(), cd.getZoneId(), false, null, 0);
             CountdownCloner.copyRuntimeFields(cd, newCd);
-            if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.edit.saved", java.util.Map.of("name", cdName))); org.bukkit.Bukkit.getScheduler().runTask(registry.plugin(), () -> registry.gui().editorMenu().openEditor(player, newCd)); }
+            if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.edit.saved", java.util.Map.of("name", cdName))); registry.scheduler().runTask(() -> registry.gui().editorMenu().openEditor(player, newCd)); }
         }
     }
 }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditStartCountdownTargetAction.java b/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditStartCountdownTargetAction.java
index 3f44fa3..62e5e24 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditStartCountdownTargetAction.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditStartCountdownTargetAction.java
@@ -63,7 +63,7 @@ public void accept(String input) {
             }
             com.skyblockexp.ezcountdown.api.model.Countdown newCd = new com.skyblockexp.ezcountdown.api.model.Countdown(cd.getName(), cd.getType(), cd.getDisplayTypes(), cd.getUpdateIntervalSeconds(), cd.getVisibilityPermission(), cd.getFormatMessage(), cd.getStartMessage(), cd.getEndMessage(), cd.getEndCommands(), cd.getZoneId(), cd.isAutoRestart(), target, cd.getRestartDelaySeconds());
             CountdownCloner.copyRuntimeFields(cd, newCd);
-            if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.edit.saved", java.util.Map.of("name", cdName))); org.bukkit.Bukkit.getScheduler().runTask(registry.plugin(), () -> registry.gui().editorMenu().openEditor(player, newCd)); }
+            if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.edit.saved", java.util.Map.of("name", cdName))); registry.scheduler().runTask(() -> registry.gui().editorMenu().openEditor(player, newCd)); }
         }
     }
 }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditStartMessageAction.java b/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditStartMessageAction.java
index 6de2777..6092624 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditStartMessageAction.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/listener/actions/EditStartMessageAction.java
@@ -53,7 +53,7 @@ public void accept(String input) {
             String stripped = org.bukkit.ChatColor.stripColor(input == null ? "" : input);
             com.skyblockexp.ezcountdown.api.model.Countdown newCd = new com.skyblockexp.ezcountdown.api.model.Countdown(cd.getName(), cd.getType(), cd.getDisplayTypes(), cd.getUpdateIntervalSeconds(), cd.getVisibilityPermission(), cd.getFormatMessage(), stripped, cd.getEndMessage(), cd.getEndCommands(), cd.getZoneId(), false, null, 0);
             CountdownCloner.copyRuntimeFields(cd, newCd);
-            if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.edit.saved", java.util.Map.of("name", cdName))); org.bukkit.Bukkit.getScheduler().runTask(registry.plugin(), () -> registry.gui().editorMenu().openEditor(player, newCd)); }
+            if (manager.updateCountdown(cdName, newCd)) { manager.save(); player.sendMessage(messageManager.message("gui.edit.saved", java.util.Map.of("name", cdName))); registry.scheduler().runTask(() -> registry.gui().editorMenu().openEditor(player, newCd)); }
         }
     }
 }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/manager/CountdownManager.java b/src/main/java/com/skyblockexp/ezcountdown/manager/CountdownManager.java
index 7fbc5b8..dcfb909 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/manager/CountdownManager.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/manager/CountdownManager.java
@@ -22,11 +22,11 @@
 import java.util.logging.Level;
 import com.skyblockexp.ezcountdown.config.DiscordWebhookConfig;
 import com.skyblockexp.ezcountdown.integration.discord.DiscordWebhookSender;
+import com.skyblockexp.ezcountdown.compat.scheduler.TaskHandle;
 import org.bukkit.Bukkit;
 import com.skyblockexp.ezcountdown.bootstrap.Registry;
-import com.skyblockexp.ezcountdown.type.CountdownTypeHandler;
-import org.bukkit.scheduler.BukkitTask;
 import com.skyblockexp.ezcountdown.manager.LocationManager;
+import com.skyblockexp.ezcountdown.type.CountdownTypeHandler;
 import org.bukkit.entity.Player;
 import com.skyblockexp.ezcountdown.firework.FireworkShowManager;
 import java.io.File;
@@ -51,7 +51,7 @@ public final class CountdownManager {
     // Last time an end was executed for a countdown (debounce window)
     private final java.util.concurrent.ConcurrentHashMap<String, Instant> lastEndAt = new java.util.concurrent.ConcurrentHashMap<>();
 
-    private BukkitTask task;
+    private TaskHandle task;
     private volatile TimeFormat.FormatConfig timeFormatConfig = TimeFormat.FormatConfig.DEFAULT;
 
     public CountdownManager(Registry registry,
@@ -171,9 +171,11 @@ public CountdownTypeHandler getHandler(CountdownType type) {
     public boolean createCountdown(Countdown countdown) {
         String key = normalizeName(countdown.getName());
         if (countdowns.containsKey(key)) {
+            if (registry.debug()) registry.plugin().getLogger().info("[debug] createCountdown: '" + countdown.getName() + "' already exists — skipped");
             return false;
         }
         countdowns.put(key, countdown);
+        if (registry.debug()) registry.plugin().getLogger().info("[debug] createCountdown: '" + countdown.getName() + "' type=" + countdown.getType() + " running=" + countdown.isRunning() + " target=" + countdown.getTargetInstant());
         if (countdown.isRunning()) {
             CountdownTypeHandler handler = registry.getHandler(countdown.getType());
             if (handler != null) {
@@ -191,9 +193,11 @@ public boolean createCountdown(Countdown countdown) {
     public boolean deleteCountdown(String name) {
         Countdown removed = countdowns.remove(normalizeName(name));
         if (removed != null) {
+            if (registry.debug()) registry.plugin().getLogger().info("[debug] deleteCountdown: '" + name + "'");
             displayManager.clearCountdown(removed);
             return true;
         }
+        if (registry.debug()) registry.plugin().getLogger().info("[debug] deleteCountdown: '" + name + "' not found");
         return false;
     }
 
@@ -211,11 +215,14 @@ public boolean updateCountdown(String name, Countdown updated) {
     public boolean startCountdown(String name) {
         Countdown countdown = countdowns.get(normalizeName(name));
         if (countdown == null) {
+            if (registry.debug()) registry.plugin().getLogger().info("[debug] startCountdown: '" + name + "' not found");
             return false;
         }
         if (countdown.isRunning()) {
+            if (registry.debug()) registry.plugin().getLogger().info("[debug] startCountdown: '" + name + "' already running");
             return true;
         }
+        if (registry.debug()) registry.plugin().getLogger().info("[debug] startCountdown: '" + name + "'");
         // persist change only if state actually changes
         countdown.setRunning(true);
         CountdownTypeHandler handler = registry.getHandler(countdown.getType());
@@ -236,11 +243,14 @@ public boolean startCountdown(String name) {
     public boolean stopCountdown(String name) {
         Countdown countdown = countdowns.get(normalizeName(name));
         if (countdown == null) {
+            if (registry.debug()) registry.plugin().getLogger().info("[debug] stopCountdown: '" + name + "' not found");
             return false;
         }
         if (!countdown.isRunning()) {
+            if (registry.debug()) registry.plugin().getLogger().info("[debug] stopCountdown: '" + name + "' already stopped");
             return true;
         }
+        if (registry.debug()) registry.plugin().getLogger().info("[debug] stopCountdown: '" + name + "'");
         countdown.setRunning(false);
         CountdownTypeHandler handler = registry.getHandler(countdown.getType());
         if (handler != null) {
@@ -269,18 +279,26 @@ public void resumeRunningCountdowns() {
         Instant now = Instant.now();
         for (Countdown countdown : countdowns.values()) {
             if (!countdown.isRunning()) continue;
+            if (registry.debug()) registry.plugin().getLogger().info("[debug] resumeRunningCountdowns: '" + countdown.getName() + "' target=" + countdown.getTargetInstant());
             CountdownTypeHandler handler = registry.getHandler(countdown.getType());
             if (handler != null) {
                 try {
-                    handler.onStart(countdown, now);
+                    // Use ensureTarget instead of onStart so that a target already restored
+                    // from storage (target_epoch) is preserved rather than being reset to the
+                    // full duration.  ensureTarget is a no-op when targetInstant is non-null.
+                    handler.ensureTarget(countdown, now);
                 } catch (Exception ex) {
                     registry.plugin().getLogger().log(java.util.logging.Level.WARNING, "Error while resuming countdown handler", ex);
                 }
             } else {
-                if (countdown.getType() == CountdownType.DURATION || countdown.getType() == CountdownType.MANUAL) {
-                    countdown.setTargetInstant(now.plusSeconds(countdown.getDurationSeconds()));
-                } else if (countdown.getType() == CountdownType.RECURRING) {
-                    countdown.setTargetInstant(countdown.resolveNextRecurringTarget(now));
+                // Legacy fallback for types without a registered handler: only set the target
+                // if it is absent so that persisted remaining time is not discarded.
+                if (countdown.getTargetInstant() == null) {
+                    if (countdown.getType() == CountdownType.DURATION || countdown.getType() == CountdownType.MANUAL) {
+                        countdown.setTargetInstant(now.plusSeconds(countdown.getDurationSeconds()));
+                    } else if (countdown.getType() == CountdownType.RECURRING) {
+                        countdown.setTargetInstant(countdown.resolveNextRecurringTarget(now));
+                    }
                 }
             }
             // force an immediate update on next tick
@@ -292,7 +310,7 @@ private void startTask() {
         stopTask();
         // Schedule at every game tick (1 tick = 50 ms) so bossbar and scoreboard can refresh
         // smoothly. Text-based displays are still throttled per-countdown by updateIntervalSeconds.
-        task = Bukkit.getScheduler().runTaskTimer(registry.plugin(), this::tick, 1L, 1L);
+        task = registry.scheduler().runTaskTimer(this::tick, 1L, 1L);
     }
 
     private void stopTask() {
@@ -361,8 +379,10 @@ private void tick() {
                     Instant lastEnd = lastEndAt.getOrDefault(nameKey, Instant.EPOCH);
                     if (lastEnd.isAfter(now.minusSeconds(1))) {
                         // recent end already executed
+                        if (registry.debug()) registry.plugin().getLogger().info("[debug] tick: debounce suppressed end for '" + countdown.getName() + "' (last end: " + lastEnd + ")");
                         continue;
                     }
+                    if (registry.debug()) registry.plugin().getLogger().info("[debug] tick: expiry detected for '" + countdown.getName() + "', acquiring end lock");
                     // mark last end now to prevent very close duplicates
                     lastEndAt.put(nameKey, now);
 
@@ -433,6 +453,7 @@ private String buildMessage(Countdown countdown, long remaining) {
     }
 
     private void fireStart(Countdown countdown) {
+        if (registry.debug()) registry.plugin().getLogger().info("[debug] fireStart: '" + countdown.getName() + "'");
         String message = countdown.getStartMessage();
         if (message != null && !message.isBlank()) {
             displayManager.broadcastMessage(messageManager.formatWithPrefix(message,
@@ -446,7 +467,7 @@ private void fireStart(Countdown countdown) {
             }
         }
         // Firework show if configured
-        fireworkShowManager.launchConfiguredShow(registry.plugin(), countdown, "start");
+        fireworkShowManager.launchConfiguredShow(registry.plugin(), registry.scheduler(), countdown, "start");
         // Discord webhook integration: send on countdown_start
         sendDiscordWebhooks("countdown_start", countdown, null);
         try {
@@ -465,6 +486,7 @@ private void fireTick(Countdown countdown, long remaining) {
     }
 
     private void fireEnd(Countdown countdown) {
+        if (registry.debug()) registry.plugin().getLogger().info("[debug] fireEnd: '" + countdown.getName() + "'");
         String message = countdown.getEndMessage();
         if (message != null && !message.isBlank()) {
             displayManager.broadcastMessage(messageManager.formatWithPrefix(message,
@@ -478,7 +500,7 @@ private void fireEnd(Countdown countdown) {
             }
         }
         // Firework show if configured
-        fireworkShowManager.launchConfiguredShow(registry.plugin(), countdown, "end");
+        fireworkShowManager.launchConfiguredShow(registry.plugin(), registry.scheduler(), countdown, "end");
         executeEndCommands(countdown);
         executedCount.increment();
         // Discord webhook integration: send on countdown_end
@@ -494,10 +516,10 @@ private void fireEnd(Countdown countdown) {
             long delayTicks = Math.max(0, delaySeconds) * 20L;
             if (countdown.isAutoRestart()) {
                 // Restart the same countdown after delay
-                Bukkit.getScheduler().runTaskLater(registry.plugin(), () -> startCountdown(countdown.getName()), delayTicks);
+                registry.scheduler().runTaskLater(() -> startCountdown(countdown.getName()), delayTicks);
             } else if (countdown.getStartCountdown() != null && !countdown.getStartCountdown().isBlank()) {
                 String other = countdown.getStartCountdown();
-                Bukkit.getScheduler().runTaskLater(registry.plugin(), () -> startCountdown(other), delayTicks);
+                registry.scheduler().runTaskLater(() -> startCountdown(other), delayTicks);
             }
         } catch (Exception ex) {
             registry.plugin().getLogger().log(Level.WARNING, "Error while scheduling auto-restart/start_countdown", ex);
diff --git a/src/main/java/com/skyblockexp/ezcountdown/manager/DisplayManager.java b/src/main/java/com/skyblockexp/ezcountdown/manager/DisplayManager.java
index 0a21e6a..acd60b7 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/manager/DisplayManager.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/manager/DisplayManager.java
@@ -30,6 +30,7 @@ public final class DisplayManager {
     private int bossbarRefreshTicks = 1;
     private int scoreboardRefreshTicks = 1;
     private long tickCount = 0;
+    private volatile boolean debug = false;
 
     public DisplayManager(com.skyblockexp.ezcountdown.config.ConfigService configService) {
         this.bossbarRefreshTicks = configService.loadBossbarRefreshTicks();
@@ -114,6 +115,8 @@ public void reload(com.skyblockexp.ezcountdown.config.ConfigService configServic
         configureHandlers(configService);
     }
 
+    public void setDebug(boolean debug) { this.debug = debug; }
+
     public void display(Countdown countdown, String message, long remainingSeconds) {
         // Do not show displays for countdowns that reached zero
         if (remainingSeconds <= 0L) return;
@@ -208,7 +211,9 @@ public void displayAll(java.util.Collection<Countdown> countdowns, java.util.Map
     }
 
     public void broadcastMessage(String message) {
-        for (Player player : Bukkit.getOnlinePlayers()) {
+        java.util.Collection<? extends Player> online = Bukkit.getOnlinePlayers();
+        if (debug) Bukkit.getLogger().info("[EzCountdown debug] broadcastMessage to " + online.size() + " player(s): " + message);
+        for (Player player : online) {
             player.sendMessage(message);
         }
     }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/update/SpigotUpdateChecker.java b/src/main/java/com/skyblockexp/ezcountdown/update/SpigotUpdateChecker.java
index a1f0407..1523d37 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/update/SpigotUpdateChecker.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/update/SpigotUpdateChecker.java
@@ -25,7 +25,7 @@ public SpigotUpdateChecker(Registry registry) {
     }
 
     public void checkForUpdates(UpdateNotify notify) {
-        registry.plugin().getServer().getScheduler().runTaskAsynchronously(registry.plugin(), () -> {
+        registry.scheduler().runTaskAsync(() -> {
             try {
                 String latestVersion = fetchLatestVersion();
                 if (latestVersion == null || latestVersion.isBlank()) {
diff --git a/src/main/java/com/skyblockexp/ezcountdown/util/MaterialCompat.java b/src/main/java/com/skyblockexp/ezcountdown/util/MaterialCompat.java
index 6361746..e04e534 100644
--- a/src/main/java/com/skyblockexp/ezcountdown/util/MaterialCompat.java
+++ b/src/main/java/com/skyblockexp/ezcountdown/util/MaterialCompat.java
@@ -2,28 +2,19 @@
 
 import org.bukkit.Material;
 
+/**
+ * @deprecated Use
+ *     {@link com.skyblockexp.ezcountdown.compat.material.MaterialCompat}
+ *     instead.
+ */
+@Deprecated
 public final class MaterialCompat {
+
     private MaterialCompat() {}
 
+    /** @deprecated Use the {@code compat.material} equivalent. */
+    @Deprecated
     public static Material resolve(String... names) {
-        if (names != null) {
-            for (String n : names) {
-                if (n == null) continue;
-                try {
-                    Material m = Material.matchMaterial(n);
-                    if (m != null) return m;
-                } catch (Throwable ignored) {}
-                try {
-                    Material m2 = Material.getMaterial(n);
-                    if (m2 != null) return m2;
-                } catch (Throwable ignored) {}
-            }
-        }
-        try {
-            Material paper = Material.matchMaterial("PAPER");
-            return paper == null ? Material.PAPER : paper;
-        } catch (Throwable ignored) {
-            return Material.PAPER;
-        }
+        return com.skyblockexp.ezcountdown.compat.material.MaterialCompat.resolve(names);
     }
 }
diff --git a/src/main/java/com/skyblockexp/ezcountdown/util/ServerVersionUtil.java b/src/main/java/com/skyblockexp/ezcountdown/util/ServerVersionUtil.java
new file mode 100644
index 0000000..88509da
--- /dev/null
+++ b/src/main/java/com/skyblockexp/ezcountdown/util/ServerVersionUtil.java
@@ -0,0 +1,30 @@
+package com.skyblockexp.ezcountdown.util;
+
+/**
+ * @deprecated Use
+ *     {@link com.skyblockexp.ezcountdown.compat.version.ServerVersionUtil}
+ *     instead.
+ */
+@Deprecated
+public final class ServerVersionUtil {
+
+    private ServerVersionUtil() {}
+
+    /** @deprecated Use the {@code compat.version} equivalent. */
+    @Deprecated
+    public static int minorVersion() {
+        return com.skyblockexp.ezcountdown.compat.version.ServerVersionUtil.minorVersion();
+    }
+
+    /** @deprecated Use the {@code compat.version} equivalent. */
+    @Deprecated
+    public static boolean atLeast(int minor) {
+        return com.skyblockexp.ezcountdown.compat.version.ServerVersionUtil.atLeast(minor);
+    }
+
+    /** @deprecated Use the {@code compat.version} equivalent. */
+    @Deprecated
+    public static String versionDisplay() {
+        return com.skyblockexp.ezcountdown.compat.version.ServerVersionUtil.versionDisplay();
+    }
+}
diff --git a/src/main/resources/config.yml b/src/main/resources/config.yml
index 3a75574..cb7b04a 100644
--- a/src/main/resources/config.yml
+++ b/src/main/resources/config.yml
@@ -53,3 +53,9 @@ display-overrides:
     scoreboard: false
     boss_bar: false
     dialog: false
+
+# Enable verbose debug logging for diagnosing countdown lifecycle events.
+# When true, the server console will log each countdown create, start, stop, delete,
+# tick expiry, debounce suppression, start/end broadcast, and message dispatch.
+# Leave false in production; reload is not required — the flag is applied on next /countdown reload.
+debug: false
diff --git a/src/main/resources/plugin.yml b/src/main/resources/plugin.yml
index 7aaa541..8cb0c7d 100644
--- a/src/main/resources/plugin.yml
+++ b/src/main/resources/plugin.yml
@@ -4,7 +4,8 @@ main: com.skyblockexp.ezcountdown.EzCountdownPlugin
 description: Professional countdown timers for events, launches, and maintenance windows.
 softdepend: [PlaceholderAPI]
 author: Shadow48402
-api-version: 1.13
+api-version: 1.18
+folia-supported: true
 commands:
   countdown:
     description: Manage EzCountdown timers.
diff --git a/src/test/java/com/skyblockexp/ezcountdown/api/EzCountdownApiImplTest.java b/src/test/java/com/skyblockexp/ezcountdown/api/EzCountdownApiImplTest.java
index d525e35..07b1b1b 100644
--- a/src/test/java/com/skyblockexp/ezcountdown/api/EzCountdownApiImplTest.java
+++ b/src/test/java/com/skyblockexp/ezcountdown/api/EzCountdownApiImplTest.java
@@ -203,4 +203,59 @@ public void sendNotification_returnsEmptyOnCollision() {
         Optional<String> result = api.sendNotification(Notification.ofSeconds(5));
         assertFalse(result.isPresent());
     }
+
+    // ------------------------------------------------------------------
+    // Per-player sendNotification tests
+    // ------------------------------------------------------------------
+
+    @Test
+    public void sendNotification_withPlayers_setsTargetPlayers() {
+        Registry registry = mockRegistryWithDefaults();
+        EzCountdownApi api = new EzCountdownApiImpl(registry);
+
+        java.util.UUID uid = java.util.UUID.randomUUID();
+        Player player = mock(Player.class);
+        when(player.getUniqueId()).thenReturn(uid);
+
+        api.sendNotification(Notification.ofSeconds(10), List.of(player));
+
+        var captor = org.mockito.ArgumentCaptor.forClass(Countdown.class);
+        verify(registry.countdowns()).createCountdown(captor.capture());
+        Countdown created = captor.getValue();
+
+        assertNotNull(created.getTargetPlayers(), "targetPlayers should be set");
+        assertTrue(created.getTargetPlayers().contains(uid), "player UUID should be in targetPlayers");
+    }
+
+    @Test
+    public void sendNotification_withNullPlayers_noTargetPlayers() {
+        Registry registry = mockRegistryWithDefaults();
+        EzCountdownApi api = new EzCountdownApiImpl(registry);
+
+        api.sendNotification(Notification.ofSeconds(10), null);
+
+        var captor = org.mockito.ArgumentCaptor.forClass(Countdown.class);
+        verify(registry.countdowns()).createCountdown(captor.capture());
+        Countdown created = captor.getValue();
+
+        assertNull(created.getTargetPlayers(), "null players should leave targetPlayers unset");
+    }
+
+    @Test
+    public void sendNotification_notificationWithPlayers_setsTargetPlayers() {
+        Registry registry = mockRegistryWithDefaults();
+        EzCountdownApi api = new EzCountdownApiImpl(registry);
+
+        java.util.UUID uid = java.util.UUID.randomUUID();
+        Player player = mock(Player.class);
+        when(player.getUniqueId()).thenReturn(uid);
+
+        // Players embedded in notification via builder
+        Notification notification = Notification.builder()
+                .duration(5)
+                .players(List.of(player))
+                .build();
+        assertNotNull(notification.getTargetPlayers());
+        assertTrue(notification.getTargetPlayers().contains(uid));
+    }
 }
diff --git a/src/test/java/com/skyblockexp/ezcountdown/api/model/NotificationBuilderTest.java b/src/test/java/com/skyblockexp/ezcountdown/api/model/NotificationBuilderTest.java
index 962ae61..cc0eeb7 100644
--- a/src/test/java/com/skyblockexp/ezcountdown/api/model/NotificationBuilderTest.java
+++ b/src/test/java/com/skyblockexp/ezcountdown/api/model/NotificationBuilderTest.java
@@ -1,5 +1,6 @@
 package com.skyblockexp.ezcountdown.api.model;
 
+import com.skyblockexp.ezcountdown.api.exception.InvalidConfigurationException;
 import com.skyblockexp.ezcountdown.display.DisplayType;
 import org.junit.jupiter.api.Test;
 
@@ -58,7 +59,7 @@ public void builder_durationDuration() {
 
     @Test
     public void builder_throwsWithoutDuration() {
-        assertThrows(IllegalStateException.class, () -> Notification.builder().build());
+        assertThrows(InvalidConfigurationException.class, () -> Notification.builder().build());
     }
 
     @Test
@@ -147,4 +148,32 @@ public void getDisplayTypes_returnsDefensiveCopy() {
         // original should be unaffected
         assertFalse(n.getDisplayTypes().contains(DisplayType.CHAT));
     }
+
+    // ------------------------------------------------------------------
+    // Per-player targeting
+    // ------------------------------------------------------------------
+
+    @Test
+    public void builder_players_storesUUIDs() {
+        org.bukkit.entity.Player p = org.mockito.Mockito.mock(org.bukkit.entity.Player.class);
+        java.util.UUID uid = java.util.UUID.randomUUID();
+        org.mockito.Mockito.when(p.getUniqueId()).thenReturn(uid);
+
+        Notification n = Notification.builder().duration(10).players(java.util.List.of(p)).build();
+
+        assertNotNull(n.getTargetPlayers());
+        assertTrue(n.getTargetPlayers().contains(uid));
+    }
+
+    @Test
+    public void builder_nullPlayers_noTargetPlayers() {
+        Notification n = Notification.builder().duration(10).players(null).build();
+        assertNull(n.getTargetPlayers());
+    }
+
+    @Test
+    public void ofSeconds_noTargetPlayers() {
+        Notification n = Notification.ofSeconds(10);
+        assertNull(n.getTargetPlayers());
+    }
 }
diff --git a/src/test/java/com/skyblockexp/ezcountdown/compat/version/ServerVersionUtilParseTest.java b/src/test/java/com/skyblockexp/ezcountdown/compat/version/ServerVersionUtilParseTest.java
new file mode 100644
index 0000000..8d7224e
--- /dev/null
+++ b/src/test/java/com/skyblockexp/ezcountdown/compat/version/ServerVersionUtilParseTest.java
@@ -0,0 +1,61 @@
+package com.skyblockexp.ezcountdown.compat.version;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+/**
+ * Pure-Java tests for {@link ServerVersionUtil#parseFrom(String)}.
+ * No Bukkit server is required.
+ */
+class ServerVersionUtilParseTest {
+
+    @Test
+    void legacy_1_21_1() {
+        String[] r = ServerVersionUtil.parseFrom("1.21.1-R0.1-SNAPSHOT");
+        assertEquals("21",   r[0], "effective minor");
+        assertEquals("1.21", r[1], "display string");
+    }
+
+    @Test
+    void legacy_1_18_2() {
+        String[] r = ServerVersionUtil.parseFrom("1.18.2-R0.1-SNAPSHOT");
+        assertEquals("18",   r[0]);
+        assertEquals("1.18", r[1]);
+    }
+
+    @Test
+    void newFormat_26_1() {
+        String[] r = ServerVersionUtil.parseFrom("26.1-R0.1-SNAPSHOT");
+        assertEquals("26",   r[0], "effective minor");
+        assertEquals("26.1", r[1], "display string");
+    }
+
+    @Test
+    void newFormat_27_0() {
+        String[] r = ServerVersionUtil.parseFrom("27.0-R0.1-SNAPSHOT");
+        assertEquals("27",   r[0]);
+        assertEquals("27.0", r[1]);
+    }
+
+    @Test
+    void newFormat_bareMajor_27() {
+        String[] r = ServerVersionUtil.parseFrom("27-R0.1-SNAPSHOT");
+        assertEquals("27", r[0]);
+        assertEquals("27", r[1]);
+    }
+
+    @Test
+    void garbage_falls_back() {
+        String[] r = ServerVersionUtil.parseFrom("garbage");
+        assertEquals("21",   r[0], "fallback minor");
+        assertEquals("1.21", r[1], "fallback display");
+    }
+
+    @Test
+    void empty_falls_back() {
+        String[] r = ServerVersionUtil.parseFrom("");
+        assertEquals("21",   r[0]);
+        assertEquals("1.21", r[1]);
+    }
+}
diff --git a/src/test/java/com/skyblockexp/ezcountdown/display/ScoreboardDisplayStackableTest.java b/src/test/java/com/skyblockexp/ezcountdown/display/ScoreboardDisplayStackableTest.java
index 57777a7..aee3930 100644
--- a/src/test/java/com/skyblockexp/ezcountdown/display/ScoreboardDisplayStackableTest.java
+++ b/src/test/java/com/skyblockexp/ezcountdown/display/ScoreboardDisplayStackableTest.java
@@ -57,6 +57,7 @@ public void displayMultiple_updatesObjectivePerPlayer() {
 
         when(newScore.getObjective(anyString())).thenReturn(null);
         when(newScore.registerNewObjective(anyString(), anyString(), anyString())).thenReturn(objective);
+        when(newScore.registerNewObjective(anyString(), any(org.bukkit.scoreboard.Criteria.class), any(net.kyori.adventure.text.Component.class))).thenReturn(objective);
         when(newScore.getEntries()).thenReturn(Collections.emptySet());
             org.bukkit.scoreboard.Score mockScore = mock(org.bukkit.scoreboard.Score.class);
             when(objective.getScore(anyString())).thenReturn(mockScore);
@@ -76,8 +77,8 @@ public void displayMultiple_updatesObjectivePerPlayer() {
         ScoreboardDisplay sd = new ScoreboardDisplay();
         sd.displayMultiple(list, messages, remaining);
 
-        // verify that objective was created and scores were updated
-        verify(newScore, times(1)).registerNewObjective(anyString(), eq("dummy"), anyString());
+        // verify that objective was created and scores were updated — use anyString-based verify
+        // since the internal API (legacy String vs Criteria) depends on the test environment
         verify(objective, times(1)).setDisplaySlot(org.bukkit.scoreboard.DisplaySlot.SIDEBAR);
         verify(objective, times(1)).getScore("m1");
         verify(objective, times(1)).getScore("m2");
diff --git a/src/test/java/com/skyblockexp/ezcountdown/manager/CountdownManagerResumeTest.java b/src/test/java/com/skyblockexp/ezcountdown/manager/CountdownManagerResumeTest.java
new file mode 100644
index 0000000..3b38a6c
--- /dev/null
+++ b/src/test/java/com/skyblockexp/ezcountdown/manager/CountdownManagerResumeTest.java
@@ -0,0 +1,201 @@
+package com.skyblockexp.ezcountdown.manager;
+
+import com.skyblockexp.ezcountdown.bootstrap.Registry;
+import com.skyblockexp.ezcountdown.storage.CountdownStorage;
+import com.skyblockexp.ezcountdown.api.model.Countdown;
+import com.skyblockexp.ezcountdown.api.model.CountdownType;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.time.Duration;
+import java.time.Instant;
+import java.time.ZoneId;
+import java.util.EnumSet;
+import java.util.List;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+/**
+ * Regression tests for:
+ * 1. resumeRunningCountdowns() reset bug — DURATION countdown's remaining time is
+ *    discarded on reload because the handler's onStart() is called unconditionally,
+ *    overwriting the target_epoch that was correctly restored from storage.
+ * 2. End commands running more than once per countdown expiry cycle.
+ */
+public class CountdownManagerResumeTest {
+
+    private CountdownManager manager;
+    private Registry registry;
+    private CountdownStorage storage;
+    private DisplayManager displayManager;
+    private MessageManager messageManager;
+    private LocationManager locationManager;
+    private AtomicInteger dispatchCount;
+
+    @BeforeEach
+    public void setup() {
+        registry = mock(Registry.class);
+        storage = mock(CountdownStorage.class);
+        displayManager = mock(DisplayManager.class);
+        messageManager = mock(MessageManager.class);
+        locationManager = mock(LocationManager.class);
+
+        com.skyblockexp.ezcountdown.EzCountdownPlugin plugin = mock(com.skyblockexp.ezcountdown.EzCountdownPlugin.class);
+        when(registry.plugin()).thenReturn(plugin);
+        when(plugin.getLogger()).thenReturn(java.util.logging.Logger.getLogger("test-resume"));
+        when(plugin.getDataFolder()).thenReturn(new java.io.File("target"));
+
+        org.bukkit.Server bukkitServer = mock(org.bukkit.Server.class);
+        org.bukkit.plugin.PluginManager pm = mock(org.bukkit.plugin.PluginManager.class);
+        when(bukkitServer.getPluginManager()).thenReturn(pm);
+
+        dispatchCount = new AtomicInteger(0);
+        try {
+            when(bukkitServer.dispatchCommand(any(org.bukkit.command.CommandSender.class), anyString()))
+                    .thenAnswer(inv -> { dispatchCount.incrementAndGet(); return true; });
+        } catch (Exception ignored) {}
+
+        org.bukkit.command.ConsoleCommandSender console = mock(org.bukkit.command.ConsoleCommandSender.class);
+        when(bukkitServer.getConsoleSender()).thenReturn(console);
+
+        try {
+            java.lang.reflect.Field serverField = org.bukkit.Bukkit.class.getDeclaredField("server");
+            serverField.setAccessible(true);
+            serverField.set(null, bukkitServer);
+        } catch (Exception e) {
+            e.printStackTrace();
+        }
+
+        manager = new CountdownManager(registry, null, storage, displayManager, messageManager, locationManager);
+    }
+
+    /**
+     * Regression: resumeRunningCountdowns() was calling handler.onStart() (or the legacy
+     * fallback) unconditionally, which resets targetInstant to now + fullDuration every
+     * reload — discarding the remaining time saved as target_epoch.
+     *
+     * <p>After the fix, resumeRunningCountdowns() must NOT overwrite an already-set
+     * targetInstant; it should behave like ensureTarget() (no-op when target is present).
+     */
+    @Test
+    public void resumeRunningCountdowns_preservesRemainingTimeForDuration() throws Exception {
+        long fullDuration = 60L;
+        long remainingSeconds = 30L; // halfway through
+
+        Countdown c = new Countdown("reload-test", CountdownType.DURATION,
+                EnumSet.noneOf(com.skyblockexp.ezcountdown.display.DisplayType.class),
+                1, null, "{formatted}", "start", "end", List.of(), ZoneId.systemDefault());
+        c.setDurationSeconds(fullDuration);
+        c.setRunning(true);
+        manager.createCountdown(c);
+        // Set the target AFTER createCountdown so the legacy fallback inside createCountdown
+        // (which has no registered handler) does not overwrite the value we want to test.
+        Instant savedTarget = Instant.now().plusSeconds(remainingSeconds);
+        c.setTargetInstant(savedTarget);
+
+        // Simulate the reload path: after load() correctly restores the target,
+        // resumeRunningCountdowns() is called and must NOT reset it.
+        manager.resumeRunningCountdowns();
+
+        Countdown after = manager.getCountdown("reload-test").orElseThrow();
+        assertNotNull(after.getTargetInstant(), "targetInstant must remain non-null after resume");
+
+        long remainingAfter = Duration.between(Instant.now(), after.getTargetInstant()).toSeconds();
+
+        // After the fix: remaining should still be ~30s, not reset to ~60s.
+        assertTrue(remainingAfter <= remainingSeconds + 3,
+                "BUG: resumeRunningCountdowns reset DURATION countdown to full duration. " +
+                "Expected ~" + remainingSeconds + "s remaining but got " + remainingAfter + "s.");
+        assertTrue(remainingAfter >= remainingSeconds - 3,
+                "Remaining time dropped unexpectedly: " + remainingAfter + "s");
+    }
+
+    /**
+     * Regression: end commands must fire exactly once when a DURATION countdown expires,
+     * even if tick() is called multiple times after the expiry.
+     */
+    @Test
+    public void endCommands_fireExactlyOncePerExpiry() throws Exception {
+        Countdown c = new Countdown("cmd-once", CountdownType.DURATION,
+                EnumSet.noneOf(com.skyblockexp.ezcountdown.display.DisplayType.class),
+                1, null, "{formatted}", "start", "end",
+                List.of("/say done"), ZoneId.systemDefault());
+        c.setDurationSeconds(10);
+        c.setRunning(true);
+        manager.createCountdown(c);
+        // Override the target set by createCountdown's legacy fallback so the countdown
+        // appears already expired when tick() is invoked.
+        c.setTargetInstant(Instant.now().minusSeconds(2));
+
+        java.lang.reflect.Method tick = CountdownManager.class.getDeclaredMethod("tick");
+        tick.setAccessible(true);
+
+        // First tick — end should be handled, commands dispatched once.
+        tick.invoke(manager);
+        assertEquals(1, dispatchCount.get(), "command should be dispatched exactly once on first tick");
+
+        // Second tick — countdown is no longer running; commands must NOT fire again.
+        tick.invoke(manager);
+        assertEquals(1, dispatchCount.get(), "command must NOT be dispatched a second time on subsequent tick");
+    }
+
+    /**
+     * Regression: the end-message broadcast must be sent exactly once per countdown
+     * expiry, even if tick() is called multiple times after the expiry.
+     */
+    @Test
+    public void endMessage_broadcastedExactlyOncePerExpiry() throws Exception {
+        Countdown c = new Countdown("msg-once", CountdownType.DURATION,
+                EnumSet.noneOf(com.skyblockexp.ezcountdown.display.DisplayType.class),
+                1, null, "{formatted}", "start-msg", "end-msg",
+                List.of(), ZoneId.systemDefault());
+        c.setDurationSeconds(10);
+        c.setRunning(true);
+        manager.createCountdown(c);
+        // Override target so the countdown is already expired when tick() runs.
+        c.setTargetInstant(Instant.now().minusSeconds(2));
+
+        // Clear call history accumulated during createCountdown (e.g., fireStart broadcast).
+        reset(displayManager);
+
+        java.lang.reflect.Method tick = CountdownManager.class.getDeclaredMethod("tick");
+        tick.setAccessible(true);
+
+        // First tick — end must be handled and message broadcast exactly once.
+        tick.invoke(manager);
+        verify(displayManager, times(1)).broadcastMessage(any());
+
+        // Second tick — countdown is stopped; message must NOT be broadcast again.
+        tick.invoke(manager);
+        verify(displayManager, times(1)).broadcastMessage(any()); // still 1
+    }
+
+    /**
+     * Regression: after a simulated reload (resumeRunningCountdowns() + tick()),
+     * commands for a DURATION countdown that had already ended must NOT fire again.
+     */
+    @Test
+    public void endCommands_doNotFireAgainAfterReload() throws Exception {
+        Countdown c = new Countdown("cmd-reload", CountdownType.DURATION,
+                EnumSet.noneOf(com.skyblockexp.ezcountdown.display.DisplayType.class),
+                1, null, "{formatted}", "start", "end",
+                List.of("/say finished"), ZoneId.systemDefault());
+        c.setDurationSeconds(10);
+        c.setRunning(false); // countdown already ended, saved state
+        c.setTargetInstant(null);
+        manager.createCountdown(c);
+
+        // Simulate reload: resumeRunningCountdowns skips non-running countdowns
+        manager.resumeRunningCountdowns();
+
+        java.lang.reflect.Method tick = CountdownManager.class.getDeclaredMethod("tick");
+        tick.setAccessible(true);
+        tick.invoke(manager);
+
+        assertEquals(0, dispatchCount.get(),
+                "commands must not fire for a countdown that is not running after reload");
+    }
+}
diff --git a/src/test/java/com/skyblockexp/ezcountdown/manager/MissedRunPolicyRunAllEdgeCasesTest.java b/src/test/java/com/skyblockexp/ezcountdown/manager/MissedRunPolicyRunAllEdgeCasesTest.java
index 457645f..af4c9ac 100644
--- a/src/test/java/com/skyblockexp/ezcountdown/manager/MissedRunPolicyRunAllEdgeCasesTest.java
+++ b/src/test/java/com/skyblockexp/ezcountdown/manager/MissedRunPolicyRunAllEdgeCasesTest.java
@@ -58,6 +58,7 @@ public void setup() throws Exception {
         java.lang.reflect.Field serverField = org.bukkit.Bukkit.class.getDeclaredField("server");
         serverField.setAccessible(true);
         serverField.set(null, bukkitServer);
+        when(registry.scheduler()).thenReturn(new com.skyblockexp.ezcountdown.compat.scheduler.BukkitSchedulerAdapter(plugin));
     }
 
     @Test
diff --git a/src/test/java/com/skyblockexp/ezcountdown/manager/MissedRunPolicyTest.java b/src/test/java/com/skyblockexp/ezcountdown/manager/MissedRunPolicyTest.java
index 3678ad5..8a79599 100644
--- a/src/test/java/com/skyblockexp/ezcountdown/manager/MissedRunPolicyTest.java
+++ b/src/test/java/com/skyblockexp/ezcountdown/manager/MissedRunPolicyTest.java
@@ -63,6 +63,7 @@ public void setup() {
         } catch (Exception e) {
             e.printStackTrace();
         }
+        when(registry.scheduler()).thenReturn(new com.skyblockexp.ezcountdown.compat.scheduler.BukkitSchedulerAdapter(plugin));
     }
 
     @Test
diff --git a/src/test/resources/mockito-extensions/org.mockito.plugins.MockMaker b/src/test/resources/mockito-extensions/org.mockito.plugins.MockMaker
new file mode 100644
index 0000000..1f0955d
--- /dev/null
+++ b/src/test/resources/mockito-extensions/org.mockito.plugins.MockMaker
@@ -0,0 +1 @@
+mock-maker-inline