diff --git a/CHANGES b/CHANGES
index 25f2854..9eb2717 100644
--- a/CHANGES
+++ b/CHANGES
@@ -12,6 +12,10 @@ _Notes on upcoming releases will be added here_
 
 The MCP install widget on the front page, {doc}`/quickstart`, and {ref}`clients` now lets you pick a config scope per LLM client alongside the install method — *local* / *user* / *project* for Claude Code, *user* / *project* for Codex and Gemini, *project* / *global* for Cursor. JSON-only clients (Cursor, Claude Desktop) also show the destination config-file path next to the snippet so the paste target is never a guess. Your scope choice is remembered per-client, so switching between clients restores each one's last selection.
 
+**Installer picker can apply or bypass dependency cooldowns**
+
+A new *Configure cooldowns* control on the install widget lets you tack a cooldown onto the snippet without leaving the page. Pick a delay in days (uv's `--exclude-newer`, pip's `--uploaded-prior-to`, pipx's `--pip-args`) to wait out community vetting before pulling a fresh release, or pick *Bypass any global cooldown* to skip a `~/.config/uv/uv.toml` cutoff and grab the latest libtmux-mcp anyway. The setting persists across pages, and the embedded *What are cooldowns?* expander links to the [Datadog Security Labs writeup](https://securitylabs.datadoghq.com/articles/dependency-cooldowns/) and [cooldowns.dev](https://cooldowns.dev/) if you want the supply-chain context. (#31)
+
 ## libtmux-mcp 0.1.0a7 (2026-05-16)
 
 ### Breaking changes
diff --git a/docs/_ext/widgets/_assets.py b/docs/_ext/widgets/_assets.py
index fb1b077..bfd7c61 100644
--- a/docs/_ext/widgets/_assets.py
+++ b/docs/_ext/widgets/_assets.py
@@ -3,10 +3,10 @@
 from __future__ import annotations
 
 import pathlib
+import shutil
 import typing as t
 
 from sphinx.util import logging
-from sphinx.util.fileutil import copy_asset_file
 
 from ._base import BaseWidget
 
@@ -28,6 +28,13 @@ def install_widget_assets(
     every page includes them (same pattern as ``sphinx-copybutton``). This is
     intentionally simpler than per-page inclusion — the files are small and the
     docs are not bandwidth-constrained.
+
+    Uses :func:`shutil.copy2` directly. Recent Sphinx releases tightened
+    ``copy_asset_file`` to refuse overwriting (it emits a
+    ``misc.copy_overwrite`` warning and aborts), which leaves stale widget
+    JS/CSS on every incremental rebuild. The fix is to do the byte copy
+    ourselves: the cache-busting ``?v=<hash>`` querystring on the
+    ``add_*_file`` registration line keeps browser caches honest.
     """
     if app.builder.format != "html":
         return
@@ -47,5 +54,5 @@ def install_widget_assets(
             if not source.is_file():
                 continue
             dest.mkdir(parents=True, exist_ok=True)
-            copy_asset_file(str(source), str(dest))
+            shutil.copy2(str(source), str(dest / filename))
             register(f"{STATIC_SUBDIR}/{name}/{filename}")
diff --git a/docs/_ext/widgets/_base.py b/docs/_ext/widgets/_base.py
index 9d18dd0..aaa3ab3 100644
--- a/docs/_ext/widgets/_base.py
+++ b/docs/_ext/widgets/_base.py
@@ -23,6 +23,12 @@ class HighlightFilter(t.Protocol):
     def __call__(self, code: str, language: str = "default") -> markupsafe.Markup: ...
 
 
+class CooldownDaysSlotFilter(t.Protocol):
+    """Callable signature for the Jinja ``cooldown_days_slot`` filter."""
+
+    def __call__(self, html: object) -> markupsafe.Markup: ...
+
+
 class widget_container(nodes.container):  # type: ignore[misc]  # docutils nodes are untyped
     """Wraps a widget's rendered HTML; visit/depart emit the outer div."""
 
@@ -99,6 +105,7 @@ def render(
             lstrip_blocks=True,
         )
         jenv.filters["highlight"] = make_highlight_filter(env)
+        jenv.filters["cooldown_days_slot"] = make_cooldown_days_slot_filter()
         template = jenv.from_string(source)
         context: dict[str, t.Any] = {
             **cls.default_options,
@@ -109,6 +116,53 @@ def render(
         return template.render(**context)
 
 
+def make_cooldown_days_slot_filter() -> CooldownDaysSlotFilter:
+    """Return a Jinja filter that injects cooldown slot ``<span>``s.
+
+    The Pygments highlighter escapes two days-mode sentinels emitted in
+    snippet bodies (see :mod:`docs._ext.widgets.mcp_install`):
+
+    * ``&lt;COOLDOWN_DURATION&gt;`` — used by uvx and pip days bodies.
+      Swapped for a span whose default text content is ``P<N>D`` (ISO
+      8601 duration). uv stores the value as
+      ``ExcludeNewerValue::Relative(ExcludeNewerSpan)`` and recomputes
+      ``now - N days`` on every resolver call; pip 26.1+ does the same
+      at flag-parse time per invocation. The snippet stays fresh
+      forever once saved to an MCP config.
+    * ``&lt;COOLDOWN_DATE&gt;`` — used by pipx days bodies because
+      pipx 1.8.0 bundles a pip older than 26.1 that rejects the
+      duration form with ``Invalid isoformat``. Swapped for a span
+      whose default text content is an absolute ISO date
+      (``today - default-days``). Drifts daily but ``widget.js``
+      refreshes the slot on every page load.
+
+    Both spans live inside a Pygments string-literal span and inherit
+    the parent's color. Their ``textContent`` is rewritten by
+    ``widget.js`` whenever the user changes the days input. The filter
+    is a no-op for outputs without either sentinel (off and bypass
+    cooldown modes never emit one).
+    """
+    from .mcp_install import DEFAULT_COOLDOWN_DAYS, default_cooldown_date
+
+    default_date = default_cooldown_date(DEFAULT_COOLDOWN_DAYS)
+    duration_span = (
+        '<span class="lm-mcp-install__cooldown-days"'
+        f" data-cooldown-duration-slot>P{DEFAULT_COOLDOWN_DAYS}D</span>"
+    )
+    date_span = (
+        '<span class="lm-mcp-install__cooldown-days"'
+        f" data-cooldown-date-slot>{default_date}</span>"
+    )
+
+    def _filter(html: object) -> markupsafe.Markup:
+        s = str(html)
+        s = s.replace("&lt;COOLDOWN_DURATION&gt;", duration_span)
+        s = s.replace("&lt;COOLDOWN_DATE&gt;", date_span)
+        return markupsafe.Markup(s)
+
+    return _filter
+
+
 def make_highlight_filter(env: BuildEnvironment) -> HighlightFilter:
     r"""Return a Jinja filter that runs Sphinx's Pygments highlighter.
 
diff --git a/docs/_ext/widgets/_prehydrate.py b/docs/_ext/widgets/_prehydrate.py
index c09fef3..3d9ed61 100644
--- a/docs/_ext/widgets/_prehydrate.py
+++ b/docs/_ext/widgets/_prehydrate.py
@@ -1,27 +1,41 @@
 """Prevent flash-of-wrong-selection on the ``mcp-install`` widget.
 
-The widget's server-rendered HTML always marks the first client/method/scope
-tab ``aria-selected="true"`` and ``hidden=""`` on every panel except the
-``(claude-code, uvx, local)`` cell. ``widget.js`` then reads ``localStorage``
-and mutates the DOM to the user's saved selection — a visible flash on
-initial page paint and on every gp-sphinx SPA navigation between docs pages.
-
-This module emits an inline ``<head>`` script that copies the saved selection
-from ``localStorage`` onto ``<html>`` as ``data-mcp-install-client`` /
-``data-mcp-install-method`` / ``data-mcp-install-scope`` attributes *before
-first paint*, plus a ``<style>`` block whose attribute-selector rules drive
-the active tab + visible scope group + visible panel from those attributes.
-``<html>`` is never replaced by gp-sphinx's ``spa-nav.js`` (it only swaps
-``.article-container``), so the attributes survive SPA navigation and the
-new article paints in the saved state without the head script needing to
-re-run.
+The widget's server-rendered HTML always marks the first
+client/method/scope tab ``aria-selected="true"`` and ``hidden=""`` on
+every panel except the ``(claude-code, uvx, local, off)`` cell.
+``widget.js`` then reads ``localStorage`` and mutates the DOM to the
+user's saved selection — a visible flash on initial page paint and on
+every gp-sphinx SPA navigation between docs pages.
+
+This module emits an inline ``<head>`` script that copies the saved
+selection from ``localStorage`` onto ``<html>`` as
+``data-mcp-install-client`` / ``data-mcp-install-method`` /
+``data-mcp-install-scope`` / ``data-mcp-install-cooldown-enabled`` /
+``data-mcp-install-cooldown-type`` / ``data-mcp-install-cooldown-days``
+attributes *before first paint*, plus a ``<style>`` block whose
+attribute-selector rules drive the active tab + visible scope group +
+visible panel from those attributes. ``<html>`` is never replaced by
+gp-sphinx's ``spa-nav.js`` (it only swaps ``.article-container``), so
+the attributes survive SPA navigation and the new article paints in
+the saved state without the head script needing to re-run.
 
 Scope is **per-client**: the localStorage key is
-``libtmux-mcp.mcp-install.scope.<client_id>``. Switching clients reads
-that client's saved scope (falling back to ``DEFAULT_SCOPES``) and updates
-``data-mcp-install-scope``. The ``DEFAULT_SCOPES`` map is serialized into
-the inline script from :data:`mcp_install.DEFAULT_SCOPES` so Python stays
-the single source of truth for which scope wins on first paint.
+``libtmux-mcp.mcp-install.scope.<client_id>``.
+
+Cooldown state is **three orthogonal axes**:
+
+* ``libtmux-mcp.mcp-install.cooldown.enabled`` — ``"1"`` / ``"0"`` —
+  master on/off switch.
+* ``libtmux-mcp.mcp-install.cooldown.type`` — ``"days"`` / ``"bypass"`` —
+  cooldown flavor when enabled.
+* ``libtmux-mcp.mcp-install.cooldown.days`` — int — day count when
+  ``type=days``.
+
+The ``cooldown-days`` attribute is read by ``widget.js`` (not by these
+CSS rules) to populate the per-snippet
+``[data-cooldown-duration-slot]`` / ``[data-cooldown-date-slot]``
+spans. The CSS panel rule keys on the ``enabled`` + ``type`` pair to
+pick which panel variant is visible.
 """
 
 from __future__ import annotations
@@ -29,7 +43,14 @@
 import json
 import typing as t
 
-from .mcp_install import CLIENTS, DEFAULT_SCOPES, METHODS
+from .mcp_install import (
+    CLIENTS,
+    DEFAULT_COOLDOWN_DAYS,
+    DEFAULT_COOLDOWN_ENABLED,
+    DEFAULT_COOLDOWN_TYPE,
+    DEFAULT_SCOPES,
+    METHODS,
+)
 
 if t.TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -39,11 +60,12 @@
 # ``@layer mcp-install-prehydrate`` (see :func:`_build_style`) and per CSS
 # Cascade Level 5 only ``!important`` declarations get the layer-priority
 # *reversal* that makes a layered rule outrank an unlayered one. Normal
-# (non-``!important``) rules in a layer LOSE to unlayered rules of the same
-# specificity — which is what bit the original tab rules: they were
+# (non-``!important``) rules in a layer LOSE to unlayered rules of the
+# same specificity — which is what bit the original tab rules: they were
 # specific enough to beat ``widget.css``'s ``.tab[aria-selected="true"]``
-# unlayered, but became powerless once we wrapped the prehydrate in a layer
-# to fix the panel cascade against ``furo-tw``'s ``[hidden]`` preflight.
+# unlayered, but became powerless once we wrapped the prehydrate in a
+# layer to fix the panel cascade against ``furo-tw``'s ``[hidden]``
+# preflight.
 _TAB_DEACTIVATE_RULE = (
     "html[data-mcp-install-client] .lm-mcp-install__tab"
     '[data-tab-kind="client"][aria-selected="true"],'
@@ -72,16 +94,67 @@
 _SCOPE_GROUP_ACTIVE_DECL = "{display:flex !important}"
 
 
+# Native ``<input type="checkbox">`` doesn't react to a CSS attribute
+# selector — its rendered glyph follows the ``.checked`` property, which
+# only ``widget.js`` can set (and only after DOMContentLoaded). That
+# produced a visible unchecked → checked flicker on every reload when
+# ``cooldown.enabled = "1"`` was saved. Strip the native UI with
+# ``appearance: none`` and re-render the checkbox visual from CSS keyed
+# off ``html[data-mcp-install-cooldown-enabled="1"]`` so the prehydrate
+# ``<head>`` script (which sets that attribute before first paint) drives
+# the visual without waiting for JS. ``.checked`` is still synced on
+# DOMContentLoaded for accessibility and click-handler correctness — the
+# sync is invisible because CSS already shows the right state.
+_COOLDOWN_TOGGLE_RULES = (
+    # Reset native chrome and own the box.
+    ".lm-mcp-install__cooldown-toggle"
+    "{appearance:none !important;"
+    "-webkit-appearance:none !important;"
+    "width:0.95em !important;"
+    "height:0.95em !important;"
+    "margin:0 !important;"
+    "border:1.5px solid var(--color-foreground-muted) !important;"
+    "border-radius:0.2em !important;"
+    "background:var(--color-background-primary) !important;"
+    "cursor:pointer !important;"
+    "position:relative !important;"
+    "flex:0 0 auto !important}"
+    # Checked appearance (brand-coloured fill + border).
+    'html[data-mcp-install-cooldown-enabled="1"]'
+    " .lm-mcp-install__cooldown-toggle"
+    "{background:var(--color-brand-primary) !important;"
+    "border-color:var(--color-brand-primary) !important}"
+    # Check mark via a centred ``✓`` pseudo. White on brand blue is
+    # legible in both light and dark modes (brand-primary stays blue).
+    'html[data-mcp-install-cooldown-enabled="1"]'
+    " .lm-mcp-install__cooldown-toggle::after"
+    '{content:"✓" !important;'
+    "position:absolute !important;"
+    "inset:0 !important;"
+    "display:flex !important;"
+    "align-items:center !important;"
+    "justify-content:center !important;"
+    "color:#fff !important;"
+    "font-size:0.85em !important;"
+    "font-weight:700 !important;"
+    "line-height:1 !important}"
+    # Focus ring — accessibility unchanged from native.
+    ".lm-mcp-install__cooldown-toggle:focus-visible"
+    "{outline:2px solid var(--color-brand-primary) !important;"
+    "outline-offset:2px !important}"
+)
+
+
 def _script() -> str:
     """Inline ``<head>`` script that mirrors localStorage onto ``<html>``.
 
     Emits a ``DEFAULT_SCOPES`` object literal derived from
-    :data:`mcp_install.DEFAULT_SCOPES` so adding a client/scope in
-    Python auto-extends the script. The script is intentionally tiny
-    (~300 bytes) and wrapped in try/catch in case ``localStorage`` is
-    disabled (private browsing, restricted environments).
+    :data:`mcp_install.DEFAULT_SCOPES`, plus the cooldown defaults
+    (``enabled`` / ``type`` / ``days``). Adding a client / scope /
+    cooldown mode in Python auto-extends the script.
     """
     defaults_literal = json.dumps(dict(DEFAULT_SCOPES), separators=(",", ":"))
+    enabled_default = "1" if DEFAULT_COOLDOWN_ENABLED else "0"
     return (
         '<script data-cfasync="false">(function(){'
         "try{"
@@ -92,9 +165,21 @@ def _script() -> str:
         + '";'
         'var m=localStorage.getItem("libtmux-mcp.mcp-install.method");'
         'var s=localStorage.getItem("libtmux-mcp.mcp-install.scope."+c)||d[c];'
+        'var ce=localStorage.getItem("libtmux-mcp.mcp-install.cooldown.enabled")||"'
+        + enabled_default
+        + '";'
+        'var ct=localStorage.getItem("libtmux-mcp.mcp-install.cooldown.type")||"'
+        + DEFAULT_COOLDOWN_TYPE
+        + '";'
+        'var cd=localStorage.getItem("libtmux-mcp.mcp-install.cooldown.days")||"'
+        + str(DEFAULT_COOLDOWN_DAYS)
+        + '";'
         'if(c)h.setAttribute("data-mcp-install-client",c);'
         'if(m)h.setAttribute("data-mcp-install-method",m);'
         'if(s)h.setAttribute("data-mcp-install-scope",s);'
+        'h.setAttribute("data-mcp-install-cooldown-enabled",ce);'
+        'h.setAttribute("data-mcp-install-cooldown-type",ct);'
+        'h.setAttribute("data-mcp-install-cooldown-days",cd);'
         "}catch(_){}"
         "})();</script>"
     )
@@ -127,7 +212,7 @@ def _scope_tab_active_selectors() -> str:
 
 
 def _scope_group_visible_selectors() -> str:
-    """Generate one rule per client that has a scope group rendered.
+    """One rule per client that has a scope group rendered.
 
     Single-scope clients (``len(scopes) == 1``) get no group in the
     template, so they get no rule here either.
@@ -141,53 +226,96 @@ def _scope_group_visible_selectors() -> str:
 
 
 def _panel_active_selectors() -> str:
-    """One selector per legal (client, method, scope) triple."""
-    return ",".join(
-        f'html[data-mcp-install-client="{c.id}"]'
-        f'[data-mcp-install-method="{m.id}"]'
-        f'[data-mcp-install-scope="{s.id}"]'
-        f" .lm-mcp-install__panel"
-        f'[data-client="{c.id}"]'
-        f'[data-method="{m.id}"]'
-        f'[data-scope="{s.id}"]'
-        for c in CLIENTS
-        for m in METHODS
-        for s in c.scopes
-    )
+    """One selector per legal (client, method, scope, cooldown-state).
+
+    Cooldown state is the (enabled, type) pair. There are three cases:
+
+    * ``enabled=0`` → show the panel whose ``data-cooldown="off"``,
+      regardless of saved type.
+    * ``enabled=1`` + ``type=days`` → show the panel whose
+      ``data-cooldown="days"``.
+    * ``enabled=1`` + ``type=bypass`` → show the panel whose
+      ``data-cooldown="bypass"``.
+
+    Enumerates 30 selectors per case = 90 total (same count as the
+    previous single-``mode`` model, just keyed on the new attr pair).
+    """
+    selectors: list[str] = []
+    for c in CLIENTS:
+        for m in METHODS:
+            for s in c.scopes:
+                base = (
+                    f'[data-mcp-install-client="{c.id}"]'
+                    f'[data-mcp-install-method="{m.id}"]'
+                    f'[data-mcp-install-scope="{s.id}"]'
+                )
+                panel_base = (
+                    f" .lm-mcp-install__panel"
+                    f'[data-client="{c.id}"]'
+                    f'[data-method="{m.id}"]'
+                    f'[data-scope="{s.id}"]'
+                )
+                # enabled=0 → off panel (type is don't-care)
+                selectors.append(
+                    f'html[data-mcp-install-cooldown-enabled="0"]'
+                    f"{base}{panel_base}"
+                    f'[data-cooldown="off"]'
+                )
+                # enabled=1, type=days → days panel
+                selectors.append(
+                    f'html[data-mcp-install-cooldown-enabled="1"]'
+                    f'[data-mcp-install-cooldown-type="days"]'
+                    f"{base}{panel_base}"
+                    f'[data-cooldown="days"]'
+                )
+                # enabled=1, type=bypass → bypass panel
+                selectors.append(
+                    f'html[data-mcp-install-cooldown-enabled="1"]'
+                    f'[data-mcp-install-cooldown-type="bypass"]'
+                    f"{base}{panel_base}"
+                    f'[data-cooldown="bypass"]'
+                )
+    return ",".join(selectors)
 
 
 def _build_style() -> str:
     """Return the ``<style>`` block that drives active state from html attrs.
 
-    Selectors are enumerated from :data:`CLIENTS` / :data:`METHODS` so adding
-    a client, method, or scope auto-extends the prehydrate rules — no second
-    source of truth to drift from.
+    Selectors are enumerated from :data:`CLIENTS` / :data:`METHODS` so
+    adding a client, method, or scope auto-extends the prehydrate rules
+    — no second source of truth to drift from.
 
-    Rules are wrapped in ``@layer mcp-install-prehydrate``. ``gp-furo-theme``
-    ships Tailwind v4's preflight inside ``@layer base``, including
+    Rules are wrapped in ``@layer mcp-install-prehydrate``.
+    ``gp-furo-theme`` ships Tailwind v4's preflight inside
+    ``@layer base``, including
     ``[hidden]:where(:not([hidden="until-found"])){display:none!important}``.
     Per CSS Cascade Level 5, important-rule layer ordering is reversed:
     rules in *any* cascade layer outrank ``!important`` unlayered rules
-    regardless of specificity. An unlayered prehydrate ``<style>`` therefore
-    loses to the preflight on the saved panel, so the saved panel paints as
-    ``display:none`` until ``widget.js`` mutates ``[hidden]`` and the
-    install widget visibly grows. Declaring our rules in their own layer
-    makes them the *first* layer the browser encounters (the prehydrate
-    ``<style>`` lives in ``metatags``, before any ``<link>``), which is
-    the highest-priority layer for ``!important``.
+    regardless of specificity. An unlayered prehydrate ``<style>``
+    therefore loses to the preflight on the saved panel, so the saved
+    panel paints as ``display:none`` until ``widget.js`` mutates
+    ``[hidden]`` and the install widget visibly grows. Declaring our
+    rules in their own layer makes them the *first* layer the browser
+    encounters (the prehydrate ``<style>`` lives in ``metatags``,
+    before any ``<link>``), which is the highest-priority layer for
+    ``!important``.
 
     The reversal only applies to ``!important`` declarations. *Normal*
-    layered rules LOSE to *normal* unlayered rules — so every declaration
-    here is ``!important``, including the tab active/inactive colours
-    that competed (and won, unlayered) against ``widget.css``'s
-    ``.lm-mcp-install__tab[aria-selected="true"]`` purely on specificity.
-    Drop the ``!important`` on a tab declaration and the active-tab
-    indicator will flash from server default to saved state on first paint.
-
-    Scope adds three new selector families: scope group visibility (one
-    rule per client with >1 scope), scope tab active state (one rule per
-    legal client+scope pair), and a triple-attribute panel rule that
-    replaces the old client+method pair.
+    layered rules LOSE to *normal* unlayered rules — so every
+    declaration here is ``!important``, including the tab
+    active/inactive colours that competed (and won, unlayered) against
+    ``widget.css``'s ``.lm-mcp-install__tab[aria-selected="true"]``
+    purely on specificity. Drop the ``!important`` on a tab
+    declaration and the active-tab indicator will flash from server
+    default to saved state on first paint.
+
+    Cooldown adds a fourth dimension keyed on the (enabled, type)
+    pair on ``<html>`` rather than a single ``cooldown-mode`` attr.
+    The ``cooldown-days`` html attribute does NOT drive a CSS rule —
+    the days number lives in spans ``widget.js`` updates by
+    textContent on every change (both duration ``P<N>D`` and
+    absolute-date forms coexist; uvx + pip use duration, pipx uses
+    absolute).
     """
     client_ids = tuple(c.id for c in CLIENTS)
     method_ids = tuple(m.id for m in METHODS)
@@ -199,6 +327,7 @@ def _build_style() -> str:
         _scope_group_visible_selectors() + _SCOPE_GROUP_ACTIVE_DECL,
         _PANEL_HIDE_RULE,
         _panel_active_selectors() + _PANEL_ACTIVE_DECL,
+        _COOLDOWN_TOGGLE_RULES,
     ]
     return "<style>@layer mcp-install-prehydrate{" + "".join(rules) + "}</style>"
 
@@ -216,9 +345,10 @@ def inject_mcp_install_prehydrate(
 ) -> None:
     """Inject the prehydrate ``<style>`` + ``<script>`` into Furo's ``<head>``.
 
-    Appended to ``context["metatags"]`` so it lands in Furo's ``metatags`` slot
-    (rendered before stylesheets and the ``<body>`` open). The pair is small
-    (~1.5 KB) and a no-op when no widget is present, so we don't bother
-    scoping to pages that use the directive.
+    Appended to ``context["metatags"]`` so it lands in Furo's
+    ``metatags`` slot (rendered before stylesheets and the ``<body>``
+    open). The pair is small (~3 KB with the cooldown rules) and a
+    no-op when no widget is present, so we don't bother scoping to
+    pages that use the directive.
     """
     context["metatags"] = context.get("metatags", "") + _snippet()
diff --git a/docs/_ext/widgets/mcp_install.py b/docs/_ext/widgets/mcp_install.py
index 5b576f6..8375288 100644
--- a/docs/_ext/widgets/mcp_install.py
+++ b/docs/_ext/widgets/mcp_install.py
@@ -1,19 +1,34 @@
-"""MCP install picker widget: 5 MCP clients by 3 install methods by N scopes.
-
-The matrix is **client x method x scope** where scope is per-client (each
-client carries its own ``scopes`` tuple). Claude Code has three scopes
-(local / user / project), Claude Desktop has one (user), and the rest
-have two each — see the per-client ``_*_SCOPES`` constants below.
-
-``DEFAULT_SCOPES`` is derived from ``CLIENTS`` and consumed by
-``_prehydrate.py`` so Python remains the single source of truth for
-which scope wins on first paint.
+"""MCP install picker widget: client x method x scope x cooldown matrix.
+
+Each MCP client carries its own ``scopes`` tuple (Claude Code has three,
+Claude Desktop has one, the rest have two). On top of that, every panel
+exists in three **cooldown** modes — ``off`` (no extra flag), ``days``
+(insert a ``--exclude-newer`` / ``--uploaded-prior-to`` flag with a
+user-configurable day count), and ``bypass`` (skip any global uv
+cooldown via ``--no-config`` / ``UV_NO_CONFIG``). Together these
+produce 90 server-rendered panels (3 + 1 + 2 + 2 + 2 = 10 scopes,
+times 3 methods, times 3 cooldown modes).
+
+Cooldown state is split across three orthogonal axes:
+``DEFAULT_COOLDOWN_ENABLED`` (master on/off), ``DEFAULT_COOLDOWN_TYPE``
+(``"days"`` vs ``"bypass"``), and ``DEFAULT_COOLDOWN_DAYS`` (day count).
+These (along with ``DEFAULT_SCOPES``) are consumed by ``_prehydrate.py``
+so Python remains the single source of truth for which (client,
+method, scope, cooldown) cell wins on first paint.
+
+Two sentinels appear in days-mode bodies. ``<COOLDOWN_DURATION>`` lands
+in uvx + pip bodies and survives as ISO 8601 duration ``P<N>D`` — both
+uv and pip 26.1+ re-evaluate the duration on every invocation, so the
+flag stays fresh forever once saved in an MCP config. ``<COOLDOWN_DATE>``
+lands in pipx bodies because pipx 1.8.0 bundles a pip older than 26.1
+that rejects the duration form; JS recomputes the absolute date on
+every page load. Both sentinels are swapped by ``cooldown_days_slot``
+in ``docs/_ext/widgets/_base.py``.
 """
 
 from __future__ import annotations
 
 import collections.abc
-import textwrap
 import typing as t
 from dataclasses import dataclass
 
@@ -32,7 +47,15 @@ class Scope:
     id: str
     label: str
     config_file: str
-    note: str | None  # optional preamble shown above the snippet
+    note: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class Cooldown:
+    """One cooldown mode (off / days / bypass)."""
+
+    id: str
+    label: str
 
 
 @dataclass(frozen=True, slots=True)
@@ -42,7 +65,7 @@ class Client:
     id: str
     label: str
     kind: str  # "cli" or "json"
-    scopes: tuple[Scope, ...]  # >=1; first is the SSR default for this client
+    scopes: tuple[Scope, ...]
 
 
 @dataclass(frozen=True, slots=True)
@@ -51,18 +74,21 @@ class Method:
 
     id: str
     label: str
-    doc_url: str | None  # link for the "With [uv] installed:" preamble
+    doc_url: str | None
 
 
 @dataclass(frozen=True, slots=True)
 class Panel:
-    """Pre-built HTML-ready cell for one (client, method, scope) combination."""
+    """Pre-built HTML-ready cell for one (client, method, scope, cooldown)."""
 
     client: Client
     method: Method
     scope: Scope
+    cooldown: Cooldown
     language: str  # "console" | "json" | "toml"
     body: str
+    pip_prereq: str | None  # only set for the pip method
+    note: str | None  # cooldown-related caveat (e.g. pipx bypass is a no-op)
     is_default: bool
 
 
@@ -186,7 +212,11 @@ class Panel:
 )
 
 
-PIP_PREREQ: str = "pip install --user --upgrade libtmux libtmux-mcp"
+COOLDOWNS: tuple[Cooldown, ...] = (
+    Cooldown(id="off", label="Off"),
+    Cooldown(id="days", label="Apply a cooldown"),
+    Cooldown(id="bypass", label="Bypass global cooldown"),
+)
 
 
 # Default scope per client, derived from the first entry of each ``scopes``
@@ -196,118 +226,232 @@ class Panel:
     client.id: client.scopes[0].id for client in CLIENTS
 }
 
+DEFAULT_COOLDOWN_ENABLED: bool = False
+DEFAULT_COOLDOWN_TYPE: str = "days"
+DEFAULT_COOLDOWN_DAYS: int = 7
+
+
+# Two sentinels swapped by ``cooldown_days_slot`` in ``_base.py`` after
+# Pygments has escaped them to ``&lt;...&gt;``.
+#
+# * ``<COOLDOWN_DURATION>`` is used by uvx and pip days bodies. uv stores
+#   the value as ``ExcludeNewerValue::Relative(ExcludeNewerSpan)`` and
+#   re-evaluates ``now - N days`` at every resolver call, so the saved
+#   ``.mcp.json`` arg ``"P7D"`` stays fresh forever. pip 26.1+ does the
+#   same at flag-parse time on every invocation.
+# * ``<COOLDOWN_DATE>`` is used by pipx days bodies because pipx 1.8.0
+#   bundles a pip older than 26.1, which rejects the duration form with
+#   ``Invalid isoformat``. The absolute date is computed in JS from
+#   ``today - savedDays``; the build-time default drifts daily but
+#   ``widget.js`` refreshes the slot on every page load.
+_DURATION_SENTINEL = "<COOLDOWN_DURATION>"
+_DATE_SENTINEL = "<COOLDOWN_DATE>"
+
+
+def default_cooldown_date(days: int) -> str:
+    """Return the ISO date string for *today (UTC) - days*.
+
+    Used as the build-time default for the cooldown-date slot so the
+    server-rendered snippet shows a valid date before JS hydration.
+    """
+    import datetime as _datetime
 
-_JSON_BODIES: collections.abc.Mapping[str, str] = {
-    "uvx": textwrap.dedent(
-        """\
-        {
-            "mcpServers": {
-                "tmux": {
-                    "command": "uvx",
-                    "args": ["libtmux-mcp"]
-                }
-            }
-        }"""
-    ),
-    "pipx": textwrap.dedent(
-        """\
-        {
-            "mcpServers": {
-                "tmux": {
-                    "command": "pipx",
-                    "args": ["run", "libtmux-mcp"]
-                }
-            }
-        }"""
-    ),
-    "pip": textwrap.dedent(
-        """\
-        {
-            "mcpServers": {
-                "tmux": {
-                    "command": "libtmux-mcp"
-                }
-            }
-        }"""
-    ),
-}
+    cutoff = _datetime.datetime.now(_datetime.timezone.utc) - _datetime.timedelta(
+        days=days
+    )
+    return cutoff.date().isoformat()
 
 
-_TOML_BODIES: collections.abc.Mapping[str, str] = {
-    "uvx": textwrap.dedent(
-        """\
-        [mcp_servers.tmux]
-        command = "uvx"
-        args = ["libtmux-mcp"]"""
-    ),
-    "pipx": textwrap.dedent(
-        """\
-        [mcp_servers.tmux]
-        command = "pipx"
-        args = ["run", "libtmux-mcp"]"""
-    ),
-    "pip": textwrap.dedent(
-        """\
-        [mcp_servers.tmux]
-        command = "libtmux-mcp\""""
-    ),
-}
+PIP_PREREQ_OFF: str = "pip install --user --upgrade libtmux libtmux-mcp"
+PIP_PREREQ_DAYS: str = (
+    f"pip install --user --upgrade --uploaded-prior-to {_DURATION_SENTINEL}"
+    " libtmux libtmux-mcp"
+)
 
 
-_CLI_BODIES: collections.abc.Mapping[tuple[str, str], str] = {
-    ("claude-code", "uvx"): "claude mcp add tmux -- uvx libtmux-mcp",
-    ("claude-code", "pipx"): "claude mcp add tmux -- pipx run libtmux-mcp",
-    ("claude-code", "pip"): "claude mcp add tmux -- libtmux-mcp",
-    ("codex", "uvx"): "codex mcp add tmux -- uvx libtmux-mcp",
-    ("codex", "pipx"): "codex mcp add tmux -- pipx run libtmux-mcp",
-    ("codex", "pip"): "codex mcp add tmux -- libtmux-mcp",
-    ("gemini", "uvx"): "gemini mcp add tmux uvx -- libtmux-mcp",
-    ("gemini", "pipx"): "gemini mcp add tmux pipx -- run libtmux-mcp",
-    ("gemini", "pip"): "gemini mcp add tmux libtmux-mcp",
-}
+def _pip_prereq_for(cooldown: Cooldown) -> str:
+    """Return the prereq ``pip install`` line for the given cooldown mode.
 
+    ``bypass`` falls through to the ``off`` form: pip has no global cooldown
+    config to bypass, so the prereq is identical and the cooldown note on
+    the panel explains the situation.
+    """
+    if cooldown.id == "days":
+        return PIP_PREREQ_DAYS
+    return PIP_PREREQ_OFF
 
-def _with_scope(client_id: str, base: str, scope_id: str) -> str:
-    """Insert the ``--scope`` flag into a CLI command at the right position.
 
-    Each CLI has a different syntax for where the flag lands:
+def _tool_command(method: Method, cooldown: Cooldown) -> str:
+    """Build the inner ``<tool> [flags] libtmux-mcp`` command.
 
-    * **claude**: ``claude mcp add tmux --scope X -- <method-cmd>``.
-      Skip the flag for ``local`` (claude's default).
-    * **gemini**: ``gemini mcp add --scope X tmux <method-cmd>``. Always
-      emit the flag — both ``user`` and ``project`` are explicit.
-    * **codex**: doesn't support ``--scope`` from the CLI; only the
-      default ``user`` scope reaches this code path (codex project
-      uses ``_TOML_BODIES`` directly via :func:`_body_for`).
+    This is the portion of every CLI panel that lives *after* the
+    ``mcp add ... --`` separator on Claude / Codex / Gemini, and the
+    same string that goes into the JSON ``command + args`` pair for
+    Claude Desktop / Cursor.
     """
-    if client_id == "claude-code":
-        if scope_id == "local":
-            return base
-        return base.replace("mcp add tmux", f"mcp add tmux --scope {scope_id}", 1)
-    if client_id == "gemini":
-        return base.replace("mcp add tmux", f"mcp add --scope {scope_id} tmux", 1)
-    return base
+    if method.id == "uvx":
+        if cooldown.id == "days":
+            return f"uvx --exclude-newer {_DURATION_SENTINEL} libtmux-mcp"
+        if cooldown.id == "bypass":
+            return "uvx --no-config libtmux-mcp"
+        return "uvx libtmux-mcp"
+    if method.id == "pipx":
+        if cooldown.id == "days":
+            # pipx 1.8.0 bundles pip <26.1, which doesn't accept the
+            # duration form — emit an absolute date instead. JS recomputes
+            # ``today - savedDays`` on every page load.
+            return (
+                f"pipx run --pip-args=--uploaded-prior-to={_DATE_SENTINEL} libtmux-mcp"
+            )
+        # off + bypass (pipx default backend has no global cooldown)
+        return "pipx run libtmux-mcp"
+    # pip method: the cooldown applies on the prereq line above, not on
+    # the registered command. The register step is just ``libtmux-mcp``.
+    return "libtmux-mcp"
+
+
+def _cli_body(client: Client, scope: Scope, method: Method, cooldown: Cooldown) -> str:
+    """Build the full shell command for a CLI-kind client."""
+    tool_cmd = _tool_command(method, cooldown)
+    if client.id == "gemini":
+        # gemini's ``--`` separator lands *after* the tool token, not
+        # before. Split tool_cmd on the first space so the tool name
+        # stays adjacent to the registration slug.
+        if " " in tool_cmd:
+            head, tail = tool_cmd.split(" ", 1)
+            return f"gemini mcp add --scope {scope.id} tmux {head} -- {tail}"
+        # pip method: no args, no ``--``.
+        return f"gemini mcp add --scope {scope.id} tmux {tool_cmd}"
+    # claude-code: ``--scope`` flag added for non-default scopes.
+    if client.id == "claude-code":
+        flag = "" if scope.id == "local" else f"--scope {scope.id} "
+        return f"claude mcp add tmux {flag}-- {tool_cmd}".replace("  ", " ")
+    # codex: CLI doesn't write project scope; the project-scope panel
+    # uses the TOML body path (see ``_body_for``).
+    return f"codex mcp add tmux -- {tool_cmd}"
+
+
+_JSON_INDENT = "    "
+
+
+def _json_body(method: Method, cooldown: Cooldown) -> str:
+    """Build the JSON config snippet for a JSON-kind client.
+
+    The same JSON works for Claude Desktop and Cursor; the *destination*
+    differs (carried on ``Scope.config_file``) but the content does not.
+    """
+    if method.id == "uvx":
+        command = "uvx"
+        if cooldown.id == "days":
+            args = f'"--exclude-newer", "{_DURATION_SENTINEL}", "libtmux-mcp"'
+        else:
+            args = '"libtmux-mcp"'
+    elif method.id == "pipx":
+        command = "pipx"
+        if cooldown.id == "days":
+            args = (
+                '"run", "--pip-args=--uploaded-prior-to='
+                f'{_DATE_SENTINEL}", "libtmux-mcp"'
+            )
+        else:
+            args = '"run", "libtmux-mcp"'
+    else:  # pip
+        command = "libtmux-mcp"
+        args = None
+
+    # Build server-object members at the 12-space indent (3 levels deep:
+    # top → mcpServers → tmux → here). Bypass via ``env`` only applies to
+    # uvx (pipx + pip have no global uv cooldown to skip); the per-panel
+    # ``note`` field surfaces the no-op caveat on those combos.
+    server_indent = _JSON_INDENT * 3
+    server_lines = [server_indent + f'"command": "{command}"']
+    if args is not None:
+        server_lines.append(server_indent + f'"args": [{args}]')
+    if cooldown.id == "bypass" and method.id == "uvx":
+        server_lines.append(server_indent + '"env": { "UV_NO_CONFIG": "1" }')
+    server_block = ",\n".join(server_lines)
+    # Avoid ``textwrap.dedent`` here — the f-string-then-dedent pattern
+    # collapses when the substituted ``inner`` block lands lines at a
+    # smaller indent than the surrounding template, breaking the
+    # post-dedent alignment of every member except the first. Explicit
+    # per-line indents keep the output stable regardless of source
+    # whitespace.
+    return (
+        "{\n"
+        f'{_JSON_INDENT}"mcpServers": {{\n'
+        f'{_JSON_INDENT * 2}"tmux": {{\n'
+        f"{server_block}\n"
+        f"{_JSON_INDENT * 2}}}\n"
+        f"{_JSON_INDENT}}}\n"
+        "}"
+    )
+
+
+def _toml_body(method: Method, cooldown: Cooldown) -> str:
+    """Build the TOML snippet for Codex's project scope (manual edit)."""
+    if method.id == "uvx":
+        command, args_inner = "uvx", '"libtmux-mcp"'
+        if cooldown.id == "days":
+            args_inner = f'"--exclude-newer", "{_DURATION_SENTINEL}", "libtmux-mcp"'
+    elif method.id == "pipx":
+        command, args_inner = "pipx", '"run", "libtmux-mcp"'
+        if cooldown.id == "days":
+            args_inner = (
+                f'"run", "--pip-args=--uploaded-prior-to={_DATE_SENTINEL}",'
+                ' "libtmux-mcp"'
+            )
+    else:  # pip
+        command, args_inner = "libtmux-mcp", None
+
+    lines = [
+        "[mcp_servers.tmux]",
+        f'command = "{command}"',
+    ]
+    if args_inner is not None:
+        lines.append(f"args = [{args_inner}]")
+    if cooldown.id == "bypass" and method.id == "uvx":
+        lines.append('env = { UV_NO_CONFIG = "1" }')
+    return "\n".join(lines)
+
+
+def _cooldown_note(method: Method, cooldown: Cooldown) -> str | None:
+    """Return a one-line caveat for cells where cooldown is a no-op."""
+    if cooldown.id != "bypass":
+        return None
+    if method.id == "pip":
+        return (
+            "pip has no global cooldown, so bypass is a no-op. Use this"
+            " when pairing the snippet with a uv-backed parent command."
+        )
+    if method.id == "pipx":
+        return (
+            "pipx's default backend (pip) has no global cooldown."
+            " For uv-style cooldown control, install `pipx[uv]` and set"
+            " `UV_NO_CONFIG=1` in your shell."
+        )
+    return None
 
 
 def _body_for(
     client: Client,
     method: Method,
     scope: Scope,
-) -> tuple[str, str]:
-    """Return ``(body, language)`` for one (client, method, scope) cell.
-
-    Cursor's project vs global cells share an identical JSON body; only
-    the config-file label (on :class:`Scope`) differs. Codex project is
-    the only cell that escapes its client's normal kind — it shows a TOML
-    snippet for manual ``.codex/config.toml`` editing.
+    cooldown: Cooldown,
+) -> tuple[str, str, str | None]:
+    """Return ``(body, language, note)`` for one (client, method, scope, cooldown).
+
+    Codex's ``project`` scope is the one cell that escapes its client's
+    normal kind — it emits TOML because the Codex CLI doesn't write
+    ``project`` scope, so the user pastes manually into a
+    ``.codex/config.toml`` at the repo root.
     """
+    note = _cooldown_note(method, cooldown)
     if client.id == "codex" and scope.id == "project":
-        return _TOML_BODIES[method.id], "toml"
+        return _toml_body(method, cooldown), "toml", note
     if client.kind == "json":
-        return _JSON_BODIES[method.id], "json"
+        return _json_body(method, cooldown), "json", note
     if client.kind == "cli":
-        base = _CLI_BODIES[(client.id, method.id)]
-        return _with_scope(client.id, base, scope.id), "console"
+        return _cli_body(client, scope, method, cooldown), "console", note
     msg = f"unknown client kind: {client.kind!r}"
     raise ValueError(msg)
 
@@ -315,34 +459,46 @@ def _body_for(
 def build_panels(
     clients: tuple[Client, ...] = CLIENTS,
     methods: tuple[Method, ...] = METHODS,
+    cooldowns: tuple[Cooldown, ...] = COOLDOWNS,
 ) -> list[Panel]:
-    """Pre-compute every legal (client, method, scope) panel for rendering."""
+    """Pre-compute every legal (client, method, scope, cooldown) panel."""
     panels: list[Panel] = []
     for client_index, client in enumerate(clients):
         for method_index, method in enumerate(methods):
             for scope_index, scope in enumerate(client.scopes):
-                raw, language = _body_for(client, method, scope)
-                # "console" = BashSessionLexer -- recognises the leading
-                # ``$ `` as Generic.Prompt and emits ``<span class="gp">``,
-                # which the gp-sphinx copybutton regex strips on copy.
-                body = f"$ {raw}" if language == "console" else raw
-                panels.append(
-                    Panel(
-                        client=client,
-                        method=method,
-                        scope=scope,
-                        language=language,
-                        body=body,
-                        is_default=(
-                            client_index == 0 and method_index == 0 and scope_index == 0
-                        ),
+                for cooldown_index, cooldown in enumerate(cooldowns):
+                    raw, language, note = _body_for(client, method, scope, cooldown)
+                    # "console" = BashSessionLexer -- recognises the
+                    # leading ``$ `` as Generic.Prompt and emits
+                    # ``<span class="gp">``, which the gp-sphinx
+                    # copybutton regex strips on copy.
+                    body = f"$ {raw}" if language == "console" else raw
+                    pip_prereq = (
+                        _pip_prereq_for(cooldown) if method.id == "pip" else None
+                    )
+                    panels.append(
+                        Panel(
+                            client=client,
+                            method=method,
+                            scope=scope,
+                            cooldown=cooldown,
+                            language=language,
+                            body=body,
+                            pip_prereq=pip_prereq,
+                            note=note,
+                            is_default=(
+                                client_index == 0
+                                and method_index == 0
+                                and scope_index == 0
+                                and cooldown_index == 0
+                            ),
+                        )
                     )
-                )
     return panels
 
 
 class MCPInstallWidget(BaseWidget):
-    """MCP client + install-method + scope picker rendered as one block."""
+    """MCP client + install-method + scope + cooldown picker."""
 
     name: t.ClassVar[str] = "mcp-install"
     option_spec: t.ClassVar[collections.abc.Mapping[str, t.Any]] = {
@@ -354,10 +510,13 @@ class MCPInstallWidget(BaseWidget):
 
     @classmethod
     def context(cls, env: BuildEnvironment) -> collections.abc.Mapping[str, t.Any]:
-        """Return clients, methods, pre-built panels, and pip prereq for Jinja."""
+        """Return clients, methods, cooldowns, panels, defaults for Jinja."""
         return {
             "clients": CLIENTS,
             "methods": METHODS,
+            "cooldowns": COOLDOWNS,
             "panels": build_panels(),
-            "pip_prereq": PIP_PREREQ,
+            "default_cooldown_enabled": DEFAULT_COOLDOWN_ENABLED,
+            "default_cooldown_type": DEFAULT_COOLDOWN_TYPE,
+            "default_cooldown_days": DEFAULT_COOLDOWN_DAYS,
         }
diff --git a/docs/_widgets/mcp-install/widget.css b/docs/_widgets/mcp-install/widget.css
index 6592b5f..862d981 100644
--- a/docs/_widgets/mcp-install/widget.css
+++ b/docs/_widgets/mcp-install/widget.css
@@ -127,3 +127,244 @@
 .lm-mcp-install--compact .lm-mcp-install__body {
   padding: 0.7rem 0.8rem;
 }
+
+/* Cooldown control: sits on the right edge of the method row. The
+ * ``margin-inline-start: auto`` is the modern flex-trick to push to
+ * the end without disturbing the preceding tabs. */
+.lm-mcp-install__cooldown-control {
+  display: flex;
+  align-items: center;
+  gap: 0.35rem;
+  margin-inline-start: auto;
+  padding: 0 0.7rem 0 0.5rem;
+  color: var(--color-foreground-secondary);
+  font-size: 0.9em;
+}
+
+/* The .lm-mcp-install__cooldown-toggle styling lives in
+ * docs/_ext/widgets/_prehydrate.py inside the @layer mcp-install-prehydrate
+ * block — the appearance reset + checked-state visual must paint from the
+ * inline <head> style so native unchecked → checked flicker disappears. */
+
+.lm-mcp-install__cooldown-label-text {
+  appearance: none;
+  background: transparent;
+  border: 0;
+  border-bottom: 1px dashed transparent;
+  color: inherit;
+  cursor: pointer;
+  font: inherit;
+  padding: 0;
+  margin: 0;
+}
+
+.lm-mcp-install__cooldown-label-text:hover {
+  color: var(--color-foreground-primary);
+  border-bottom-color: var(--color-foreground-muted);
+}
+
+.lm-mcp-install__cooldown-label-text:focus-visible {
+  outline: 2px solid var(--color-brand-primary);
+  outline-offset: 2px;
+  border-radius: 0.15rem;
+}
+
+.lm-mcp-install__cooldown-help {
+  appearance: none;
+  background: transparent;
+  border: 1px solid var(--color-background-border, var(--color-foreground-border, #ccc));
+  border-radius: 999px;
+  width: 1.3em;
+  height: 1.3em;
+  padding: 0;
+  font: inherit;
+  font-size: 0.85em;
+  color: var(--color-foreground-secondary);
+  cursor: help;
+  line-height: 1;
+}
+
+.lm-mcp-install__cooldown-help:hover {
+  color: var(--color-brand-primary);
+  border-color: var(--color-brand-primary);
+}
+
+.lm-mcp-install__cooldown-help:focus-visible {
+  outline: 2px solid var(--color-brand-primary);
+  outline-offset: 2px;
+}
+
+/* Cooldown days slot inside snippets: inherits Pygments color from
+ * the surrounding string-literal span. Two ``data-*-slot`` attributes
+ * act as the JS hook for updating textContent on every cooldown-days
+ * change: ``data-cooldown-duration-slot`` (uvx + pip days bodies,
+ * carries ``P<N>D``) and ``data-cooldown-date-slot`` (pipx days bodies,
+ * carries ``YYYY-MM-DD``). */
+.lm-mcp-install__cooldown-days {
+  /* No own styling — the wrapping Pygments span carries the color. */
+}
+
+/* Cooldown caveat note rendered after snippets where bypass is a no-op. */
+.lm-mcp-install__cooldown-note {
+  margin: 0.5rem 0 0 0;
+  font-size: 0.85em;
+  font-style: italic;
+  color: var(--color-foreground-secondary);
+  border-left: 2px solid var(--color-background-border, var(--color-foreground-border, #ccc));
+  padding-left: 0.6rem;
+}
+
+.lm-mcp-install__cooldown-note code {
+  font-style: normal;
+}
+
+/* Settings sub-view: lives next to the install body and swaps in via
+ * the ``[data-mcp-install-view="settings"]`` attribute on ``<html>``.
+ * No transitions on the swap — same lesson as the tab rows (see commit
+ * f23d7d5: animations during theme resolve are visible flicker). */
+.lm-mcp-install__body--settings {
+  display: none;
+  padding: 1rem 1.2rem 1.2rem;
+}
+
+html[data-mcp-install-view="settings"] .lm-mcp-install__body--install {
+  display: none;
+}
+
+html[data-mcp-install-view="settings"] .lm-mcp-install__body--settings {
+  display: block;
+}
+
+/* Settings header: back button + title share one row, both flush to the
+ * top-left of the settings body's content area (the body's own padding
+ * supplies the gap to the widget edge). Sizes track the widget's base
+ * font scale (the host ``.lm-mcp-install`` is 0.95em). */
+.lm-mcp-install__settings-header {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  margin: 0 0 0.8rem 0;
+}
+
+.lm-mcp-install__back {
+  appearance: none;
+  background: transparent;
+  border: 1px solid var(--color-background-border, var(--color-foreground-border, #ccc));
+  border-radius: 0.25rem;
+  color: var(--color-foreground-secondary);
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.3rem;
+  font: inherit;
+  font-size: 0.85em;
+  line-height: 1;
+  padding: 0.2rem 0.5rem;
+}
+
+.lm-mcp-install__back:hover {
+  color: var(--color-foreground-primary);
+  border-color: var(--color-foreground-secondary);
+  background: var(--color-background-hover, rgba(0, 0, 0, 0.04));
+}
+
+.lm-mcp-install__back:focus-visible {
+  outline: 2px solid var(--color-brand-primary);
+  outline-offset: 2px;
+}
+
+.lm-mcp-install__back-icon {
+  font-size: 1.1em;
+  line-height: 1;
+}
+
+.lm-mcp-install__settings-title {
+  margin: 0;
+  font-size: 1em;
+  font-weight: 600;
+  color: var(--color-foreground-primary);
+}
+
+.lm-mcp-install__settings-help {
+  margin: 0 0 0.8rem 0;
+  font-size: 0.9em;
+  color: var(--color-foreground-secondary);
+}
+
+.lm-mcp-install__settings-help em {
+  font-style: italic;
+}
+
+.lm-mcp-install__settings-modes {
+  border: 0;
+  padding: 0;
+  margin: 0 0 1rem 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+
+.lm-mcp-install__settings-mode {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  cursor: pointer;
+  padding: 0.25rem 0;
+}
+
+.lm-mcp-install__settings-mode input[type="radio"] {
+  cursor: pointer;
+}
+
+.lm-mcp-install__cooldown-days-input {
+  width: 4.5em;
+  padding: 0.15rem 0.35rem;
+  border: 1px solid var(--color-background-border, var(--color-foreground-border, #ccc));
+  border-radius: 0.2rem;
+  background: var(--color-background-primary);
+  color: var(--color-foreground-primary);
+  font: inherit;
+  font-size: 0.95em;
+}
+
+.lm-mcp-install__cooldown-explainer {
+  border-top: 1px solid var(--color-background-border, var(--color-foreground-border, #ccc));
+  padding-top: 0.7rem;
+  margin-top: 0.5rem;
+  color: var(--color-foreground-secondary);
+  font-size: 0.9em;
+}
+
+.lm-mcp-install__cooldown-explainer summary {
+  cursor: pointer;
+  color: var(--color-brand-content, var(--color-brand-primary));
+  margin-bottom: 0.5rem;
+}
+
+.lm-mcp-install__cooldown-explainer p {
+  margin: 0 0 0.5rem 0;
+}
+
+.lm-mcp-install__cooldown-explainer a {
+  color: var(--color-brand-content, var(--color-brand-primary));
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.lm-mcp-install__sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* Compact variant tightens the cooldown control too. */
+.lm-mcp-install--compact .lm-mcp-install__cooldown-control {
+  font-size: 0.85em;
+  padding: 0 0.5rem 0 0.4rem;
+}
diff --git a/docs/_widgets/mcp-install/widget.html b/docs/_widgets/mcp-install/widget.html
index ac44a1f..e2e1798 100644
--- a/docs/_widgets/mcp-install/widget.html
+++ b/docs/_widgets/mcp-install/widget.html
@@ -1,6 +1,7 @@
 {#
-  MCP install widget: server-rendered client × method × scope matrix.
-  widget_name, clients, methods, panels, pip_prereq, variant are provided by
+  MCP install widget: server-rendered client x method x scope x cooldown
+  matrix. widget_name, clients, methods, cooldowns, panels,
+  default_cooldown_mode, default_cooldown_days, variant are provided by
   MCPInstallWidget.context() / the directive's option merge.
 
   The scope row is rendered as one __scopes-group per client that has
@@ -14,9 +15,24 @@
 
   Each code block runs through the `highlight` filter (defined in
   docs._ext.widgets._base.make_highlight_filter) which wraps Sphinx's
-  PygmentsBridge —
-  so the output is byte-identical to a native ``.. code-block::`` block,
-  meaning sphinx-copybutton + its prompt-strip regex work automatically.
+  PygmentsBridge — so the output is byte-identical to a native
+  ``.. code-block::`` block, meaning sphinx-copybutton + its prompt-strip
+  regex work automatically. The output is then run through
+  ``cooldown_days_slot`` (defined in
+  docs._ext.widgets._base.make_cooldown_days_slot_filter) which swaps
+  two post-Pygments sentinels:
+
+  * ``&lt;COOLDOWN_DURATION&gt;`` becomes
+    ``<span data-cooldown-duration-slot>P7D</span>`` — used by uvx and
+    pip days bodies, where uv + pip 26.1+ re-evaluate the duration on
+    every invocation.
+  * ``&lt;COOLDOWN_DATE&gt;`` becomes
+    ``<span data-cooldown-date-slot>YYYY-MM-DD</span>`` — used by pipx
+    days bodies because pipx 1.8.0's bundled pip rejects the duration
+    form.
+
+  ``widget.js`` updates both slot kinds' textContent on every
+  cooldown-days input change.
 #}
 <div class="lm-mcp-install lm-mcp-install--{{ variant }}">
   <div class="lm-mcp-install__tabs lm-mcp-install__tabs--clients"
@@ -49,6 +65,23 @@
       {{ method.label }}
     </button>
     {% endfor %}
+
+    <div class="lm-mcp-install__cooldown-control">
+      <input type="checkbox"
+             id="lm-mcp-install__cooldown-toggle"
+             class="lm-mcp-install__cooldown-toggle"
+             data-action="cooldown-toggle"
+             aria-label="Apply a dependency cooldown">
+      <button type="button"
+              class="lm-mcp-install__cooldown-label-text"
+              data-action="cooldown-open"
+              aria-label="Open cooldown settings">Configure cooldowns</button>
+      <button type="button"
+              class="lm-mcp-install__cooldown-help"
+              data-action="cooldown-help"
+              aria-label="What are cooldowns?"
+              title="What are cooldowns?">?</button>
+    </div>
   </div>
 
   <div class="lm-mcp-install__tabs lm-mcp-install__tabs--scopes"
@@ -73,13 +106,14 @@
     {% endfor %}
   </div>
 
-  <div class="lm-mcp-install__body">
+  <div class="lm-mcp-install__body lm-mcp-install__body--install">
     {% for panel in panels %}
     <div class="lm-mcp-install__panel"
          role="tabpanel"
          data-client="{{ panel.client.id }}"
          data-method="{{ panel.method.id }}"
          data-scope="{{ panel.scope.id }}"
+         data-cooldown="{{ panel.cooldown.id }}"
          tabindex="0"
          {% if not panel.is_default %}hidden{% endif %}>
 
@@ -90,7 +124,7 @@
       {% elif panel.method.id == 'pip' %}
       <p class="lm-mcp-install__preamble">Install the packages first:</p>
       <div class="lm-mcp-install__code--prereq">
-        {{ ("$ " ~ pip_prereq) | highlight("console") }}
+        {{ (("$ " ~ panel.pip_prereq) | highlight("console")) | cooldown_days_slot }}
       </div>
       <p class="lm-mcp-install__preamble">
         Then {{ 'register' if panel.client.kind == 'cli' else 'use this config' }}:
@@ -103,7 +137,13 @@
       </p>
       {% endif %}
 
-      {{ panel.body | highlight(panel.language) }}
+      {{ (panel.body | highlight(panel.language)) | cooldown_days_slot }}
+
+      {% if panel.note %}
+      <p class="lm-mcp-install__cooldown-note">
+        {{ panel.note }}
+      </p>
+      {% endif %}
 
       {#
         JSON-only clients (Cursor, Claude Desktop) carry the config file in the
@@ -120,4 +160,62 @@
     </div>
     {% endfor %}
   </div>
+
+  <div class="lm-mcp-install__body lm-mcp-install__body--settings"
+       role="dialog"
+       aria-label="Cooldown settings">
+    <div class="lm-mcp-install__settings-header">
+      <button type="button"
+              class="lm-mcp-install__back"
+              data-action="cooldown-back"
+              aria-label="Back to installer">
+        <span class="lm-mcp-install__back-icon" aria-hidden="true">&larr;</span>
+        <span class="lm-mcp-install__back-text">Back</span>
+      </button>
+      <h3 class="lm-mcp-install__settings-title">Dependency cooldowns</h3>
+    </div>
+    <p class="lm-mcp-install__settings-help">
+      Use the <em>Configure cooldowns</em> checkbox above to enable or
+      disable. These settings choose how cooldown behaves once enabled.
+    </p>
+    <fieldset class="lm-mcp-install__settings-modes">
+      <legend class="lm-mcp-install__sr-only">Cooldown type</legend>
+      <label class="lm-mcp-install__settings-mode">
+        <input type="radio" name="cooldown-mode" value="days"
+               data-action="cooldown-mode"
+               {{ 'checked' if default_cooldown_type == 'days' else '' }}>
+        <span>
+          Apply a cooldown of
+          <input type="number" min="1" max="365"
+                 value="{{ default_cooldown_days }}"
+                 class="lm-mcp-install__cooldown-days-input"
+                 data-action="cooldown-days"
+                 aria-label="Cooldown in days">
+          days
+        </span>
+      </label>
+      <label class="lm-mcp-install__settings-mode">
+        <input type="radio" name="cooldown-mode" value="bypass"
+               data-action="cooldown-mode"
+               {{ 'checked' if default_cooldown_type == 'bypass' else '' }}>
+        <span>Bypass any global cooldown <small>(uv only)</small></span>
+      </label>
+    </fieldset>
+    <details class="lm-mcp-install__cooldown-explainer">
+      <summary>What are cooldowns?</summary>
+      <p>
+        Cooldowns delay picking up newly uploaded packages so the
+        community has time to spot supply-chain attacks before you
+        install. Most package managers don't apply one by default
+        &mdash; you opt in via a global setting in your tool's config.
+      </p>
+      <p>
+        Learn more at
+        <a href="https://cooldowns.dev/" target="_blank" rel="noopener">cooldowns.dev</a>
+        &middot;
+        <a href="https://securitylabs.datadoghq.com/articles/dependency-cooldowns/"
+           target="_blank" rel="noopener">Datadog Security Labs writeup</a>.
+      </p>
+    </details>
+  </div>
 </div>
diff --git a/docs/_widgets/mcp-install/widget.js b/docs/_widgets/mcp-install/widget.js
index a5d4893..6330138 100644
--- a/docs/_widgets/mcp-install/widget.js
+++ b/docs/_widgets/mcp-install/widget.js
@@ -11,10 +11,23 @@
  * keeps tab aria-selected and the <html> data-attrs in sync with the
  * current selection. The CSS handles the rest.
  *
- * Scope is per-client: the localStorage key is
- * libtmux-mcp.mcp-install.scope.<client_id>. Switching clients reads
- * that client's saved scope (or DEFAULT_SCOPES fallback) and re-applies
- * it; switching scope writes to the current client's slot only.
+ * Scope is per-client (storage key `libtmux-mcp.mcp-install.scope.<id>`).
+ *
+ * Cooldown state is split into three orthogonal axes:
+ *   - `cooldown.enabled` ("1" | "0"): master on/off
+ *   - `cooldown.type`    ("days" | "bypass"): cooldown flavor when enabled
+ *   - `cooldown.days`    int: day count when type=days
+ *
+ * The checkbox in the method-tab row flips `enabled` only — it does *not*
+ * change the install/settings view. The "Configure cooldowns" label is the
+ * only entry point to the settings view. Inside settings, touching the
+ * radio or days input auto-sets enabled=1 (implicit activation).
+ *
+ * Days slots come in two flavors — uvx and pip days bodies embed a
+ * duration slot (`P<N>D`, self-refreshing in both uv and pip 26.1+),
+ * while pipx days bodies embed an absolute-date slot (pipx 1.8.0's
+ * bundled pip <26.1 rejects duration). Both are updated on every days
+ * input change.
  *
  * Vanilla JS, no deps.
  */
@@ -25,6 +38,9 @@
     client: "libtmux-mcp.mcp-install.client",
     method: "libtmux-mcp.mcp-install.method",
     scope: function (client) { return "libtmux-mcp.mcp-install.scope." + client; },
+    cooldownEnabled: "libtmux-mcp.mcp-install.cooldown.enabled",
+    cooldownType: "libtmux-mcp.mcp-install.cooldown.type",
+    cooldownDays: "libtmux-mcp.mcp-install.cooldown.days",
   };
 
   // Mirror of docs/_ext/widgets/mcp_install.py:DEFAULT_SCOPES. The prehydrate
@@ -39,10 +55,17 @@
     "cursor": "project",
   };
 
+  var DEFAULT_COOLDOWN_ENABLED = false;
+  var DEFAULT_COOLDOWN_TYPE = "days";
+  var DEFAULT_COOLDOWN_DAYS = 7;
+  var VALID_COOLDOWN_TYPES = { days: 1, bypass: 1 };
+
   var SYNC_EVENT = "lm-mcp-install:change";
 
   // Bind once on document/window — these listeners survive every SPA swap.
   document.addEventListener("click", onClick);
+  document.addEventListener("change", onChange);
+  document.addEventListener("input", onInput);
   document.addEventListener("keydown", onKeydown);
   window.addEventListener(SYNC_EVENT, onBroadcast);
 
@@ -59,6 +82,9 @@
     if (!widgets.length) return;
     var savedClient = localStorage.getItem(STORAGE.client);
     var savedMethod = localStorage.getItem(STORAGE.method);
+    var enabled = readCooldownEnabled();
+    var type = readCooldownType();
+    var days = readCooldownDays();
     widgets.forEach(function (widget) {
       // Always re-select client (saved or server-default). Selecting the
       // client also restores that client's saved scope as a side effect
@@ -74,15 +100,110 @@
       // call that pushes the SSR defaults onto <html data-mcp-install-*>
       // so the prehydrate CSS rules have all three attrs to match against.
       syncHtmlAttrs(widget);
+      // Cooldown state: paint UI + slot text from the same saved values
+      // the prehydrate script already pushed onto <html>.
+      applyCooldownToWidget(widget, enabled, type, days);
     });
+    // Settings view is transient — always reset to install view on
+    // first load and every SPA nav. (The user wouldn't expect to land
+    // mid-form on a new page.)
+    setView("install");
   }
 
   function onClick(e) {
+    var action = e.target.closest("[data-action]");
+    if (action) {
+      var widget = action.closest(".lm-mcp-install");
+      if (widget) {
+        if (handleCooldownAction(widget, action, e)) return;
+      }
+    }
     var tab = e.target.closest(".lm-mcp-install__tab");
     if (!tab) return;
-    var widget = tab.closest(".lm-mcp-install");
+    var tabWidget = tab.closest(".lm-mcp-install");
+    if (!tabWidget) return;
+    select(tabWidget, tab.dataset.tabKind, tab.dataset.tabValue, { persist: true, broadcast: true });
+    // Tab clicks are an install-side action — if the user was mid-
+    // configuring cooldowns, the click implies they want to see the
+    // snippet for their new selection. Return to install view so the
+    // updated panel is visible.
+    setView("install");
+  }
+
+  function handleCooldownAction(widget, el, event) {
+    var action = el.dataset.action;
+    if (action === "cooldown-toggle") {
+      // Native checkbox change runs through onChange. Don't double-handle.
+      return false;
+    }
+    if (action === "cooldown-open") {
+      setView("settings");
+      event.preventDefault();
+      return true;
+    }
+    if (action === "cooldown-help") {
+      setView("settings");
+      var details = widget.querySelector(".lm-mcp-install__cooldown-explainer");
+      if (details) details.open = true;
+      event.preventDefault();
+      return true;
+    }
+    if (action === "cooldown-back") {
+      setView("install");
+      event.preventDefault();
+      return true;
+    }
+    return false;
+  }
+
+  function onChange(e) {
+    var el = e.target.closest("[data-action]");
+    if (!el) return;
+    var widget = el.closest(".lm-mcp-install");
     if (!widget) return;
-    select(widget, tab.dataset.tabKind, tab.dataset.tabValue, { persist: true, broadcast: true });
+    var action = el.dataset.action;
+    if (action === "cooldown-toggle") {
+      // Master on/off only. Does NOT change view. Does NOT change
+      // type or days. Just flips ``cooldown.enabled``.
+      setCooldownEnabled(el.checked, { persist: true, broadcast: true });
+      return;
+    }
+    if (action === "cooldown-mode") {
+      // Radio selection in settings -> set type, auto-enable.
+      setCooldownType(el.value, { persist: true, broadcast: true });
+      if (!readCooldownEnabled()) {
+        setCooldownEnabled(true, { persist: true, broadcast: true });
+      }
+      return;
+    }
+    if (action === "cooldown-days") {
+      // Days input in settings -> set days, auto-enable, force type=days.
+      var n = clampDays(parseInt(el.value, 10));
+      setCooldownDays(n, { persist: true, broadcast: true });
+      if (readCooldownType() !== "days") {
+        setCooldownType("days", { persist: true, broadcast: true });
+      }
+      if (!readCooldownEnabled()) {
+        setCooldownEnabled(true, { persist: true, broadcast: true });
+      }
+    }
+  }
+
+  function onInput(e) {
+    // ``input`` fires on every keystroke for number inputs. We mirror the
+    // computed duration + cutoff date into every slot span so the snippet
+    // updates in real time even before the user blurs the field.
+    // localStorage write happens only on ``change`` (see onChange) to
+    // avoid hammering writes.
+    var el = e.target.closest('[data-action="cooldown-days"]');
+    if (!el) return;
+    var widget = el.closest(".lm-mcp-install");
+    if (!widget) return;
+    var n = parseInt(el.value, 10);
+    if (!isNaN(n) && n >= 1) {
+      updateAllCooldownSlots(n);
+      document.documentElement.setAttribute("data-mcp-install-cooldown-days", String(n));
+    }
   }
 
   function onKeydown(e) {
@@ -96,7 +217,17 @@
   function onBroadcast(event) {
     document.querySelectorAll(".lm-mcp-install").forEach(function (widget) {
       if (widget === event.detail.origin) return;
-      select(widget, event.detail.kind, event.detail.value, { persist: false, broadcast: false });
+      var kind = event.detail.kind;
+      if (kind === "cooldown-enabled" || kind === "cooldown-type" || kind === "cooldown-days") {
+        applyCooldownToWidget(
+          widget,
+          readCooldownEnabled(),
+          readCooldownType(),
+          readCooldownDays()
+        );
+        return;
+      }
+      select(widget, kind, event.detail.value, { persist: false, broadcast: false });
     });
   }
 
@@ -235,4 +366,137 @@
     tabs[next].focus();
     select(widget, kind, tabs[next].dataset.tabValue, { persist: true, broadcast: true });
   }
+
+  // -------- cooldown helpers --------------------------------------------
+
+  function readCooldownEnabled() {
+    var v = localStorage.getItem(STORAGE.cooldownEnabled);
+    if (v === "1") return true;
+    if (v === "0") return false;
+    return DEFAULT_COOLDOWN_ENABLED;
+  }
+
+  function readCooldownType() {
+    var t = localStorage.getItem(STORAGE.cooldownType);
+    return VALID_COOLDOWN_TYPES[t] ? t : DEFAULT_COOLDOWN_TYPE;
+  }
+
+  function readCooldownDays() {
+    var d = parseInt(localStorage.getItem(STORAGE.cooldownDays), 10);
+    return clampDays(d);
+  }
+
+  function clampDays(n) {
+    if (isNaN(n)) return DEFAULT_COOLDOWN_DAYS;
+    if (n < 1) return 1;
+    if (n > 365) return 365;
+    return n;
+  }
+
+  function setCooldownEnabled(enabled, opts) {
+    var v = enabled ? "1" : "0";
+    document.documentElement.setAttribute("data-mcp-install-cooldown-enabled", v);
+    if (opts.persist) localStorage.setItem(STORAGE.cooldownEnabled, v);
+    document.querySelectorAll(".lm-mcp-install").forEach(function (widget) {
+      applyCooldownToWidget(widget, enabled, readCooldownType(), readCooldownDays());
+    });
+    if (opts.broadcast) {
+      window.dispatchEvent(
+        new CustomEvent(SYNC_EVENT, {
+          detail: { origin: null, kind: "cooldown-enabled", value: v },
+        })
+      );
+    }
+  }
+
+  function setCooldownType(type, opts) {
+    if (!VALID_COOLDOWN_TYPES[type]) return;
+    document.documentElement.setAttribute("data-mcp-install-cooldown-type", type);
+    if (opts.persist) localStorage.setItem(STORAGE.cooldownType, type);
+    document.querySelectorAll(".lm-mcp-install").forEach(function (widget) {
+      applyCooldownToWidget(widget, readCooldownEnabled(), type, readCooldownDays());
+    });
+    if (opts.broadcast) {
+      window.dispatchEvent(
+        new CustomEvent(SYNC_EVENT, {
+          detail: { origin: null, kind: "cooldown-type", value: type },
+        })
+      );
+    }
+  }
+
+  function setCooldownDays(days, opts) {
+    var n = clampDays(days);
+    document.documentElement.setAttribute("data-mcp-install-cooldown-days", String(n));
+    if (opts.persist) localStorage.setItem(STORAGE.cooldownDays, String(n));
+    updateAllCooldownSlots(n);
+    // Sync the days input across every widget (multi-widget page).
+    document.querySelectorAll('[data-action="cooldown-days"]').forEach(function (input) {
+      if (document.activeElement !== input) input.value = String(n);
+    });
+    if (opts.broadcast) {
+      window.dispatchEvent(
+        new CustomEvent(SYNC_EVENT, {
+          detail: { origin: null, kind: "cooldown-days", value: n },
+        })
+      );
+    }
+  }
+
+  function daysToIsoDate(n) {
+    // YYYY-MM-DD in UTC, for pipx (pipx 1.8.0's bundled pip <26.1 rejects
+    // the duration form). uv and pip 26.1+ both accept this absolute form
+    // too, but the duration form is preferred for them because it stays
+    // self-refreshing in the user's saved MCP config.
+    var ms = Date.now() - n * 86400000;
+    return new Date(ms).toISOString().slice(0, 10);
+  }
+
+  function daysToIsoDuration(n) {
+    // P<N>D in ISO 8601. Used by uvx and pip days panels.
+    return "P" + n + "D";
+  }
+
+  function updateAllCooldownSlots(n) {
+    var duration = daysToIsoDuration(n);
+    var date = daysToIsoDate(n);
+    document.querySelectorAll("[data-cooldown-duration-slot]").forEach(function (slot) {
+      slot.textContent = duration;
+    });
+    document.querySelectorAll("[data-cooldown-date-slot]").forEach(function (slot) {
+      slot.textContent = date;
+    });
+  }
+
+  function applyCooldownToWidget(widget, enabled, type, days) {
+    // Checkbox: checked iff enabled.
+    var toggle = widget.querySelector(".lm-mcp-install__cooldown-toggle");
+    if (toggle) toggle.checked = !!enabled;
+    // Radio: the matching radio in the settings form.
+    widget.querySelectorAll('[data-action="cooldown-mode"]').forEach(function (radio) {
+      radio.checked = radio.value === type;
+    });
+    // Days input value (don't clobber while typing).
+    var daysInput = widget.querySelector('[data-action="cooldown-days"]');
+    if (daysInput && document.activeElement !== daysInput) {
+      daysInput.value = String(days);
+    }
+    // Slot contents for this widget's panels (other widgets get updated
+    // by their own applyCooldownToWidget call). Both duration and date
+    // slots are refreshed — only one kind is visible per panel.
+    var duration = daysToIsoDuration(days);
+    var date = daysToIsoDate(days);
+    widget.querySelectorAll("[data-cooldown-duration-slot]").forEach(function (slot) {
+      slot.textContent = duration;
+    });
+    widget.querySelectorAll("[data-cooldown-date-slot]").forEach(function (slot) {
+      slot.textContent = date;
+    });
+  }
+
+  function setView(view) {
+    var prev = document.documentElement.getAttribute("data-mcp-install-view");
+    if (prev === view) return;
+    document.documentElement.setAttribute("data-mcp-install-view", view);
+  }
 })();
diff --git a/tests/docs/test_widgets.py b/tests/docs/test_widgets.py
index 0f36822..5a9b004 100644
--- a/tests/docs/test_widgets.py
+++ b/tests/docs/test_widgets.py
@@ -11,10 +11,17 @@
 import pytest
 
 from docs._ext.widgets import BaseWidget
-from docs._ext.widgets._base import make_highlight_filter
+from docs._ext.widgets._base import (
+    make_cooldown_days_slot_filter,
+    make_highlight_filter,
+)
 from docs._ext.widgets._discovery import discover
 from docs._ext.widgets.mcp_install import (
     CLIENTS,
+    COOLDOWNS,
+    DEFAULT_COOLDOWN_DAYS,
+    DEFAULT_COOLDOWN_ENABLED,
+    DEFAULT_COOLDOWN_TYPE,
     METHODS,
     MCPInstallWidget,
     _body_for,
@@ -41,47 +48,139 @@ def test_discover_finds_mcp_install() -> None:
     assert issubclass(registry["mcp-install"], BaseWidget)
 
 
+_OFF = next(c for c in COOLDOWNS if c.id == "off")
+_DAYS = next(c for c in COOLDOWNS if c.id == "days")
+_BYPASS = next(c for c in COOLDOWNS if c.id == "bypass")
+
+
 def test_build_panels_yields_cross_product() -> None:
-    """One panel per (client, method, scope) triple; exactly one flagged default."""
+    """One panel per (client, method, scope, cooldown) quadruple; one default."""
     panels = build_panels()
-    expected = sum(len(c.scopes) for c in CLIENTS) * len(METHODS)
+    expected = sum(len(c.scopes) for c in CLIENTS) * len(METHODS) * len(COOLDOWNS)
     assert len(panels) == expected
     assert panels[0].is_default is True
     assert sum(1 for p in panels if p.is_default) == 1
 
 
-def test_build_panels_first_cell_is_claude_code_uvx_local() -> None:
-    """First panel is Claude Code + uvx + local in ``console`` with a ``$ `` body."""
+def test_build_panels_first_cell_is_claude_code_uvx_local_off() -> None:
+    """First panel is Claude Code + uvx + local + off — the SSR-default cell."""
     panels = build_panels()
     assert panels[0].client.id == "claude-code"
     assert panels[0].method.id == "uvx"
     assert panels[0].scope.id == "local"
+    assert panels[0].cooldown.id == "off"
     assert panels[0].language == "console"
     assert panels[0].body.startswith("$ ")
 
 
-def test_body_for_cli_client_returns_shell_command() -> None:
-    """CLI clients get the literal ``<tool> mcp add ...`` shell command."""
+def test_default_cooldown_constants() -> None:
+    """The default state is disabled, type ``days``, days positive."""
+    assert DEFAULT_COOLDOWN_ENABLED is False
+    assert DEFAULT_COOLDOWN_TYPE == "days"
+    assert DEFAULT_COOLDOWN_DAYS > 0
+
+
+def test_body_for_cli_client_off_returns_clean_command() -> None:
+    """Cooldown off leaves the existing CLI command intact (no extra flags)."""
     client = CLIENTS[0]  # claude-code
-    body, language = _body_for(client, METHODS[0], client.scopes[0])
+    body, language, note = _body_for(client, METHODS[0], client.scopes[0], _OFF)
     assert body == "claude mcp add tmux -- uvx libtmux-mcp"
     assert language == "console"
+    assert note is None
+
+
+def test_body_for_uvx_days_inserts_duration_sentinel() -> None:
+    """Uvx days mode adds ``--exclude-newer P<N>D`` (duration form).
+
+    uv stores the value as ``ExcludeNewerValue::Relative(ExcludeNewerSpan)``
+    and re-evaluates ``now - N days`` on every resolver call, so a saved
+    ``.mcp.json`` arg ``"P7D"`` stays fresh forever.
+    """
+    client = CLIENTS[0]
+    body, language, note = _body_for(client, METHODS[0], client.scopes[0], _DAYS)
+    assert body == (
+        "claude mcp add tmux -- uvx --exclude-newer <COOLDOWN_DURATION> libtmux-mcp"
+    )
+    assert language == "console"
+    assert note is None
+
+
+def test_body_for_uvx_bypass_inserts_no_config_flag() -> None:
+    """Bypass adds ``--no-config`` to the uvx command (flag form, not env)."""
+    client = CLIENTS[0]
+    body, language, note = _body_for(client, METHODS[0], client.scopes[0], _BYPASS)
+    assert body == "claude mcp add tmux -- uvx --no-config libtmux-mcp"
+    assert language == "console"
+    assert note is None  # uvx has a real bypass — no caveat
+
+
+def test_body_for_pipx_bypass_returns_caveat_note() -> None:
+    """Pipx bypass renders identically to off and surfaces a no-op note."""
+    client = CLIENTS[0]
+    pipx = next(m for m in METHODS if m.id == "pipx")
+    body_off, _, note_off = _body_for(client, pipx, client.scopes[0], _OFF)
+    body_bp, _, note_bp = _body_for(client, pipx, client.scopes[0], _BYPASS)
+    assert body_off == body_bp  # same command emitted
+    assert note_off is None
+    assert note_bp is not None
+    assert "pipx" in note_bp.lower()
+
+
+def test_body_for_pip_bypass_returns_caveat_note() -> None:
+    """Pip bypass renders identically to off and surfaces a no-op note."""
+    client = CLIENTS[0]
+    pip = next(m for m in METHODS if m.id == "pip")
+    body_off, _, note_off = _body_for(client, pip, client.scopes[0], _OFF)
+    body_bp, _, note_bp = _body_for(client, pip, client.scopes[0], _BYPASS)
+    assert body_off == body_bp
+    assert note_off is None
+    assert note_bp is not None
+    assert "pip" in note_bp.lower()
+
+
+def test_body_for_pipx_days_uses_pip_args_form_with_absolute_date() -> None:
+    """Pipx days uses absolute date (pipx 1.8.0's bundled pip rejects P<N>D)."""
+    client = CLIENTS[0]
+    pipx = next(m for m in METHODS if m.id == "pipx")
+    body, language, _ = _body_for(client, pipx, client.scopes[0], _DAYS)
+    assert "--pip-args=--uploaded-prior-to=<COOLDOWN_DATE>" in body
+    assert language == "console"
 
 
-def test_body_for_json_client_returns_config_snippet() -> None:
+def test_body_for_json_client_off_returns_config_snippet() -> None:
     """JSON clients get the ``mcpServers`` config snippet for the chosen method."""
     claude_desktop = CLIENTS[1]
-    body, language = _body_for(claude_desktop, METHODS[0], claude_desktop.scopes[0])
+    body, language, _ = _body_for(
+        claude_desktop, METHODS[0], claude_desktop.scopes[0], _OFF
+    )
     assert '"command": "uvx"' in body
     assert '"libtmux-mcp"' in body
     assert language == "json"
 
 
+def test_body_for_json_uvx_days_includes_exclude_newer_arg() -> None:
+    """Days mode for JSON-kind clients shows the duration flag in ``args``."""
+    claude_desktop = CLIENTS[1]
+    body, _, _ = _body_for(claude_desktop, METHODS[0], claude_desktop.scopes[0], _DAYS)
+    assert '"--exclude-newer"' in body
+    assert '"<COOLDOWN_DURATION>"' in body
+
+
+def test_body_for_json_uvx_bypass_adds_env_block() -> None:
+    """Bypass for JSON uvx panels adds an ``env`` block setting UV_NO_CONFIG=1."""
+    claude_desktop = CLIENTS[1]
+    body, _, _ = _body_for(
+        claude_desktop, METHODS[0], claude_desktop.scopes[0], _BYPASS
+    )
+    assert '"env":' in body
+    assert '"UV_NO_CONFIG": "1"' in body
+
+
 def test_body_for_claude_code_project_inserts_scope_flag() -> None:
     """Non-default Claude Code scopes append ``--scope X`` to the install command."""
     claude_code = CLIENTS[0]
     project_scope = next(s for s in claude_code.scopes if s.id == "project")
-    body, language = _body_for(claude_code, METHODS[0], project_scope)
+    body, language, _ = _body_for(claude_code, METHODS[0], project_scope, _OFF)
     assert body == "claude mcp add tmux --scope project -- uvx libtmux-mcp"
     assert language == "console"
 
@@ -90,21 +189,46 @@ def test_body_for_codex_project_returns_toml() -> None:
     """Codex project is the one cell whose kind escapes the client's CLI shape."""
     codex = next(c for c in CLIENTS if c.id == "codex")
     project_scope = next(s for s in codex.scopes if s.id == "project")
-    body, language = _body_for(codex, METHODS[0], project_scope)
+    body, language, _ = _body_for(codex, METHODS[0], project_scope, _OFF)
     assert language == "toml"
     assert "[mcp_servers.tmux]" in body
     assert 'command = "uvx"' in body
 
 
+def test_body_for_codex_project_days_inlines_flag_in_toml_args() -> None:
+    """Codex project + days puts ``--exclude-newer <DURATION>`` in the args array."""
+    codex = next(c for c in CLIENTS if c.id == "codex")
+    project_scope = next(s for s in codex.scopes if s.id == "project")
+    body, language, _ = _body_for(codex, METHODS[0], project_scope, _DAYS)
+    assert language == "toml"
+    assert '"--exclude-newer"' in body
+    assert '"<COOLDOWN_DURATION>"' in body
+
+
 def test_body_for_gemini_user_inserts_scope_flag() -> None:
     """Gemini emits ``--scope`` between ``mcp add`` and the server slug."""
     gemini = next(c for c in CLIENTS if c.id == "gemini")
     user_scope = next(s for s in gemini.scopes if s.id == "user")
-    body, language = _body_for(gemini, METHODS[0], user_scope)
+    body, language, _ = _body_for(gemini, METHODS[0], user_scope, _OFF)
     assert body == "gemini mcp add --scope user tmux uvx -- libtmux-mcp"
     assert language == "console"
 
 
+def test_pip_panel_has_cooldown_aware_pip_prereq() -> None:
+    """Panel.pip_prereq is set only for the pip method, with cooldown applied."""
+    panels = build_panels()
+    pip_panels = [p for p in panels if p.method.id == "pip"]
+    non_pip = [p for p in panels if p.method.id != "pip"]
+    assert all(p.pip_prereq is None for p in non_pip)
+    assert all(p.pip_prereq is not None for p in pip_panels)
+    days_pip = next(p for p in pip_panels if p.cooldown.id == "days")
+    off_pip = next(p for p in pip_panels if p.cooldown.id == "off")
+    assert days_pip.pip_prereq is not None
+    assert off_pip.pip_prereq is not None
+    assert "--uploaded-prior-to <COOLDOWN_DURATION>" in days_pip.pip_prereq
+    assert "--uploaded-prior-to" not in off_pip.pip_prereq
+
+
 def test_body_for_unknown_kind_raises() -> None:
     """An unrecognised ``client.kind`` surfaces as a ``ValueError``."""
     from docs._ext.widgets.mcp_install import Client, Scope
@@ -112,7 +236,96 @@ def test_body_for_unknown_kind_raises() -> None:
     fake_scope = Scope(id="user", label="User", config_file="", note=None)
     fake = Client(id="x", label="X", kind="bogus", scopes=(fake_scope,))
     with pytest.raises(ValueError, match="unknown client kind"):
-        _body_for(fake, METHODS[0], fake_scope)
+        _body_for(fake, METHODS[0], fake_scope, _OFF)
+
+
+# ---------- unit: cooldown_days_slot Jinja filter ------------------------
+
+
+def test_cooldown_days_slot_filter_swaps_duration_sentinel() -> None:
+    """``&lt;COOLDOWN_DURATION&gt;`` becomes a ``data-cooldown-duration-slot`` span.
+
+    Pygments escapes the body's ``<COOLDOWN_DURATION>`` sentinel to
+    ``&lt;COOLDOWN_DURATION&gt;`` before the filter runs; the filter
+    swaps that for the slot span carrying ``P<N>D`` as default text.
+    """
+    filt = make_cooldown_days_slot_filter()
+    inp = "uvx --exclude-newer &lt;COOLDOWN_DURATION&gt; libtmux-mcp"
+    out = str(filt(inp))
+    assert "&lt;COOLDOWN_DURATION&gt;" not in out
+    assert 'class="lm-mcp-install__cooldown-days"' in out
+    assert "data-cooldown-duration-slot" in out
+    assert f">P{DEFAULT_COOLDOWN_DAYS}D</span>" in out
+
+
+def test_cooldown_days_slot_filter_swaps_date_sentinel() -> None:
+    """``&lt;COOLDOWN_DATE&gt;`` becomes a ``data-cooldown-date-slot`` span.
+
+    The default date is computed at filter construction time from
+    ``today (UTC) - DEFAULT_COOLDOWN_DAYS``; ``widget.js`` overwrites
+    the slot's textContent on every page load.
+    """
+    filt = make_cooldown_days_slot_filter()
+    inp = "pipx run --pip-args=--uploaded-prior-to=&lt;COOLDOWN_DATE&gt; libtmux-mcp"
+    out = str(filt(inp))
+    assert "&lt;COOLDOWN_DATE&gt;" not in out
+    assert "data-cooldown-date-slot" in out
+    assert re.search(r"data-cooldown-date-slot>\d{4}-\d{2}-\d{2}<", out)
+
+
+def test_cooldown_days_slot_filter_is_no_op_without_sentinels() -> None:
+    """Off and bypass bodies never carry a sentinel and pass through unchanged."""
+    filt = make_cooldown_days_slot_filter()
+    inp = "uvx libtmux-mcp"
+    assert str(filt(inp)) == inp
+
+
+def test_cooldown_days_slot_filter_swaps_both_sentinels_in_one_html() -> None:
+    """A single page renders both uvx (duration) and pipx (date) snippets.
+
+    The Jinja filter is called per body, but the safety net is that a
+    single string with both sentinels still gets both swapped — drift
+    here would silently leave raw sentinels in the rendered HTML.
+    """
+    filt = make_cooldown_days_slot_filter()
+    inp = "left &lt;COOLDOWN_DURATION&gt; middle &lt;COOLDOWN_DATE&gt; right"
+    out = str(filt(inp))
+    assert "data-cooldown-duration-slot" in out
+    assert "data-cooldown-date-slot" in out
+    assert "&lt;COOLDOWN_" not in out
+
+
+def test_cooldown_days_slot_filter_returns_markupsafe_markup() -> None:
+    """Output is ``markupsafe.Markup`` so autoescape doesn't re-escape the span."""
+    import markupsafe
+
+    filt = make_cooldown_days_slot_filter()
+    out = filt("&lt;COOLDOWN_DURATION&gt;")
+    assert isinstance(out, markupsafe.Markup)
+
+
+def test_cooldown_days_slot_filter_registered_on_widget_render(
+    make_app: MakeApp,
+    real_widget_srcdir: pathlib.Path,
+) -> None:
+    """End-to-end: a rendered days-mode panel emits both slot spans correctly.
+
+    Guards against regressing the filter wiring in
+    ``BaseWidget.render()`` (i.e. ``jenv.filters["cooldown_days_slot"]``).
+    """
+    (real_widget_srcdir / "index.md").write_text(
+        "# Home\n\n```{mcp-install}\n```\n",
+        encoding="utf-8",
+    )
+    app = _build(make_app, real_widget_srcdir)
+    html = (pathlib.Path(app.outdir) / "index.html").read_text(encoding="utf-8")
+    # uvx + pip days bodies emit the duration slot; pipx days bodies
+    # emit the date slot. Both kinds must appear in any complete build.
+    assert "data-cooldown-duration-slot" in html
+    assert "data-cooldown-date-slot" in html
+    # And no raw sentinel escapes to the rendered page.
+    assert "&lt;COOLDOWN_DURATION&gt;" not in html
+    assert "&lt;COOLDOWN_DATE&gt;" not in html
 
 
 # ---------- integration: Sphinx build -------------------------------------