docs update

Author: brbzull0

doc/appendices/command-line/traffic_ctl.en.rst

@@ -211,10 +211,23 @@ Display the current value of a configuration record.
    configuration after any configuration file modification. If no configuration files have been
    modified since the previous configuration load, this command is a no-op.
 
+   The reload is **asynchronous**: the command sends a JSONRPC request to |TS| and returns
+   immediately — it does not block until every config handler finishes. The actual reload work
+   runs on background threads (``ET_TASK``), where each registered config handler loads its
+   configuration and reports success or failure.
+
    Every reload is assigned a **token** — a unique identifier for the reload operation. The token
-   can be used to query the reload's status later via :option:`traffic_ctl config status`. If no
-   token is provided via ``--token``, the server generates one automatically using a timestamp
-   (e.g. ``rldtk-1739808000000``).
+   is the handle you use to track, monitor, or query the reload after it starts. If no token is
+   provided via ``--token``, the server generates one automatically using a timestamp (e.g.
+   ``rldtk-1739808000000``). You can supply a custom token via ``--token`` (e.g.
+   ``-t deploy-v2.1``) to tag reloads with meaningful labels for CI pipelines, deploy scripts, or
+   post-mortem analysis.
+
+   Use the token to:
+
+   - **Monitor** a reload in real-time: ``traffic_ctl config reload -t <token> -m``
+   - **Query** the final status: ``traffic_ctl config status -t <token>``
+   - **Get detailed logs**: ``traffic_ctl config status -t <token> -l``
 
    The timestamp of the last reconfiguration event (in seconds since epoch) is published in the
    ``proxy.process.proxy.reconfigure_time`` metric.

doc/developer-guide/config-reload-framework.en.rst

@@ -29,11 +29,23 @@ every handler must follow.
 Overview
 ========
 
+When a reload is requested (via :program:`traffic_ctl config reload` or the
+:ref:`admin_config_reload` JSONRPC API), the server does not block the caller. Instead, it:
+
+1. **Assigns a token** to the reload — either auto-generated (e.g. ``rldtk-<timestamp>``) or
+   user-supplied via ``-t``.
+2. **Schedules the reload** on background threads (``ET_TASK``). Each registered config handler
+   runs, reports its status (``in_progress`` → ``success`` or ``fail``), and results are
+   aggregated into a task tree.
+3. **Returns the token** immediately so the caller can track progress via
+   :option:`traffic_ctl config status` or :ref:`get_reload_config_status`.
+
+The **token** is the unique identifier for a reload operation — it is the handle used to monitor
+progress, query final status, and retrieve per-handler logs.
+
 ``ConfigRegistry`` is a centralized singleton that manages all configuration files, their reload
-handlers, trigger records, and file dependencies. When a reload is requested (via
-:program:`traffic_ctl` or the JSONRPC API — see :ref:`admin_config_reload` and
-:ref:`get_reload_config_status`), it coordinates execution, tracks progress per handler,
-and records the result in a queryable history.
+handlers, trigger records, and file dependencies. It coordinates execution, tracks progress per
+handler, and records the result in a queryable history.
 
 Key capabilities:
 
@@ -115,6 +127,14 @@ dependencies.
         "proxy.config.ssl.client.cert.filename",
         "proxy.config.ssl.server.session_ticket.enable"});
 
+.. note::
+
+   When a config key has multiple trigger records, a change to **any** of them invokes the
+   handler **once** per reload cycle — not once per record. The framework deduplicates
+   internally: the first trigger creates a subtask for the config key; subsequent triggers
+   for the same key in the same cycle are skipped. Handlers do not need to guard against
+   duplicate invocations.
+
 
 register_static_file
 --------------------

doc/developer-guide/jsonrpc/jsonrpc-api.en.rst

@@ -922,7 +922,12 @@ admin_config_reload
 Description
 ~~~~~~~~~~~
 
-Initiate a configuration reload. This method supports two modes:
+Initiate a configuration reload. This method returns immediately — the actual reload runs
+asynchronously on background threads (``ET_TASK``). The response contains a **token** that the
+caller uses to track the reload's progress and query its final status via
+:ref:`get_reload_config_status`.
+
+This method supports two modes:
 
 - **File-based reload** (default) — re-reads all registered configuration files from disk and invokes
   their handlers for any files whose modification time has changed.
@@ -1135,6 +1140,7 @@ Field                   Type          Description
 ``config_token``        |str|         The reload token.
 ``status``              |str|         Overall status: ``success``, ``fail``, ``in_progress``, ``timeout``.
 ``description``         |str|         Human-readable description.
+``config_key``          |str|         Registry key used for deduplication (empty for main tasks).
 ``filename``            |str|         Associated filename (empty for the main task).
 ``meta``                ``object``    Metadata: ``created_time_ms``, ``last_updated_time_ms``, ``main_task``.
 ``log``                 ``array``     Log messages from the handler.
@@ -1175,6 +1181,7 @@ Response:
                "config_token": "deploy-v2.1",
                "status": "success",
                "description": "Main reload task - 2025 Feb 17 12:00:00",
+               "config_key": "",
                "filename": "",
                "meta": {
                   "created_time_ms": "1739808000123",
@@ -1187,6 +1194,7 @@ Response:
                      "config_token": "deploy-v2.1",
                      "status": "success",
                      "description": "ip_allow",
+                     "config_key": "ip_allow",
                      "filename": "/opt/ats/etc/trafficserver/ip_allow.yaml",
                      "meta": {
                         "created_time_ms": "1739808000200",