From b41dfdbaa1489d37a7e8ab559b9a92ab71222dee Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 28 Apr 2026 16:20:11 +0800
Subject: [PATCH] Split usage docs into chapters and add MCP guide

Restructure docs/source, docs/source.zh-CN, docs/source.zh-TW so the
monolithic usage.rst becomes a usage/ section directory grouped by topic
(getting started, local & transfer, servers & integrations, reliability
& events, configuration & extension). Add a dedicated MCP chapter for
each language documenting Claude Desktop and Claude Code integration.
---
 docs/source.zh-CN/index.rst               |   4 +-
 docs/source.zh-CN/usage.rst               | 557 ---------------------
 docs/source.zh-CN/usage/cli.rst           |  25 +
 docs/source.zh-CN/usage/cloud.rst         |  60 +++
 docs/source.zh-CN/usage/config.rst        |  45 ++
 docs/source.zh-CN/usage/dag.rst           |  28 ++
 docs/source.zh-CN/usage/events.rst        |  58 +++
 docs/source.zh-CN/usage/gui.rst           |  24 +
 docs/source.zh-CN/usage/index.rst         |  43 ++
 docs/source.zh-CN/usage/local.rst         | 122 +++++
 docs/source.zh-CN/usage/mcp.rst           | 189 +++++++
 docs/source.zh-CN/usage/notifications.rst |  27 +
 docs/source.zh-CN/usage/plugins.rst       |  50 ++
 docs/source.zh-CN/usage/quickstart.rst    |  65 +++
 docs/source.zh-CN/usage/reliability.rst   |  33 ++
 docs/source.zh-CN/usage/servers.rst       |  46 ++
 docs/source.zh-CN/usage/transfer.rst      |  51 ++
 docs/source.zh-TW/index.rst               |   4 +-
 docs/source.zh-TW/usage.rst               | 557 ---------------------
 docs/source.zh-TW/usage/cli.rst           |  25 +
 docs/source.zh-TW/usage/cloud.rst         |  60 +++
 docs/source.zh-TW/usage/config.rst        |  45 ++
 docs/source.zh-TW/usage/dag.rst           |  28 ++
 docs/source.zh-TW/usage/events.rst        |  58 +++
 docs/source.zh-TW/usage/gui.rst           |  24 +
 docs/source.zh-TW/usage/index.rst         |  43 ++
 docs/source.zh-TW/usage/local.rst         | 122 +++++
 docs/source.zh-TW/usage/mcp.rst           | 189 +++++++
 docs/source.zh-TW/usage/notifications.rst |  27 +
 docs/source.zh-TW/usage/plugins.rst       |  50 ++
 docs/source.zh-TW/usage/quickstart.rst    |  65 +++
 docs/source.zh-TW/usage/reliability.rst   |  33 ++
 docs/source.zh-TW/usage/servers.rst       |  46 ++
 docs/source.zh-TW/usage/transfer.rst      |  51 ++
 docs/source/index.rst                     |   4 +-
 docs/source/usage.rst                     | 581 ----------------------
 docs/source/usage/cli.rst                 |  25 +
 docs/source/usage/cloud.rst               |  62 +++
 docs/source/usage/config.rst              |  46 ++
 docs/source/usage/dag.rst                 |  28 ++
 docs/source/usage/events.rst              |  58 +++
 docs/source/usage/gui.rst                 |  25 +
 docs/source/usage/index.rst               |  44 ++
 docs/source/usage/local.rst               | 129 +++++
 docs/source/usage/mcp.rst                 | 204 ++++++++
 docs/source/usage/notifications.rst       |  29 ++
 docs/source/usage/plugins.rst             |  53 ++
 docs/source/usage/quickstart.rst          |  65 +++
 docs/source/usage/reliability.rst         |  33 ++
 docs/source/usage/servers.rst             |  48 ++
 docs/source/usage/transfer.rst            |  54 ++
 51 files changed, 2641 insertions(+), 1701 deletions(-)
 delete mode 100644 docs/source.zh-CN/usage.rst
 create mode 100644 docs/source.zh-CN/usage/cli.rst
 create mode 100644 docs/source.zh-CN/usage/cloud.rst
 create mode 100644 docs/source.zh-CN/usage/config.rst
 create mode 100644 docs/source.zh-CN/usage/dag.rst
 create mode 100644 docs/source.zh-CN/usage/events.rst
 create mode 100644 docs/source.zh-CN/usage/gui.rst
 create mode 100644 docs/source.zh-CN/usage/index.rst
 create mode 100644 docs/source.zh-CN/usage/local.rst
 create mode 100644 docs/source.zh-CN/usage/mcp.rst
 create mode 100644 docs/source.zh-CN/usage/notifications.rst
 create mode 100644 docs/source.zh-CN/usage/plugins.rst
 create mode 100644 docs/source.zh-CN/usage/quickstart.rst
 create mode 100644 docs/source.zh-CN/usage/reliability.rst
 create mode 100644 docs/source.zh-CN/usage/servers.rst
 create mode 100644 docs/source.zh-CN/usage/transfer.rst
 delete mode 100644 docs/source.zh-TW/usage.rst
 create mode 100644 docs/source.zh-TW/usage/cli.rst
 create mode 100644 docs/source.zh-TW/usage/cloud.rst
 create mode 100644 docs/source.zh-TW/usage/config.rst
 create mode 100644 docs/source.zh-TW/usage/dag.rst
 create mode 100644 docs/source.zh-TW/usage/events.rst
 create mode 100644 docs/source.zh-TW/usage/gui.rst
 create mode 100644 docs/source.zh-TW/usage/index.rst
 create mode 100644 docs/source.zh-TW/usage/local.rst
 create mode 100644 docs/source.zh-TW/usage/mcp.rst
 create mode 100644 docs/source.zh-TW/usage/notifications.rst
 create mode 100644 docs/source.zh-TW/usage/plugins.rst
 create mode 100644 docs/source.zh-TW/usage/quickstart.rst
 create mode 100644 docs/source.zh-TW/usage/reliability.rst
 create mode 100644 docs/source.zh-TW/usage/servers.rst
 create mode 100644 docs/source.zh-TW/usage/transfer.rst
 delete mode 100644 docs/source/usage.rst
 create mode 100644 docs/source/usage/cli.rst
 create mode 100644 docs/source/usage/cloud.rst
 create mode 100644 docs/source/usage/config.rst
 create mode 100644 docs/source/usage/dag.rst
 create mode 100644 docs/source/usage/events.rst
 create mode 100644 docs/source/usage/gui.rst
 create mode 100644 docs/source/usage/index.rst
 create mode 100644 docs/source/usage/local.rst
 create mode 100644 docs/source/usage/mcp.rst
 create mode 100644 docs/source/usage/notifications.rst
 create mode 100644 docs/source/usage/plugins.rst
 create mode 100644 docs/source/usage/quickstart.rst
 create mode 100644 docs/source/usage/reliability.rst
 create mode 100644 docs/source/usage/servers.rst
 create mode 100644 docs/source/usage/transfer.rst

diff --git a/docs/source.zh-CN/index.rst b/docs/source.zh-CN/index.rst
index ecc2c05..39a3946 100644
--- a/docs/source.zh-CN/index.rst
+++ b/docs/source.zh-CN/index.rst
@@ -159,10 +159,10 @@ JSON 动作列表就是上述 list 的 list。
 
 .. toctree::
    :maxdepth: 2
-   :caption: 目录
+   :caption: 文档
 
    architecture
-   usage
+   usage/index
    api/index
 
 索引
diff --git a/docs/source.zh-CN/usage.rst b/docs/source.zh-CN/usage.rst
deleted file mode 100644
index 7f80669..0000000
--- a/docs/source.zh-CN/usage.rst
+++ /dev/null
@@ -1,557 +0,0 @@
-使用指南
-========
-
-JSON 动作列表
--------------
-
-动作可采用三种形状之一：
-
-.. code-block:: json
-
-   ["FA_name"]
-   ["FA_name", {"kwarg": "value"}]
-   ["FA_name", ["positional", "args"]]
-
-动作列表是动作的数组。执行器按顺序执行并返回
-``"execute[<index>]: <action>" -> result | repr(error)`` 的映射表。
-
-.. code-block:: python
-
-   from automation_file import execute_action, read_action_json
-
-   results = execute_action([
-       ["FA_create_dir", {"dir_path": "build"}],
-       ["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}],
-       ["FA_zip_dir", {"dir_we_want_to_zip": "build", "zip_name": "build_snapshot"}],
-   ])
-
-   # 或从文件读入：
-   results = execute_action(read_action_json("actions.json"))
-
-校验、dry-run、并行执行
------------------------
-
-.. code-block:: python
-
-   from automation_file import (
-       execute_action, execute_action_parallel, validate_action,
-   )
-
-   # Fail-fast 校验：若有未知名称，执行前即中止整批。
-   execute_action(actions, validate_first=True)
-
-   # Dry-run：记录将调用什么但不实际调用。
-   execute_action(actions, dry_run=True)
-
-   # 并行：通过线程池执行彼此独立的动作。
-   execute_action_parallel(actions, max_workers=4)
-
-   # 手动校验——返回已解析的名称列表。
-   names = validate_action(actions)
-
-CLI
----
-
-执行 JSON 动作列表的旧式参数::
-
-   python -m automation_file --execute_file actions.json
-   python -m automation_file --execute_dir ./actions/
-   python -m automation_file --execute_str '[["FA_create_dir",{"dir_path":"x"}]]'
-   python -m automation_file --create_project ./my_project
-
-一次性操作的子命令::
-
-   python -m automation_file ui
-   python -m automation_file zip ./src out.zip --dir
-   python -m automation_file unzip out.zip ./restored
-   python -m automation_file download https://example.com/file.bin file.bin
-   python -m automation_file create-file hello.txt --content "hi"
-   python -m automation_file server --host 127.0.0.1 --port 9943
-   python -m automation_file http-server --host 127.0.0.1 --port 9944
-   python -m automation_file drive-upload my.txt --token token.json --credentials creds.json
-
-Google Drive
-------------
-
-.. code-block:: python
-
-   from automation_file import driver_instance, drive_upload_to_drive
-
-   driver_instance.later_init("token.json", "credentials.json")
-   drive_upload_to_drive("example.txt")
-
-TCP 动作服务器
---------------
-
-.. code-block:: python
-
-   from automation_file import start_autocontrol_socket_server
-
-   server = start_autocontrol_socket_server(
-       host="localhost", port=9943, shared_secret="optional-secret",
-   )
-   # 稍后：
-   server.shutdown()
-   server.server_close()
-
-设置 ``shared_secret`` 后，客户端必须在 JSON 动作列表之前加上
-``AUTH <secret>\\n`` 前缀。服务器默认仍绑定 loopback，除非显式传入
-``allow_non_loopback=True``，否则拒绝非 loopback 绑定。
-
-HTTP 动作服务器
----------------
-
-.. code-block:: python
-
-   from automation_file import start_http_action_server
-
-   server = start_http_action_server(
-       host="127.0.0.1", port=9944, shared_secret="optional-secret",
-   )
-
-   # 客户端：
-   # curl -H 'Authorization: Bearer optional-secret' \
-   #      -d '[["FA_create_dir",{"dir_path":"x"}]]' \
-   #      http://127.0.0.1:9944/actions
-
-HTTP 响应为 JSON。设置 ``shared_secret`` 后，客户端必须发送
-``Authorization: Bearer <secret>``。
-
-可靠性
-------
-
-对自定义的可调用对象应用重试：
-
-.. code-block:: python
-
-   from automation_file import retry_on_transient
-
-   @retry_on_transient(max_attempts=5, backoff_base=0.5)
-   def flaky_network_call(): ...
-
-对单个动作应用配额限制：
-
-.. code-block:: python
-
-   from automation_file import Quota
-
-   quota = Quota(max_bytes=50 * 1024 * 1024, max_seconds=30.0)
-   with quota.time_budget("bulk-upload"):
-       bulk_upload_work()
-
-路径安全
---------
-
-.. code-block:: python
-
-   from automation_file import safe_join
-
-   target = safe_join("/data/jobs", user_supplied_path)
-   # -> 若解析后的路径逃出 /data/jobs，会抛出 PathTraversalException。
-
-云端 / SFTP 后端
-----------------
-
-每个后端（S3、Azure Blob、Dropbox、SFTP）都随 ``automation_file`` 一并打包，
-并由 :func:`~automation_file.core.action_registry.build_default_registry`
-自动注册。不需要额外安装步骤——对单例调用 ``later_init`` 即可：
-
-.. code-block:: python
-
-   from automation_file import execute_action, s3_instance
-
-   s3_instance.later_init(region_name="us-east-1")
-
-   execute_action([
-       ["FA_s3_upload_file", {"local_path": "report.csv", "bucket": "reports", "key": "report.csv"}],
-   ])
-
-所有后端都提供相同的五个操作：
-``upload_file``、``upload_dir``、``download_file``、``delete_*``、``list_*``。
-``register_<backend>_ops(registry)`` 依然公开，供自行建立注册表的调用方使用。
-
-SFTP 特别使用 :class:`paramiko.RejectPolicy`——未知主机会被拒绝而非自动添加。
-请显式提供 ``known_hosts``，或依赖 ``~/.ssh/known_hosts``。
-
-文件监视触发器
---------------
-
-当被监视路径发生文件系统事件时执行动作列表。模块级的
-:data:`~automation_file.trigger.trigger_manager` 以名称为键维护一组活动
-watcher，让 JSON 接口与 GUI 共享同一个生命周期。
-
-.. code-block:: python
-
-   from automation_file import watch_start, watch_stop
-
-   watch_start(
-       name="inbox-sweeper",
-       path="/data/inbox",
-       action_list=[["FA_copy_all_file_to_dir", {"source_dir": "/data/inbox",
-                                                 "target_dir": "/data/processed"}]],
-       events=["created", "modified"],
-       recursive=False,
-   )
-   # 稍后：
-   watch_stop("inbox-sweeper")
-
-也可以通过 JSON 动作列表以 ``FA_watch_start`` / ``FA_watch_stop`` /
-``FA_watch_stop_all`` / ``FA_watch_list`` 操作。
-
-Cron 调度器
------------
-
-按周期性调度执行动作列表。5 字段 cron 解析器支持 ``*``、精确值、``a-b``
-范围、逗号分隔列表与 ``*/n`` 步进语法，并能使用 ``jan``..``dec`` /
-``sun``..``sat`` 别名。
-
-.. code-block:: python
-
-   from automation_file import schedule_add
-
-   schedule_add(
-       name="nightly-snapshot",
-       cron_expression="0 2 * * *",           # 每日本地时间 02:00
-       action_list=[["FA_zip_dir", {"dir_we_want_to_zip": "/data",
-                                    "zip_name": "/backup/data_nightly"}]],
-   )
-
-后台线程在分钟边界唤醒，因此不支持秒级精度的表达式。可通过 JSON 使用
-``FA_schedule_add`` / ``FA_schedule_remove`` / ``FA_schedule_remove_all`` /
-``FA_schedule_list``。
-
-传输进度与取消
---------------
-
-对 :func:`download_file`、:func:`s3_upload_file` 或 :func:`s3_download_file`
-传入 ``progress_name="<label>"`` 即可把传输注册到共享进度注册表。GUI
-的 **Progress** 标签页每半秒轮询注册表；``FA_progress_list``、
-``FA_progress_cancel`` 与 ``FA_progress_clear`` 让 JSON 动作列表取得同样的视图。
-
-.. code-block:: python
-
-   from automation_file import download_file, progress_cancel
-
-   # 一个线程：
-   download_file("https://example.com/big.bin", "big.bin",
-                 progress_name="big-download")
-
-   # 另一线程 / GUI：
-   progress_cancel("big-download")
-
-取消会在传输循环中抛出 :class:`~automation_file.CancelledException`。
-传输函数会捕捉该异常、将 reporter 标记为 ``status="cancelled"`` 并
-返回 ``False``——调用方不需要自行处理异常。
-
-快速文件搜索
-------------
-
-:func:`fast_find` 会挑选主机上最便宜的后端——优先使用 OS 索引，否则
-流式 scandir 遍历——以最小能耗扫描大型目录树：
-
-* macOS： ``mdfind`` （Spotlight）
-* Linux： ``plocate`` / ``locate`` 数据库
-* Windows：若已安装 Everything 的 ``es.exe`` CLI
-* 兜底： ``os.scandir`` 生成器 + ``fnmatch`` 匹配，并以 ``limit=`` 提前终止
-
-.. code-block:: python
-
-   from automation_file import fast_find, scandir_find, has_os_index
-
-   # 有索引时查询索引，否则退化到 scandir。
-   results = fast_find("/var/log", "*.log", limit=100)
-
-   # 强制走可移植路径（跳过 OS 索引）。
-   results = fast_find("/data", "report_*.csv", use_index=False)
-
-   # 流式生成器——无需扫描整棵树即可提前终止。
-   for path in scandir_find("/data", "*.csv"):
-       if "2026" in path:
-           break
-
-   # fast_find 会尝试哪个索引？返回 "mdfind" / "locate" /
-   # "plocate" / "es" / None。
-   has_os_index()
-
-JSON 动作列表也可使用 ``FA_fast_find``：
-
-.. code-block:: json
-
-   [["FA_fast_find", {"root": "/var/log", "pattern": "*.log", "limit": 50}]]
-
-校验和与完整性校验
-------------------
-
-以流式读取器（支持 :mod:`hashlib` 的任何算法）哈希任何文件，并以
-常数时间比较来验证预期摘要：
-
-.. code-block:: python
-
-   from automation_file import file_checksum, verify_checksum
-
-   digest = file_checksum("bundle.tar.gz")                 # 默认 sha256
-   verify_checksum("bundle.tar.gz", digest)                # -> True
-   verify_checksum("bundle.tar.gz", "deadbeef...", algorithm="blake2b")
-
-相同函数在 JSON 动作列表中是 ``FA_file_checksum`` 与
-``FA_verify_checksum``。
-
-可续传 HTTP 下载
-----------------
-
-:func:`~automation_file.download_file` 接受 ``resume=True``。内容会写入
-``<target>.part``；若临时文件已存在，下次调用会发送 ``Range: bytes=<n>-``
-让传输从先前停止处续传。结合 ``expected_sha256=`` 可在最后一块写入后
-立即校验下载：
-
-.. code-block:: python
-
-   from automation_file import download_file
-
-   download_file(
-       "https://example.com/big.bin",
-       "big.bin",
-       resume=True,
-       expected_sha256="3b0c44298fc1...",
-   )
-
-文件去重
---------
-
-:func:`~automation_file.find_duplicates` 以 ``os.scandir`` 遍历目录树一次，
-并执行三阶段 size → partial-hash → full-hash 流水线。拥有唯一大小的文件
-完全不会被哈希，因此数百万文件的树扫描仍然便宜：
-
-.. code-block:: python
-
-   from automation_file import find_duplicates
-
-   groups = find_duplicates("/data", min_size=1024)
-   # groups: list[list[str]]，每个内层列表为一组完全相同的文件，
-   # 按大小降序排序。
-
-``FA_find_duplicates`` 公开同一个调用给 JSON 动作列表使用。
-
-目录增量同步
-------------
-
-:func:`~automation_file.sync_dir` 把 ``src`` 镜像到 ``dst``，只复制新的
-或已变更的文件。变更检测默认为 ``(size, mtime)``；当 mtime 不可靠时
-请传入 ``compare="checksum"``。``dst`` 下的额外文件默认不会动到，
-需传入 ``delete=True`` 才会删除（并可用 ``dry_run=True`` 预览）：
-
-.. code-block:: python
-
-   from automation_file import sync_dir
-
-   summary = sync_dir("/data/src", "/data/dst", delete=True)
-   # summary: {"copied": [...], "skipped": [...], "deleted": [...],
-   #           "errors": [...], "dry_run": False}
-
-JSON 动作形式为 ``FA_sync_dir``。符号链接会以符号链接重建而非跟随，
-因此指向目录树外的链接不会把镜像搞砸。
-
-目录清单快照
-------------
-
-把目录树下所有文件的 JSON 清单写下来，稍后校验目录树未被变动。
-适用于发布产物校验、备份完整性检查、移动前的飞行前检查：
-
-.. code-block:: python
-
-   from automation_file import write_manifest, verify_manifest
-
-   write_manifest("/release/payload", "/release/MANIFEST.json")
-
-   # 稍后……
-   result = verify_manifest("/release/payload", "/release/MANIFEST.json")
-   if not result["ok"]:
-       raise SystemExit(f"manifest mismatch: {result}")
-
-``result`` 分别报告 ``matched``、``missing``、``modified``、``extra`` 列表。
-额外文件不算校验失败（与 ``sync_dir`` 的“默认不删除”行为一致）；
-``missing`` 或 ``modified`` 则会。这两个操作以 ``FA_write_manifest``
-与 ``FA_verify_manifest`` 暴露给 JSON 动作列表。
-
-通知
-----
-
-通过 webhook、Slack 或 SMTP 推送一次性消息，或在触发器 / 调度器失败时
-自动通知：
-
-.. code-block:: python
-
-   from automation_file import (
-       SlackSink, WebhookSink, EmailSink,
-       notification_manager, notify_send,
-   )
-
-   notification_manager.register(SlackSink("https://hooks.slack.com/services/T/B/X"))
-   notify_send("deploy complete", body="rev abc123", level="info")
-
-每个 sink 都实现同样的 ``send(subject, body, level)`` 接口，扇出
-:class:`~automation_file.NotificationManager` 负责：
-
-- 每个 sink 的错误隔离——一个故障 sink 不会让其他 sink 饿死。
-- 滑动窗口去重——在 ``dedup_seconds`` 内，完全相同的
-  ``(subject, body, level)`` 消息会被丢弃，避免卡住的触发器灌爆通道。
-- 对每个 webhook / Slack URL 做 SSRF 校验。
-
-调度器与触发器调度器会在失败时以 ``level="error"`` 自动通知——只要
-注册 sink 即可获得生产告警。JSON 动作形式为 ``FA_notify_send`` 与
-``FA_notify_list``。
-
-配置文件与密钥提供者
---------------------
-
-把通知 sink 与默认值一次写在 TOML 文件里。密钥引用在加载时会从环境变量
-或文件根目录解析（Docker / K8s 风格）：
-
-.. code-block:: toml
-
-   # automation_file.toml
-
-   [secrets]
-   file_root = "/run/secrets"
-
-   [defaults]
-   dedup_seconds = 120
-
-   [[notify.sinks]]
-   type = "slack"
-   name = "team-alerts"
-   webhook_url = "${env:SLACK_WEBHOOK}"
-
-   [[notify.sinks]]
-   type = "email"
-   name = "ops-email"
-   host = "smtp.example.com"
-   port = 587
-   sender = "alerts@example.com"
-   recipients = ["ops@example.com"]
-   username = "${env:SMTP_USER}"
-   password = "${file:smtp_password}"
-
-.. code-block:: python
-
-   from automation_file import AutomationConfig, notification_manager
-
-   config = AutomationConfig.load("automation_file.toml")
-   config.apply_to(notification_manager)
-
-未解析的 ``${…}`` 引用会抛出
-:class:`~automation_file.SecretNotFoundException` 而非悄悄变成空字符串。
-自定义的 provider 链可通过 :class:`~automation_file.ChainedSecretProvider` /
-:class:`~automation_file.EnvSecretProvider` /
-:class:`~automation_file.FileSecretProvider` 组装，并传给
-``AutomationConfig.load(path, provider=…)``。
-
-DAG 动作执行器
---------------
-
-:func:`~automation_file.execute_action_dag` 按依赖关系执行动作。每个节点
-形如 ``{"id": str, "action": [name, ...], "depends_on": [id, ...]}``。
-彼此独立的分支在线程池中扇出；当节点失败时，其后续依赖会被标记为
-``skipped``（``fail_fast=True``，默认）或仍会执行（``fail_fast=False``）：
-
-.. code-block:: python
-
-   from automation_file import execute_action_dag
-
-   results = execute_action_dag([
-       {"id": "fetch",  "action": ["FA_download_file",
-                                   ["https://example.com/src.tar.gz", "src.tar.gz"]]},
-       {"id": "verify", "action": ["FA_verify_checksum",
-                                   ["src.tar.gz", "3b0c44298fc1..."]],
-                        "depends_on": ["fetch"]},
-       {"id": "unpack", "action": ["FA_unzip_file", ["src.tar.gz", "src"]],
-                        "depends_on": ["verify"]},
-       {"id": "report", "action": ["FA_fast_find", ["src", "*.py"]],
-                        "depends_on": ["unpack"]},
-   ])
-
-环路、未知依赖、自依赖与重复 id 会在任何节点执行前抛出
-:class:`~automation_file.exceptions.DagException`。JSON 动作形式为
-``FA_execute_action_dag``。
-
-Entry-point 插件
-----------------
-
-第三方包可在自己的 ``pyproject.toml`` 中声明 ``automation_file.actions``
-entry point，以注册自己的 ``FA_*`` 命令::
-
-   [project.entry-points."automation_file.actions"]
-   my_plugin = "my_plugin:register"
-
-其中 ``register`` 是零参数的可调用对象，返回
-``Mapping[str, Callable]``。插件安装到同一个虚拟环境后，
-:func:`~automation_file.core.action_registry.build_default_registry`
-会自动采用——调用端无需任何修改：
-
-.. code-block:: python
-
-   # my_plugin/__init__.py
-   def greet(name: str) -> str:
-       return f"hello {name}"
-
-   def register() -> dict:
-       return {"FA_greet": greet}
-
-.. code-block:: python
-
-   # 消费端（执行 `pip install my_plugin` 之后）
-   from automation_file import execute_action
-   execute_action([["FA_greet", {"name": "world"}]])
-
-插件失败（导入错误、factory 异常、返回形状错误、注册表拒绝）会被记录
-并吞掉，一个坏插件不会破坏整个库。
-
-GUI（PySide6）
---------------
-
-标签式控制界面把每项功能都包起来：
-
-.. code-block:: bash
-
-   python -m automation_file ui
-   # 或在 repo 根目录以开发模式执行：
-   python main_ui.py
-
-.. code-block:: python
-
-   from automation_file import launch_ui
-
-   launch_ui()
-
-标签页：Home、Local、Transfer、Progress、JSON actions、Triggers、Scheduler、
-Servers。标签页下方的常驻 log panel 会实时流式推送每次调用的结果或错误。
-后台工作通过 ``ActionWorker`` 在 ``QThreadPool`` 上执行，保持 UI 响应灵敏。
-
-添加自定义命令
---------------
-
-.. code-block:: python
-
-   from automation_file import add_command_to_executor, execute_action
-
-   def greet(name: str) -> str:
-       return f"hello {name}"
-
-   add_command_to_executor({"greet": greet})
-   execute_action([["greet", {"name": "world"}]])
-
-动态包注册
-----------
-
-.. code-block:: python
-
-   from automation_file import package_manager, execute_action
-
-   package_manager.add_package_to_executor("math")
-   execute_action([["math_sqrt", [16.0]]])   # -> 4.0
-
-.. warning::
-
-   ``package_manager.add_package_to_executor`` 实际上会注册包中所有顶层
-   函数 / 类 / 内置对象。切勿把它暴露给不受信任的输入（例如通过 TCP 或
-   HTTP 服务器）。
diff --git a/docs/source.zh-CN/usage/cli.rst b/docs/source.zh-CN/usage/cli.rst
new file mode 100644
index 0000000..1de5e1b
--- /dev/null
+++ b/docs/source.zh-CN/usage/cli.rst
@@ -0,0 +1,25 @@
+CLI
+===
+
+执行 JSON 动作列表的旧式参数::
+
+   python -m automation_file --execute_file actions.json
+   python -m automation_file --execute_dir ./actions/
+   python -m automation_file --execute_str '[["FA_create_dir",{"dir_path":"x"}]]'
+   python -m automation_file --create_project ./my_project
+
+一次性操作的子命令::
+
+   python -m automation_file ui
+   python -m automation_file zip ./src out.zip --dir
+   python -m automation_file unzip out.zip ./restored
+   python -m automation_file download https://example.com/file.bin file.bin
+   python -m automation_file create-file hello.txt --content "hi"
+   python -m automation_file server --host 127.0.0.1 --port 9943
+   python -m automation_file http-server --host 127.0.0.1 --port 9944
+   python -m automation_file mcp --allowed-actions FA_list_dir,FA_file_checksum
+   python -m automation_file drive-upload my.txt --token token.json --credentials creds.json
+
+``mcp`` 子命令通过 stdio 启动 Model Context Protocol 服务器，
+让 Claude Desktop 这类宿主可以把 ``FA_*`` 动作当作 MCP 工具调用——完整集成
+说明请见 :doc:`mcp`。
diff --git a/docs/source.zh-CN/usage/cloud.rst b/docs/source.zh-CN/usage/cloud.rst
new file mode 100644
index 0000000..2efe62d
--- /dev/null
+++ b/docs/source.zh-CN/usage/cloud.rst
@@ -0,0 +1,60 @@
+云与 SFTP 后端
+==============
+
+每个后端（Google Drive、S3、Azure Blob、Dropbox、SFTP）都是
+``automation_file`` 自带的，并由
+:func:`~automation_file.core.action_registry.build_default_registry` 自动注册。
+无需额外安装步骤——在单例上调用 ``later_init`` 即可使用：
+
+.. code-block:: python
+
+   from automation_file import execute_action, s3_instance
+
+   s3_instance.later_init(region_name="us-east-1")
+
+   execute_action([
+       ["FA_s3_upload_file", {"local_path": "report.csv",
+                              "bucket": "reports", "key": "report.csv"}],
+   ])
+
+所有后端都暴露同样的五种操作：``upload_file``、``upload_dir``、
+``download_file``、``delete_*``、``list_*``。如需构建自定义注册表，
+``register_<backend>_ops(registry)`` 仍然是公开 API。
+
+Google Drive
+------------
+
+.. code-block:: python
+
+   from automation_file import driver_instance, drive_upload_to_drive
+
+   driver_instance.later_init("token.json", "credentials.json")
+   drive_upload_to_drive("example.txt")
+
+OAuth 凭证以 UTF-8 写在调用方提供的 ``token_path``。
+切勿打印或记录该文件内容。
+
+SFTP
+----
+
+:class:`~automation_file.SFTPClient` 使用 :class:`paramiko.RejectPolicy`——
+未知主机会被拒绝，而不是自动加入。请显式提供 ``known_hosts=`` 或依赖
+``~/.ssh/known_hosts``。不要为图省事改用 ``AutoAddPolicy``。
+
+跨后端复制
+----------
+
+跨后端调度器接受 URI 语法：
+
+.. code-block:: python
+
+   from automation_file import execute_action
+
+   execute_action([
+       ["FA_cross_copy",
+        {"src": "s3://reports/2026-04.csv",
+         "dst": "drive:///Backups/april.csv"}],
+   ])
+
+URI 前缀：``local://``、``s3://``、``drive://``、``sftp://``、
+``azure://``、``dropbox://``、``ftp://``。
diff --git a/docs/source.zh-CN/usage/config.rst b/docs/source.zh-CN/usage/config.rst
new file mode 100644
index 0000000..72d715e
--- /dev/null
+++ b/docs/source.zh-CN/usage/config.rst
@@ -0,0 +1,45 @@
+配置文件与机密 provider
+=======================
+
+把通知 sink 与默认值集中声明在一份 TOML 文件里。
+机密引用在加载时从环境变量或文件根目录（Docker / K8s 风格）解析：
+
+.. code-block:: toml
+
+   # automation_file.toml
+
+   [secrets]
+   file_root = "/run/secrets"
+
+   [defaults]
+   dedup_seconds = 120
+
+   [[notify.sinks]]
+   type = "slack"
+   name = "team-alerts"
+   webhook_url = "${env:SLACK_WEBHOOK}"
+
+   [[notify.sinks]]
+   type = "email"
+   name = "ops-email"
+   host = "smtp.example.com"
+   port = 587
+   sender = "alerts@example.com"
+   recipients = ["ops@example.com"]
+   username = "${env:SMTP_USER}"
+   password = "${file:smtp_password}"
+
+.. code-block:: python
+
+   from automation_file import AutomationConfig, notification_manager
+
+   config = AutomationConfig.load("automation_file.toml")
+   config.apply_to(notification_manager)
+
+未解析的 ``${…}`` 引用会抛出
+:class:`~automation_file.SecretNotFoundException`，
+而不是悄悄变成空字符串。需要自定义 provider 链时，可以使用
+:class:`~automation_file.ChainedSecretProvider` /
+:class:`~automation_file.EnvSecretProvider` /
+:class:`~automation_file.FileSecretProvider`，
+并通过 ``AutomationConfig.load(path, provider=…)`` 传入。
diff --git a/docs/source.zh-CN/usage/dag.rst b/docs/source.zh-CN/usage/dag.rst
new file mode 100644
index 0000000..6fc8a3c
--- /dev/null
+++ b/docs/source.zh-CN/usage/dag.rst
@@ -0,0 +1,28 @@
+DAG 动作执行器
+==============
+
+:func:`~automation_file.execute_action_dag` 按依赖顺序运行动作。
+每个节点形如 ``{"id": str, "action": [name, ...], "depends_on":
+[id, ...]}``。互不依赖的分支通过线程池并行展开；
+当节点失败时，其传递依赖的下游会被标记为 ``skipped``
+（默认 ``fail_fast=True``）或仍然继续运行（``fail_fast=False``）：
+
+.. code-block:: python
+
+   from automation_file import execute_action_dag
+
+   results = execute_action_dag([
+       {"id": "fetch",  "action": ["FA_download_file",
+                                   ["https://example.com/src.tar.gz", "src.tar.gz"]]},
+       {"id": "verify", "action": ["FA_verify_checksum",
+                                   ["src.tar.gz", "3b0c44298fc1..."]],
+                        "depends_on": ["fetch"]},
+       {"id": "unpack", "action": ["FA_unzip_file", ["src.tar.gz", "src"]],
+                        "depends_on": ["verify"]},
+       {"id": "report", "action": ["FA_fast_find", ["src", "*.py"]],
+                        "depends_on": ["unpack"]},
+   ])
+
+环、未知依赖、自环依赖与重复 id 都会在任何节点运行前抛出
+:class:`~automation_file.exceptions.DagException`。
+JSON 形式：``FA_execute_action_dag``。
diff --git a/docs/source.zh-CN/usage/events.rst b/docs/source.zh-CN/usage/events.rst
new file mode 100644
index 0000000..a5763bd
--- /dev/null
+++ b/docs/source.zh-CN/usage/events.rst
@@ -0,0 +1,58 @@
+触发器与调度器
+==============
+
+文件监听触发器
+--------------
+
+当被监听的路径上有文件系统事件时，自动执行一份动作列表。
+模块级的 :data:`~automation_file.trigger.trigger_manager` 维护一份
+按名称索引的活跃监听器表，让 JSON 外观与 GUI 共用同一份生命周期。
+
+.. code-block:: python
+
+   from automation_file import watch_start, watch_stop
+
+   watch_start(
+       name="inbox-sweeper",
+       path="/data/inbox",
+       action_list=[["FA_copy_all_file_to_dir",
+                     {"source_dir": "/data/inbox",
+                      "target_dir": "/data/processed"}]],
+       events=["created", "modified"],
+       recursive=False,
+   )
+   # 稍后：
+   watch_stop("inbox-sweeper")
+
+也可以从 JSON 动作列表里调用 ``FA_watch_start`` /
+``FA_watch_stop`` / ``FA_watch_stop_all`` / ``FA_watch_list``。
+
+Cron 调度器
+-----------
+
+按重复时刻执行动作列表。5 字段 cron 解析器支持
+``*``、精确值、``a-b`` 区间、逗号分隔列表与 ``*/n`` 步长，
+也支持 ``jan``..``dec`` / ``sun``..``sat`` 别名。
+
+.. code-block:: python
+
+   from automation_file import schedule_add
+
+   schedule_add(
+       name="nightly-snapshot",
+       cron_expression="0 2 * * *",           # 每天本地时间 02:00
+       action_list=[["FA_zip_dir", {"dir_we_want_to_zip": "/data",
+                                    "zip_name": "/backup/data_nightly"}]],
+   )
+
+后台线程在每分钟边界唤醒，因此不支持小于一分钟的精度。
+JSON 形式：``FA_schedule_add`` / ``FA_schedule_remove`` /
+``FA_schedule_remove_all`` / ``FA_schedule_list``。
+
+当动作列表抛出
+:class:`~automation_file.exceptions.FileAutomationException` 时，
+两个调度器都会调用
+:func:`~automation_file.notify.manager.notify_on_failure`。
+若未注册任何 sink，该助手是 no-op，因此自动通知是
+注册 :class:`~automation_file.NotificationSink` 的可选副作用——
+详见 :doc:`notifications`。
diff --git a/docs/source.zh-CN/usage/gui.rst b/docs/source.zh-CN/usage/gui.rst
new file mode 100644
index 0000000..ef8f650
--- /dev/null
+++ b/docs/source.zh-CN/usage/gui.rst
@@ -0,0 +1,24 @@
+GUI（PySide6）
+==============
+
+分页式控制面板封装了所有功能：
+
+.. code-block:: bash
+
+   python -m automation_file ui
+   # 或在仓库根目录开发时：
+   python main_ui.py
+
+.. code-block:: python
+
+   from automation_file import launch_ui
+
+   launch_ui()
+
+标签页：Home、Local、Transfer、Progress、JSON actions、Triggers、
+Scheduler、Servers。所有标签页下方共用一个常驻日志面板，
+逐条输出每次调用的结果或错误。后台任务通过 ``ActionWorker`` 在
+``QThreadPool`` 上执行，UI 始终保持响应。
+
+GUI 与库其余部分共用同一组单例——从 Python 注册的 sink、
+自定义动作、触发器都会立即在运行中的窗口生效。
diff --git a/docs/source.zh-CN/usage/index.rst b/docs/source.zh-CN/usage/index.rst
new file mode 100644
index 0000000..93c571d
--- /dev/null
+++ b/docs/source.zh-CN/usage/index.rst
@@ -0,0 +1,43 @@
+使用指南
+========
+
+使用指南按主题分章。每一节都是自包含的——挑选你需要的后端或功能直接进入即可。
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 入门
+
+   quickstart
+   cli
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 本地与传输
+
+   local
+   transfer
+   cloud
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 服务器与集成
+
+   servers
+   mcp
+   gui
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 可靠性与事件
+
+   reliability
+   events
+   notifications
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 配置与扩展
+
+   config
+   dag
+   plugins
diff --git a/docs/source.zh-CN/usage/local.rst b/docs/source.zh-CN/usage/local.rst
new file mode 100644
index 0000000..df42e6e
--- /dev/null
+++ b/docs/source.zh-CN/usage/local.rst
@@ -0,0 +1,122 @@
+本地文件操作
+============
+
+路径安全
+--------
+
+.. code-block:: python
+
+   from automation_file import safe_join
+
+   target = safe_join("/data/jobs", user_supplied_path)
+   # -> 若解析后的路径越过 /data/jobs，将抛出 PathTraversalException。
+
+任何用户提供的路径都应通过
+:func:`~automation_file.local.safe_paths.safe_join`（或 ``is_within``
+判断）解析。直接拼接 + ``Path.resolve()`` 会被符号链接和 ``..`` 段绕过。
+
+快速文件查找
+------------
+
+:func:`~automation_file.fast_find` 会挑选当前主机上代价最低的后端——
+优先使用操作系统索引，否则回退为流式 scandir 走查，
+让大目录树以最低开销被搜索：
+
+* macOS：``mdfind``（Spotlight）
+* Linux：``plocate`` / ``locate`` 数据库
+* Windows：若已安装则使用 Everything 的 ``es.exe`` CLI
+* 回退：``os.scandir`` 生成器配合 ``fnmatch`` 匹配，可由 ``limit=`` 提前终止
+
+.. code-block:: python
+
+   from automation_file import fast_find, scandir_find, has_os_index
+
+   # 若有索引则查询，否则回退 scandir。
+   results = fast_find("/var/log", "*.log", limit=100)
+
+   # 强制走可移植路径（不使用操作系统索引）。
+   results = fast_find("/data", "report_*.csv", use_index=False)
+
+   # 流式生成器——可不扫描整棵树就提前停止。
+   for path in scandir_find("/data", "*.csv"):
+       if "2026" in path:
+           break
+
+   # fast_find 将尝试哪种索引？返回 "mdfind" / "locate" /
+   # "plocate" / "es" / None。
+   has_os_index()
+
+JSON 形式：``[["FA_fast_find", {"root": "/var/log", "pattern": "*.log",
+"limit": 50}]]``。
+
+校验和与完整性
+--------------
+
+以流式方式哈希任意文件（任何 :mod:`hashlib` 算法），
+使用常数时间比较来对照预期摘要：
+
+.. code-block:: python
+
+   from automation_file import file_checksum, verify_checksum
+
+   digest = file_checksum("bundle.tar.gz")                 # 默认 sha256
+   verify_checksum("bundle.tar.gz", digest)                # -> True
+   verify_checksum("bundle.tar.gz", "deadbeef...", algorithm="blake2b")
+
+JSON 形式：``FA_file_checksum`` / ``FA_verify_checksum``。
+
+文件去重
+--------
+
+:func:`~automation_file.find_duplicates` 通过 ``os.scandir`` 一次性
+走查目录树，并以「大小 → 部分哈希 → 全量哈希」三段式进行筛选。
+大小唯一的文件根本不会被哈希，因此即使百万级别也能廉价扫描：
+
+.. code-block:: python
+
+   from automation_file import find_duplicates
+
+   groups = find_duplicates("/data", min_size=1024)
+   # groups: list[list[str]]，每个内层列表都是互相重复的文件，按大小降序。
+
+JSON 形式：``FA_find_duplicates``。
+
+增量目录同步
+------------
+
+:func:`~automation_file.sync_dir` 把 ``src`` 增量镜像到 ``dst``，仅复制
+新增或变更的文件。默认按 ``(size, mtime)`` 检测变化；
+当 mtime 不可靠时改用 ``compare="checksum"``。``dst`` 中的多余文件默认保留——
+传入 ``delete=True`` 才会清理（``dry_run=True`` 可预览）：
+
+.. code-block:: python
+
+   from automation_file import sync_dir
+
+   summary = sync_dir("/data/src", "/data/dst", delete=True)
+   # summary: {"copied": [...], "skipped": [...], "deleted": [...],
+   #           "errors": [...], "dry_run": False}
+
+符号链接会按链接重新创建而不是被跟随。JSON 形式：``FA_sync_dir``。
+
+目录清单
+--------
+
+把整棵目录树的每个文件写入 JSON 清单，稍后再校验目录是否变化。
+适合用于发布产物校验、备份完整性检查与移动前的预检：
+
+.. code-block:: python
+
+   from automation_file import write_manifest, verify_manifest
+
+   write_manifest("/release/payload", "/release/MANIFEST.json")
+
+   # 之后……
+   result = verify_manifest("/release/payload", "/release/MANIFEST.json")
+   if not result["ok"]:
+       raise SystemExit(f"manifest mismatch: {result}")
+
+``result`` 会分别报告 ``matched`` / ``missing`` / ``modified`` / ``extra``。
+多余文件不会让校验失败（与 ``sync_dir`` 默认不删除一致）；
+``missing`` 与 ``modified`` 才会失败。JSON 形式：
+``FA_write_manifest`` / ``FA_verify_manifest``。
diff --git a/docs/source.zh-CN/usage/mcp.rst b/docs/source.zh-CN/usage/mcp.rst
new file mode 100644
index 0000000..a6d6f93
--- /dev/null
+++ b/docs/source.zh-CN/usage/mcp.rst
@@ -0,0 +1,189 @@
+MCP 服务器（Claude Desktop / Claude Code）
+==========================================
+
+``automation_file`` 自带一个 Model Context Protocol（MCP）服务器，
+将共享的 :class:`~automation_file.core.action_registry.ActionRegistry`
+中的每一项暴露为 MCP 工具。**Claude Desktop**、**Claude Code**
+以及其他 MCP 宿主，可以像调用普通 MCP 工具一样调用 ``FA_*`` 动作——
+无需自写插件，无需额外打包。
+
+传输方式为 **stdio**（``stdin`` / ``stdout`` 上每行一条 JSON-RPC 2.0 消息），
+与目前 MCP 宿主使用的协议一致。
+
+提供的能力
+----------
+
+* ``initialize`` 握手，返回协议版本 ``2024-11-05``、
+  ``serverInfo.name`` 与 ``serverInfo.version``。
+* ``tools/list`` 为每个已注册的 ``FA_*`` 动作返回一个 MCP 工具描述，
+  其参数 JSON Schema 由 Python 函数签名自动派生
+  （``str → "string"``、``int → "integer"`` 等）。
+* ``tools/call`` 通过注册表派发，并以 JSON 编码后的文本内容块返回结果。
+* ``--allowed-actions`` 允许列表参数，让你只把注册表的子集暴露给宿主。
+* 所有内部错误都会以 JSON-RPC 错误对象形式返回——
+  宿主无需解析异常字符串即可呈现错误。
+
+启动服务器
+----------
+
+CLI::
+
+   python -m automation_file mcp
+   python -m automation_file mcp --name automation_file --version 1.0.0
+   python -m automation_file mcp --allowed-actions FA_list_dir,FA_file_checksum
+
+进程在前台运行，从 ``stdin`` 读取分行 JSON 并把响应写到 ``stdout``。
+通常宿主会替你启动该进程，不需要手工运行。
+
+从 Python 启动（例如嵌入到自家 stdio 桥接器里）：
+
+.. code-block:: python
+
+   from automation_file import MCPServer
+
+   server = MCPServer(name="automation_file", version="1.0.0")
+   server.serve_stdio()        # stdin 关闭前阻塞
+
+通过自定义注册表把可调用动作面缩小：
+
+.. code-block:: python
+
+   from automation_file import MCPServer
+   from automation_file.core.action_registry import ActionRegistry
+   from automation_file import executor
+
+   safe = ActionRegistry()
+   for name in ("FA_list_dir", "FA_file_checksum", "FA_fast_find"):
+       safe.register(name, executor.registry.resolve(name))
+
+   MCPServer(safe).serve_stdio()
+
+Claude Desktop 配置
+-------------------
+
+在 ``~/Library/Application Support/Claude/claude_desktop_config.json``
+（macOS）或 ``%APPDATA%\Claude\claude_desktop_config.json``
+（Windows）的 ``mcpServers`` 下添加条目：
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "automation_file": {
+         "command": "python",
+         "args": ["-m", "automation_file", "mcp"]
+       }
+     }
+   }
+
+重启 Claude Desktop。``automation_file`` 服务器会出现在工具面板中，
+所有 ``FA_*`` 动作都可被调用。
+
+对于操作敏感路径的宿主，建议把可用动作锁死为白名单：
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "automation_file": {
+         "command": "python",
+         "args": [
+           "-m", "automation_file", "mcp",
+           "--allowed-actions",
+           "FA_list_dir,FA_fast_find,FA_file_checksum,FA_verify_checksum"
+         ]
+       }
+     }
+   }
+
+显式指定虚拟环境的解释器（避免误用系统 Python）：
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "automation_file": {
+         "command": "C:\\envs\\fa\\Scripts\\python.exe",
+         "args": ["-m", "automation_file", "mcp"]
+       }
+     }
+   }
+
+Claude Code 配置
+----------------
+
+Claude Code 使用同一份 MCP 定义。可通过 ``claude mcp add`` CLI 注册::
+
+   claude mcp add automation_file -- python -m automation_file mcp
+
+或在仓库根目录提交 ``.mcp.json``：
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "automation_file": {
+         "command": "python",
+         "args": ["-m", "automation_file", "mcp"]
+       }
+     }
+   }
+
+加载完成后，要求 Claude Code 使用 ``mcp__automation_file__FA_*`` 工具——
+例如「使用 FA_fast_find 找出 ./var 下所有 *.log」。
+
+查看工具目录
+------------
+
+可渲染与宿主完全一致的描述符——便于测试、GUI 调试或生成文档：
+
+.. code-block:: python
+
+   from automation_file import tools_from_registry, executor
+
+   for tool in tools_from_registry(executor.registry):
+       print(tool["name"], "->", tool["description"])
+
+每个描述符的形状如下::
+
+   {
+     "name": "FA_fast_find",
+     "description": "底层可调用对象的第一行 docstring。",
+     "inputSchema": {
+       "type": "object",
+       "properties": {"root": {"type": "string"}, "pattern": {"type": "string"}},
+       "required": ["root", "pattern"],
+       "additionalProperties": true,
+     },
+   }
+
+手工烟雾测试
+------------
+
+直接把 JSON-RPC 帧喂给服务器以确认其能正常加载::
+
+   printf '%s\n%s\n%s\n' \
+     '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
+     '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+     '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"FA_fast_find","arguments":{"root":".","pattern":"*.py","limit":3}}}' \
+     | python -m automation_file mcp
+
+每行输入在 stdout 上恰得到一条 JSON-RPC 响应（通知没有响应）。
+
+安全注意事项
+------------
+
+* MCP 服务器以 **启动它的 Python 进程的权限** 运行。
+  每次工具调用都落在你 shell 用户账户里。
+* 默认情况下，服务器暴露 **全部** 已注册的 ``FA_*`` 动作，
+  其中包含会删除文件、写文件系统、上传到远程后端的动作。
+  对任何不完全可信的宿主，请用 ``--allowed-actions`` 只白名单暴露
+  必要的动作。
+* 在打算给第三方宿主使用的 MCP 服务器启动前，**不要** 调用
+  :func:`~automation_file.PackageLoader.add_package_to_executor`
+  （或暴露其动作）。该助手会注册任意包的全部顶层函数 / 类 / 内置，
+  权限相当于 ``eval``。
+* 服务器启动时会通过 ``file_automation_logger`` 以 ``INFO`` 级别记录
+  暴露的工具数量与配置的服务器名称。工具调用负载从不被记录。
+* 涉及对外 HTTP 的动作（``FA_download_file``、各云后端）仍会通过
+  SSRF 校验；MCP 层不会放宽任何单动作检查。
diff --git a/docs/source.zh-CN/usage/notifications.rst b/docs/source.zh-CN/usage/notifications.rst
new file mode 100644
index 0000000..d18769e
--- /dev/null
+++ b/docs/source.zh-CN/usage/notifications.rst
@@ -0,0 +1,27 @@
+通知
+====
+
+可主动推送消息，也可在触发器 / 调度器失败时自动通知，
+支持 webhook、Slack 与 SMTP：
+
+.. code-block:: python
+
+   from automation_file import (
+       SlackSink, WebhookSink, EmailSink,
+       notification_manager, notify_send,
+   )
+
+   notification_manager.register(SlackSink("https://hooks.slack.com/services/T/B/X"))
+   notify_send("deploy complete", body="rev abc123", level="info")
+
+每个 sink 都实现相同的 ``send(subject, body, level)`` 契约；
+扇出 :class:`~automation_file.NotificationManager` 负责：
+
+- **逐 sink 错误隔离** —— 一个坏 sink 不会拖累其他。
+- **滑动窗口去重** —— ``dedup_seconds`` 内相同的
+  ``(subject, body, level)`` 会被丢弃，防止卡住的触发器把通道刷爆。
+- **SSRF 校验** —— 每个 webhook / Slack URL 都会被检查。
+
+调度器与触发器在失败时会自动以 ``level="error"`` 通知——
+只要注册任意一个 sink，就能拿到生产告警。JSON 形式：
+``FA_notify_send`` / ``FA_notify_list``。
diff --git a/docs/source.zh-CN/usage/plugins.rst b/docs/source.zh-CN/usage/plugins.rst
new file mode 100644
index 0000000..48affa0
--- /dev/null
+++ b/docs/source.zh-CN/usage/plugins.rst
@@ -0,0 +1,50 @@
+插件与动态注册
+==============
+
+入口点插件
+----------
+
+第三方包可以通过在 ``pyproject.toml`` 声明
+``automation_file.actions`` 入口点，注册自己的 ``FA_*`` 命令::
+
+   [project.entry-points."automation_file.actions"]
+   my_plugin = "my_plugin:register"
+
+其中 ``register`` 是一个零参可调用对象，返回
+``Mapping[str, Callable]``。一旦插件安装到同一个 venv，
+:func:`~automation_file.core.action_registry.build_default_registry`
+会自动拾取——调用方无需任何改动：
+
+.. code-block:: python
+
+   # my_plugin/__init__.py
+   def greet(name: str) -> str:
+       return f"hello {name}"
+
+   def register() -> dict:
+       return {"FA_greet": greet}
+
+.. code-block:: python
+
+   # 安装后的消费方代码：
+   from automation_file import execute_action
+   execute_action([["FA_greet", {"name": "world"}]])
+
+插件失败（导入错误、工厂异常、返回形状不对、被注册表拒绝）
+会被记录并吞掉，单个坏插件不会拖垮整个库。
+
+动态包注册
+----------
+
+.. code-block:: python
+
+   from automation_file import package_manager, execute_action
+
+   package_manager.add_package_to_executor("math")
+   execute_action([["math_sqrt", [16.0]]])   # -> 4.0
+
+.. warning::
+
+   ``package_manager.add_package_to_executor`` 会注册任意包的全部
+   顶层函数 / 类 / 内置。**切勿** 暴露给不可信输入
+   （例如通过 TCP、HTTP 或 :doc:`mcp` 服务器）。
diff --git a/docs/source.zh-CN/usage/quickstart.rst b/docs/source.zh-CN/usage/quickstart.rst
new file mode 100644
index 0000000..357a435
--- /dev/null
+++ b/docs/source.zh-CN/usage/quickstart.rst
@@ -0,0 +1,65 @@
+快速开始
+========
+
+JSON 动作列表
+-------------
+
+动作可采用三种形状之一：
+
+.. code-block:: json
+
+   ["FA_name"]
+   ["FA_name", {"kwarg": "value"}]
+   ["FA_name", ["positional", "args"]]
+
+动作列表是动作的数组。执行器按顺序执行并返回
+``"execute[<index>]: <action>" -> result | repr(error)`` 的映射表。
+
+.. code-block:: python
+
+   from automation_file import execute_action, read_action_json
+
+   results = execute_action([
+       ["FA_create_dir", {"dir_path": "build"}],
+       ["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}],
+       ["FA_zip_dir", {"dir_we_want_to_zip": "build", "zip_name": "build_snapshot"}],
+   ])
+
+   # 或从文件读入：
+   results = execute_action(read_action_json("actions.json"))
+
+校验、dry-run、并行执行
+-----------------------
+
+.. code-block:: python
+
+   from automation_file import (
+       execute_action, execute_action_parallel, validate_action,
+   )
+
+   # Fail-fast 校验：若有未知名称，执行前即中止整批。
+   execute_action(actions, validate_first=True)
+
+   # Dry-run：记录将调用什么但不实际调用。
+   execute_action(actions, dry_run=True)
+
+   # 并行：通过线程池执行彼此独立的动作。
+   execute_action_parallel(actions, max_workers=4)
+
+   # 手动校验——返回已解析的名称列表。
+   names = validate_action(actions)
+
+注册自定义动作
+--------------
+
+.. code-block:: python
+
+   from automation_file import add_command_to_executor, execute_action
+
+   def greet(name: str) -> str:
+       return f"hello {name}"
+
+   add_command_to_executor({"greet": greet})
+   execute_action([["greet", {"name": "world"}]])
+
+入口点打包与动态包注册详见 :doc:`plugins`。
diff --git a/docs/source.zh-CN/usage/reliability.rst b/docs/source.zh-CN/usage/reliability.rst
new file mode 100644
index 0000000..a143356
--- /dev/null
+++ b/docs/source.zh-CN/usage/reliability.rst
@@ -0,0 +1,33 @@
+可靠性
+======
+
+为自家的可调用对象套上重试：
+
+.. code-block:: python
+
+   from automation_file import retry_on_transient
+
+   @retry_on_transient(max_attempts=5, backoff_base=0.5)
+   def flaky_network_call(): ...
+
+该装饰器只重试 ``retriable=(…)`` 中明确列出的异常类型
+（默认是 ``ConnectionError`` / ``TimeoutError`` / ``OSError``）。
+切勿放宽到裸 ``Exception``——那会把逻辑 bug 当成瞬时失败掩盖掉。
+重试耗尽后会抛出 :class:`~automation_file.RetryExhaustedException`，
+并通过 ``raise ... from err`` 链回最后一次原因。
+
+为单个动作设置上限：
+
+.. code-block:: python
+
+   from automation_file import Quota
+
+   quota = Quota(max_bytes=50 * 1024 * 1024, max_seconds=30.0)
+   with quota.time_budget("bulk-upload"):
+       bulk_upload_work()
+
+   # 也可以直接装饰可调用对象：
+   @quota.wraps
+   def expensive(payload: bytes) -> None: ...
+
+每个上限设置为 ``0`` 即表示禁用该项检查。
diff --git a/docs/source.zh-CN/usage/servers.rst b/docs/source.zh-CN/usage/servers.rst
new file mode 100644
index 0000000..85006c5
--- /dev/null
+++ b/docs/source.zh-CN/usage/servers.rst
@@ -0,0 +1,46 @@
+动作服务器
+==========
+
+TCP 动作服务器
+--------------
+
+.. code-block:: python
+
+   from automation_file import start_autocontrol_socket_server
+
+   server = start_autocontrol_socket_server(
+       host="localhost", port=9943, shared_secret="optional-secret",
+   )
+   # 稍后：
+   server.shutdown()
+   server.server_close()
+
+设置 ``shared_secret`` 后，客户端必须在 JSON 动作列表之前加上
+``AUTH <secret>\n`` 前缀。服务器默认仍绑定 loopback，除非显式传入
+``allow_non_loopback=True``，否则拒绝非 loopback 绑定。
+
+每个连接只接受一份 JSON 负载（``recv(8192)``）。
+若要提高该上限，必须同时改为带长度前缀的协议。
+
+HTTP 动作服务器
+---------------
+
+.. code-block:: python
+
+   from automation_file import start_http_action_server
+
+   server = start_http_action_server(
+       host="127.0.0.1", port=9944, shared_secret="optional-secret",
+   )
+
+   # 客户端：
+   # curl -H 'Authorization: Bearer optional-secret' \
+   #      -d '[["FA_create_dir",{"dir_path":"x"}]]' \
+   #      http://127.0.0.1:9944/actions
+
+HTTP 响应均为 JSON。鉴权失败返回 ``401``；非法 JSON 返回 ``400``；
+未知路径返回 ``404``。请求体上限 1 MB。默认仅绑定 loopback；
+若要绑定其他地址须传 ``allow_non_loopback=True``。
+
+共享密钥比较使用 :func:`hmac.compare_digest`（常数时间）。
+切勿记录密钥或原始负载。
diff --git a/docs/source.zh-CN/usage/transfer.rst b/docs/source.zh-CN/usage/transfer.rst
new file mode 100644
index 0000000..b1c7f74
--- /dev/null
+++ b/docs/source.zh-CN/usage/transfer.rst
@@ -0,0 +1,51 @@
+HTTP 传输
+=========
+
+可续传 HTTP 下载
+----------------
+
+:func:`~automation_file.download_file` 接受 ``resume=True``。字节会写入
+``<target>.part``；若该临时文件已存在，下一次调用会发送
+``Range: bytes=<n>-``，让传输从已有字节数继续。配合 ``expected_sha256=``
+可在最后一块写入后立即完成校验：
+
+.. code-block:: python
+
+   from automation_file import download_file
+
+   download_file(
+       "https://example.com/big.bin",
+       "big.bin",
+       resume=True,
+       expected_sha256="3b0c44298fc1...",
+   )
+
+每个 URL 都会经过
+:func:`~automation_file.remote.url_validator.validate_http_url`，
+拦截 ``file://`` / ``ftp://`` / ``data:`` 等 scheme 以及
+私有 / loopback / link-local / 保留 / 多播 / 未指定地址的 IP。
+默认 20 MB 响应上限、15 秒连接超时。TLS 验证从不关闭。
+
+传输进度与取消
+--------------
+
+把 ``progress_name="<label>"`` 传给 :func:`download_file`、
+:func:`s3_upload_file` 或 :func:`s3_download_file`，将该次传输登记到
+共享的进度注册表。GUI 的 **Progress** 标签页每 0.5 秒轮询一次该注册表；
+``FA_progress_list``、``FA_progress_cancel``、``FA_progress_clear``
+让 JSON 动作列表也能查看同样的视图。
+
+.. code-block:: python
+
+   from automation_file import download_file, progress_cancel
+
+   # 一个线程里：
+   download_file("https://example.com/big.bin", "big.bin",
+                 progress_name="big-download")
+
+   # 另一个线程 / GUI：
+   progress_cancel("big-download")
+
+取消会在传输循环里抛出 :class:`~automation_file.CancelledException`。
+传输函数自身捕获后将状态标为 ``status="cancelled"``，并返回 ``False``——
+调用方无需自行处理该异常。
diff --git a/docs/source.zh-TW/index.rst b/docs/source.zh-TW/index.rst
index ca6c70b..6bc4858 100644
--- a/docs/source.zh-TW/index.rst
+++ b/docs/source.zh-TW/index.rst
@@ -159,10 +159,10 @@ JSON 動作清單就是上述 list 的 list。
 
 .. toctree::
    :maxdepth: 2
-   :caption: 目錄
+   :caption: 文件
 
    architecture
-   usage
+   usage/index
    api/index
 
 索引
diff --git a/docs/source.zh-TW/usage.rst b/docs/source.zh-TW/usage.rst
deleted file mode 100644
index 9f7215f..0000000
--- a/docs/source.zh-TW/usage.rst
+++ /dev/null
@@ -1,557 +0,0 @@
-使用指南
-========
-
-JSON 動作清單
--------------
-
-動作可採三種形狀之一：
-
-.. code-block:: json
-
-   ["FA_name"]
-   ["FA_name", {"kwarg": "value"}]
-   ["FA_name", ["positional", "args"]]
-
-動作清單是動作的陣列。執行器依序執行並回傳
-``"execute[<index>]: <action>" -> result | repr(error)`` 的對應表。
-
-.. code-block:: python
-
-   from automation_file import execute_action, read_action_json
-
-   results = execute_action([
-       ["FA_create_dir", {"dir_path": "build"}],
-       ["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}],
-       ["FA_zip_dir", {"dir_we_want_to_zip": "build", "zip_name": "build_snapshot"}],
-   ])
-
-   # 或從檔案讀入：
-   results = execute_action(read_action_json("actions.json"))
-
-驗證、dry-run、平行執行
------------------------
-
-.. code-block:: python
-
-   from automation_file import (
-       execute_action, execute_action_parallel, validate_action,
-   )
-
-   # Fail-fast 驗證：若有未知名稱，執行前即中止整批。
-   execute_action(actions, validate_first=True)
-
-   # Dry-run：記錄將呼叫什麼但不實際呼叫。
-   execute_action(actions, dry_run=True)
-
-   # 平行：透過執行緒池執行彼此獨立的動作。
-   execute_action_parallel(actions, max_workers=4)
-
-   # 手動驗證——回傳已解析的名稱列表。
-   names = validate_action(actions)
-
-CLI
----
-
-執行 JSON 動作清單的舊式參數::
-
-   python -m automation_file --execute_file actions.json
-   python -m automation_file --execute_dir ./actions/
-   python -m automation_file --execute_str '[["FA_create_dir",{"dir_path":"x"}]]'
-   python -m automation_file --create_project ./my_project
-
-一次性操作的子命令::
-
-   python -m automation_file ui
-   python -m automation_file zip ./src out.zip --dir
-   python -m automation_file unzip out.zip ./restored
-   python -m automation_file download https://example.com/file.bin file.bin
-   python -m automation_file create-file hello.txt --content "hi"
-   python -m automation_file server --host 127.0.0.1 --port 9943
-   python -m automation_file http-server --host 127.0.0.1 --port 9944
-   python -m automation_file drive-upload my.txt --token token.json --credentials creds.json
-
-Google Drive
-------------
-
-.. code-block:: python
-
-   from automation_file import driver_instance, drive_upload_to_drive
-
-   driver_instance.later_init("token.json", "credentials.json")
-   drive_upload_to_drive("example.txt")
-
-TCP 動作伺服器
---------------
-
-.. code-block:: python
-
-   from automation_file import start_autocontrol_socket_server
-
-   server = start_autocontrol_socket_server(
-       host="localhost", port=9943, shared_secret="optional-secret",
-   )
-   # 稍後：
-   server.shutdown()
-   server.server_close()
-
-設定 ``shared_secret`` 後，client 必須在 JSON 動作清單之前加上
-``AUTH <secret>\\n`` 前綴。伺服器預設仍綁定 loopback，除非顯式傳入
-``allow_non_loopback=True``，否則拒絕非 loopback 綁定。
-
-HTTP 動作伺服器
----------------
-
-.. code-block:: python
-
-   from automation_file import start_http_action_server
-
-   server = start_http_action_server(
-       host="127.0.0.1", port=9944, shared_secret="optional-secret",
-   )
-
-   # 客戶端：
-   # curl -H 'Authorization: Bearer optional-secret' \
-   #      -d '[["FA_create_dir",{"dir_path":"x"}]]' \
-   #      http://127.0.0.1:9944/actions
-
-HTTP 回應為 JSON。設定 ``shared_secret`` 後，客戶端必須送出
-``Authorization: Bearer <secret>``。
-
-可靠性
-------
-
-對自訂的可呼叫物件套用重試：
-
-.. code-block:: python
-
-   from automation_file import retry_on_transient
-
-   @retry_on_transient(max_attempts=5, backoff_base=0.5)
-   def flaky_network_call(): ...
-
-對單一動作套用配額限制：
-
-.. code-block:: python
-
-   from automation_file import Quota
-
-   quota = Quota(max_bytes=50 * 1024 * 1024, max_seconds=30.0)
-   with quota.time_budget("bulk-upload"):
-       bulk_upload_work()
-
-路徑安全
---------
-
-.. code-block:: python
-
-   from automation_file import safe_join
-
-   target = safe_join("/data/jobs", user_supplied_path)
-   # -> 若解析後的路徑逃出 /data/jobs，會拋出 PathTraversalException。
-
-雲端 / SFTP 後端
-----------------
-
-每個後端（S3、Azure Blob、Dropbox、SFTP）皆隨 ``automation_file`` 一併打包，
-並由 :func:`~automation_file.core.action_registry.build_default_registry`
-自動登錄。不需要額外安裝步驟——對單例呼叫 ``later_init`` 即可：
-
-.. code-block:: python
-
-   from automation_file import execute_action, s3_instance
-
-   s3_instance.later_init(region_name="us-east-1")
-
-   execute_action([
-       ["FA_s3_upload_file", {"local_path": "report.csv", "bucket": "reports", "key": "report.csv"}],
-   ])
-
-所有後端都提供相同的五項操作：
-``upload_file``、``upload_dir``、``download_file``、``delete_*``、``list_*``。
-``register_<backend>_ops(registry)`` 依然公開，供自行建立登錄表的呼叫者使用。
-
-SFTP 特別使用 :class:`paramiko.RejectPolicy`——未知主機會被拒絕而非自動加入。
-請顯式提供 ``known_hosts``，或仰賴 ``~/.ssh/known_hosts``。
-
-檔案監看觸發器
---------------
-
-當受監看路徑發生檔案系統事件時執行動作清單。模組層的
-:data:`~automation_file.trigger.trigger_manager` 以名稱為鍵維護一組活動
-watcher，讓 JSON 介面與 GUI 共享同一個生命週期。
-
-.. code-block:: python
-
-   from automation_file import watch_start, watch_stop
-
-   watch_start(
-       name="inbox-sweeper",
-       path="/data/inbox",
-       action_list=[["FA_copy_all_file_to_dir", {"source_dir": "/data/inbox",
-                                                 "target_dir": "/data/processed"}]],
-       events=["created", "modified"],
-       recursive=False,
-   )
-   # 稍後：
-   watch_stop("inbox-sweeper")
-
-也可以透過 JSON 動作清單以 ``FA_watch_start`` / ``FA_watch_stop`` /
-``FA_watch_stop_all`` / ``FA_watch_list`` 操作。
-
-Cron 排程器
------------
-
-按週期性排程執行動作清單。5 欄位 cron 解析器支援 ``*``、精確值、``a-b``
-範圍、逗號分隔清單與 ``*/n`` 步進語法，並能使用 ``jan``..``dec`` /
-``sun``..``sat`` 別名。
-
-.. code-block:: python
-
-   from automation_file import schedule_add
-
-   schedule_add(
-       name="nightly-snapshot",
-       cron_expression="0 2 * * *",           # 每日本地時間 02:00
-       action_list=[["FA_zip_dir", {"dir_we_want_to_zip": "/data",
-                                    "zip_name": "/backup/data_nightly"}]],
-   )
-
-背景執行緒在分鐘邊界甦醒，因此不支援秒級精度的表達式。可透過 JSON 使用
-``FA_schedule_add`` / ``FA_schedule_remove`` / ``FA_schedule_remove_all`` /
-``FA_schedule_list``。
-
-傳輸進度與取消
---------------
-
-對 :func:`download_file`、:func:`s3_upload_file` 或 :func:`s3_download_file`
-傳入 ``progress_name="<label>"`` 即可把傳輸登錄到共享進度登錄表。GUI
-的 **Progress** 分頁每半秒輪詢登錄表；``FA_progress_list``、
-``FA_progress_cancel`` 與 ``FA_progress_clear`` 讓 JSON 動作清單取得同樣的視圖。
-
-.. code-block:: python
-
-   from automation_file import download_file, progress_cancel
-
-   # 一個執行緒：
-   download_file("https://example.com/big.bin", "big.bin",
-                 progress_name="big-download")
-
-   # 另一執行緒 / GUI：
-   progress_cancel("big-download")
-
-取消會在傳輸迴圈中拋出 :class:`~automation_file.CancelledException`。
-傳輸函式會捕捉這個例外、將 reporter 標記為 ``status="cancelled"`` 並
-回傳 ``False``——呼叫者不需自行處理例外。
-
-快速檔案搜尋
-------------
-
-:func:`fast_find` 會挑選主機上最便宜的後端——優先使用 OS 索引，否則
-串流 scandir 走訪——以最小能耗掃描大型目錄樹：
-
-* macOS： ``mdfind`` （Spotlight）
-* Linux： ``plocate`` / ``locate`` 資料庫
-* Windows：若已安裝 Everything 的 ``es.exe`` CLI
-* 後備： ``os.scandir`` 產生器 + ``fnmatch`` 比對，並以 ``limit=`` 提早終止
-
-.. code-block:: python
-
-   from automation_file import fast_find, scandir_find, has_os_index
-
-   # 有索引時查詢索引，否則落到 scandir。
-   results = fast_find("/var/log", "*.log", limit=100)
-
-   # 強制走可攜路徑（略過 OS 索引）。
-   results = fast_find("/data", "report_*.csv", use_index=False)
-
-   # 串流產生器——不需掃整棵樹即可提前終止。
-   for path in scandir_find("/data", "*.csv"):
-       if "2026" in path:
-           break
-
-   # fast_find 會嘗試哪個索引？回傳 "mdfind" / "locate" /
-   # "plocate" / "es" / None。
-   has_os_index()
-
-JSON 動作清單也可使用 ``FA_fast_find``：
-
-.. code-block:: json
-
-   [["FA_fast_find", {"root": "/var/log", "pattern": "*.log", "limit": 50}]]
-
-檢查碼與完整性驗證
-------------------
-
-以串流讀取器（支援 :mod:`hashlib` 的任何演算法）雜湊任何檔案，並以
-常數時間比較驗證預期摘要：
-
-.. code-block:: python
-
-   from automation_file import file_checksum, verify_checksum
-
-   digest = file_checksum("bundle.tar.gz")                 # 預設 sha256
-   verify_checksum("bundle.tar.gz", digest)                # -> True
-   verify_checksum("bundle.tar.gz", "deadbeef...", algorithm="blake2b")
-
-相同函式在 JSON 動作清單中是 ``FA_file_checksum`` 與
-``FA_verify_checksum``。
-
-可續傳 HTTP 下載
-----------------
-
-:func:`~automation_file.download_file` 接受 ``resume=True``。內容會寫入
-``<target>.part``；若暫存檔已存在，下次呼叫會送出 ``Range: bytes=<n>-``
-讓傳輸從先前停止處接續。結合 ``expected_sha256=`` 可在最後一塊寫入後
-立即驗證下載：
-
-.. code-block:: python
-
-   from automation_file import download_file
-
-   download_file(
-       "https://example.com/big.bin",
-       "big.bin",
-       resume=True,
-       expected_sha256="3b0c44298fc1...",
-   )
-
-檔案去重
---------
-
-:func:`~automation_file.find_duplicates` 以 ``os.scandir`` 走訪目錄樹一次，
-並執行三階段 size → partial-hash → full-hash 管線。擁有唯一大小的檔案
-完全不會被雜湊，因此數百萬檔案的樹掃描仍然便宜：
-
-.. code-block:: python
-
-   from automation_file import find_duplicates
-
-   groups = find_duplicates("/data", min_size=1024)
-   # groups: list[list[str]]，每個內層清單為一組完全相同的檔案，
-   # 依大小遞減排序。
-
-``FA_find_duplicates`` 公開同一個呼叫給 JSON 動作清單使用。
-
-目錄增量同步
-------------
-
-:func:`~automation_file.sync_dir` 把 ``src`` 鏡像到 ``dst``，只複製新的
-或已變更的檔案。變更偵測預設為 ``(size, mtime)``；當 mtime 不可靠時
-請傳入 ``compare="checksum"``。``dst`` 下的額外檔案預設不會動到，
-需傳入 ``delete=True`` 才會刪除（並可用 ``dry_run=True`` 預覽）：
-
-.. code-block:: python
-
-   from automation_file import sync_dir
-
-   summary = sync_dir("/data/src", "/data/dst", delete=True)
-   # summary: {"copied": [...], "skipped": [...], "deleted": [...],
-   #           "errors": [...], "dry_run": False}
-
-JSON 動作形式為 ``FA_sync_dir``。符號連結會以符號連結重建而非跟隨，
-因此指向目錄樹外的連結不會打翻鏡像。
-
-目錄清單快照
-------------
-
-把目錄樹下所有檔案的 JSON 清單寫下來，稍後驗證目錄樹未被變動。
-適用於發行產物驗證、備份完整性檢查、搬移前的飛行前檢查：
-
-.. code-block:: python
-
-   from automation_file import write_manifest, verify_manifest
-
-   write_manifest("/release/payload", "/release/MANIFEST.json")
-
-   # 稍後……
-   result = verify_manifest("/release/payload", "/release/MANIFEST.json")
-   if not result["ok"]:
-       raise SystemExit(f"manifest mismatch: {result}")
-
-``result`` 分別報告 ``matched``、``missing``、``modified``、``extra`` 清單。
-額外檔案不算驗證失敗（與 ``sync_dir`` 的「預設不刪除」行為一致）；
-``missing`` 或 ``modified`` 則會。這兩個操作以 ``FA_write_manifest``
-與 ``FA_verify_manifest`` 暴露給 JSON 動作清單。
-
-通知
-----
-
-透過 webhook、Slack 或 SMTP 推送一次性訊息，或在觸發器 / 排程器失敗時
-自動通知：
-
-.. code-block:: python
-
-   from automation_file import (
-       SlackSink, WebhookSink, EmailSink,
-       notification_manager, notify_send,
-   )
-
-   notification_manager.register(SlackSink("https://hooks.slack.com/services/T/B/X"))
-   notify_send("deploy complete", body="rev abc123", level="info")
-
-每個 sink 都實作同樣的 ``send(subject, body, level)`` 介面，扇出
-:class:`~automation_file.NotificationManager` 負責：
-
-- 每個 sink 的錯誤隔離——一個故障 sink 不會使其他 sink 死掉。
-- 滑動視窗去重——在 ``dedup_seconds`` 內，完全相同的
-  ``(subject, body, level)`` 訊息會被丟棄，避免卡住的觸發器灌爆通道。
-- 對每個 webhook / Slack URL 做 SSRF 驗證。
-
-排程器與觸發器調度器會在失敗時以 ``level="error"`` 自動通知——只要
-登錄 sink 即可取得生產告警。JSON 動作形式為 ``FA_notify_send`` 與
-``FA_notify_list``。
-
-組態檔與密鑰提供者
-------------------
-
-把通知 sink 與預設值一次寫在 TOML 檔裡。密鑰引用在載入時會從環境變數
-或檔案根目錄解析（Docker / K8s 風格）：
-
-.. code-block:: toml
-
-   # automation_file.toml
-
-   [secrets]
-   file_root = "/run/secrets"
-
-   [defaults]
-   dedup_seconds = 120
-
-   [[notify.sinks]]
-   type = "slack"
-   name = "team-alerts"
-   webhook_url = "${env:SLACK_WEBHOOK}"
-
-   [[notify.sinks]]
-   type = "email"
-   name = "ops-email"
-   host = "smtp.example.com"
-   port = 587
-   sender = "alerts@example.com"
-   recipients = ["ops@example.com"]
-   username = "${env:SMTP_USER}"
-   password = "${file:smtp_password}"
-
-.. code-block:: python
-
-   from automation_file import AutomationConfig, notification_manager
-
-   config = AutomationConfig.load("automation_file.toml")
-   config.apply_to(notification_manager)
-
-未解析的 ``${…}`` 引用會拋出
-:class:`~automation_file.SecretNotFoundException` 而非默默變成空字串。
-自訂的 provider 鏈可透過 :class:`~automation_file.ChainedSecretProvider` /
-:class:`~automation_file.EnvSecretProvider` /
-:class:`~automation_file.FileSecretProvider` 組裝，並傳給
-``AutomationConfig.load(path, provider=…)``。
-
-DAG 動作執行器
---------------
-
-:func:`~automation_file.execute_action_dag` 依依賴關係執行動作。每個節點
-形如 ``{"id": str, "action": [name, ...], "depends_on": [id, ...]}``。
-彼此獨立的分支在執行緒池中扇出；當節點失敗時，其後續依賴會被標記為
-``skipped``（``fail_fast=True``，預設）或仍會執行（``fail_fast=False``）：
-
-.. code-block:: python
-
-   from automation_file import execute_action_dag
-
-   results = execute_action_dag([
-       {"id": "fetch",  "action": ["FA_download_file",
-                                   ["https://example.com/src.tar.gz", "src.tar.gz"]]},
-       {"id": "verify", "action": ["FA_verify_checksum",
-                                   ["src.tar.gz", "3b0c44298fc1..."]],
-                        "depends_on": ["fetch"]},
-       {"id": "unpack", "action": ["FA_unzip_file", ["src.tar.gz", "src"]],
-                        "depends_on": ["verify"]},
-       {"id": "report", "action": ["FA_fast_find", ["src", "*.py"]],
-                        "depends_on": ["unpack"]},
-   ])
-
-循環、未知依賴、自我依賴與重複 id 會在任何節點執行前拋出
-:class:`~automation_file.exceptions.DagException`。JSON 動作形式為
-``FA_execute_action_dag``。
-
-Entry-point 外掛
-----------------
-
-第三方套件可在自己的 ``pyproject.toml`` 中宣告 ``automation_file.actions``
-entry point，以登錄自己的 ``FA_*`` 命令::
-
-   [project.entry-points."automation_file.actions"]
-   my_plugin = "my_plugin:register"
-
-其中 ``register`` 是零參數的可呼叫物件，回傳
-``Mapping[str, Callable]``。外掛安裝到同一虛擬環境後，
-:func:`~automation_file.core.action_registry.build_default_registry`
-會自動採用——呼叫端不需任何修改：
-
-.. code-block:: python
-
-   # my_plugin/__init__.py
-   def greet(name: str) -> str:
-       return f"hello {name}"
-
-   def register() -> dict:
-       return {"FA_greet": greet}
-
-.. code-block:: python
-
-   # 消費端（執行 `pip install my_plugin` 之後）
-   from automation_file import execute_action
-   execute_action([["FA_greet", {"name": "world"}]])
-
-外掛失敗（匯入錯誤、factory 例外、回傳形狀錯誤、登錄表拒絕）會被記錄
-並吞下，一個壞外掛不會破壞整個函式庫。
-
-GUI（PySide6）
---------------
-
-分頁式控制介面把每項功能都包起來：
-
-.. code-block:: bash
-
-   python -m automation_file ui
-   # 或在 repo 根目錄以開發模式執行：
-   python main_ui.py
-
-.. code-block:: python
-
-   from automation_file import launch_ui
-
-   launch_ui()
-
-分頁：Home、Local、Transfer、Progress、JSON actions、Triggers、Scheduler、
-Servers。分頁下方的常駐 log panel 會即時串流每次呼叫的結果或錯誤。
-背景工作透過 ``ActionWorker`` 在 ``QThreadPool`` 上執行，保持 UI 反應靈敏。
-
-加入自訂命令
-------------
-
-.. code-block:: python
-
-   from automation_file import add_command_to_executor, execute_action
-
-   def greet(name: str) -> str:
-       return f"hello {name}"
-
-   add_command_to_executor({"greet": greet})
-   execute_action([["greet", {"name": "world"}]])
-
-動態套件登錄
-------------
-
-.. code-block:: python
-
-   from automation_file import package_manager, execute_action
-
-   package_manager.add_package_to_executor("math")
-   execute_action([["math_sqrt", [16.0]]])   # -> 4.0
-
-.. warning::
-
-   ``package_manager.add_package_to_executor`` 實際上會登錄套件中所有頂層
-   函式 / 類別 / 內建物件。切勿把它暴露給不受信任的輸入（例如透過 TCP 或
-   HTTP 伺服器）。
diff --git a/docs/source.zh-TW/usage/cli.rst b/docs/source.zh-TW/usage/cli.rst
new file mode 100644
index 0000000..fec45d0
--- /dev/null
+++ b/docs/source.zh-TW/usage/cli.rst
@@ -0,0 +1,25 @@
+CLI
+===
+
+執行 JSON 動作清單的舊式參數::
+
+   python -m automation_file --execute_file actions.json
+   python -m automation_file --execute_dir ./actions/
+   python -m automation_file --execute_str '[["FA_create_dir",{"dir_path":"x"}]]'
+   python -m automation_file --create_project ./my_project
+
+一次性操作的子指令::
+
+   python -m automation_file ui
+   python -m automation_file zip ./src out.zip --dir
+   python -m automation_file unzip out.zip ./restored
+   python -m automation_file download https://example.com/file.bin file.bin
+   python -m automation_file create-file hello.txt --content "hi"
+   python -m automation_file server --host 127.0.0.1 --port 9943
+   python -m automation_file http-server --host 127.0.0.1 --port 9944
+   python -m automation_file mcp --allowed-actions FA_list_dir,FA_file_checksum
+   python -m automation_file drive-upload my.txt --token token.json --credentials creds.json
+
+``mcp`` 子指令以 stdio 啟動 Model Context Protocol 伺服器，
+讓 Claude Desktop 之類的宿主可把 ``FA_*`` 動作當成 MCP 工具呼叫——
+完整整合說明請見 :doc:`mcp`。
diff --git a/docs/source.zh-TW/usage/cloud.rst b/docs/source.zh-TW/usage/cloud.rst
new file mode 100644
index 0000000..c47be33
--- /dev/null
+++ b/docs/source.zh-TW/usage/cloud.rst
@@ -0,0 +1,60 @@
+雲端與 SFTP 後端
+================
+
+每個後端（Google Drive、S3、Azure Blob、Dropbox、SFTP）皆內建於
+``automation_file``，並由
+:func:`~automation_file.core.action_registry.build_default_registry` 自動註冊。
+無須額外安裝步驟——在單例上呼叫 ``later_init`` 即可使用：
+
+.. code-block:: python
+
+   from automation_file import execute_action, s3_instance
+
+   s3_instance.later_init(region_name="us-east-1")
+
+   execute_action([
+       ["FA_s3_upload_file", {"local_path": "report.csv",
+                              "bucket": "reports", "key": "report.csv"}],
+   ])
+
+所有後端都暴露相同的五種操作：``upload_file``、``upload_dir``、
+``download_file``、``delete_*``、``list_*``。如需建立自訂註冊表，
+``register_<backend>_ops(registry)`` 仍是公開 API。
+
+Google Drive
+------------
+
+.. code-block:: python
+
+   from automation_file import driver_instance, drive_upload_to_drive
+
+   driver_instance.later_init("token.json", "credentials.json")
+   drive_upload_to_drive("example.txt")
+
+OAuth 憑證以 UTF-8 寫入呼叫方提供的 ``token_path``。
+切勿輸出或記錄該檔案內容。
+
+SFTP
+----
+
+:class:`~automation_file.SFTPClient` 採用 :class:`paramiko.RejectPolicy`——
+未知主機會被拒絕，而非自動加入。請顯式提供 ``known_hosts=`` 或依賴
+``~/.ssh/known_hosts``。不要為了方便而換成 ``AutoAddPolicy``。
+
+跨後端複製
+----------
+
+跨後端調度器接受 URI 語法：
+
+.. code-block:: python
+
+   from automation_file import execute_action
+
+   execute_action([
+       ["FA_cross_copy",
+        {"src": "s3://reports/2026-04.csv",
+         "dst": "drive:///Backups/april.csv"}],
+   ])
+
+URI 前綴：``local://``、``s3://``、``drive://``、``sftp://``、
+``azure://``、``dropbox://``、``ftp://``。
diff --git a/docs/source.zh-TW/usage/config.rst b/docs/source.zh-TW/usage/config.rst
new file mode 100644
index 0000000..16e973e
--- /dev/null
+++ b/docs/source.zh-TW/usage/config.rst
@@ -0,0 +1,45 @@
+設定檔與機敏資訊 provider
+=========================
+
+把通知 sink 與預設值集中宣告在一份 TOML 檔。
+機敏資訊參考在載入時從環境變數或檔案根目錄（Docker / K8s 風格）解析：
+
+.. code-block:: toml
+
+   # automation_file.toml
+
+   [secrets]
+   file_root = "/run/secrets"
+
+   [defaults]
+   dedup_seconds = 120
+
+   [[notify.sinks]]
+   type = "slack"
+   name = "team-alerts"
+   webhook_url = "${env:SLACK_WEBHOOK}"
+
+   [[notify.sinks]]
+   type = "email"
+   name = "ops-email"
+   host = "smtp.example.com"
+   port = 587
+   sender = "alerts@example.com"
+   recipients = ["ops@example.com"]
+   username = "${env:SMTP_USER}"
+   password = "${file:smtp_password}"
+
+.. code-block:: python
+
+   from automation_file import AutomationConfig, notification_manager
+
+   config = AutomationConfig.load("automation_file.toml")
+   config.apply_to(notification_manager)
+
+未解析的 ``${…}`` 參考會擲出
+:class:`~automation_file.SecretNotFoundException`，
+而不是悄悄變成空字串。需要自訂 provider 鏈時，可使用
+:class:`~automation_file.ChainedSecretProvider` /
+:class:`~automation_file.EnvSecretProvider` /
+:class:`~automation_file.FileSecretProvider`，
+並透過 ``AutomationConfig.load(path, provider=…)`` 傳入。
diff --git a/docs/source.zh-TW/usage/dag.rst b/docs/source.zh-TW/usage/dag.rst
new file mode 100644
index 0000000..4be71bd
--- /dev/null
+++ b/docs/source.zh-TW/usage/dag.rst
@@ -0,0 +1,28 @@
+DAG 動作執行器
+==============
+
+:func:`~automation_file.execute_action_dag` 依相依順序執行動作。
+每個節點形如 ``{"id": str, "action": [name, ...], "depends_on":
+[id, ...]}``。互不相依的分支會透過執行緒池平行展開；
+當節點失敗時，其遞移相依的下游會被標記為 ``skipped``
+（預設 ``fail_fast=True``）或仍然執行（``fail_fast=False``）：
+
+.. code-block:: python
+
+   from automation_file import execute_action_dag
+
+   results = execute_action_dag([
+       {"id": "fetch",  "action": ["FA_download_file",
+                                   ["https://example.com/src.tar.gz", "src.tar.gz"]]},
+       {"id": "verify", "action": ["FA_verify_checksum",
+                                   ["src.tar.gz", "3b0c44298fc1..."]],
+                        "depends_on": ["fetch"]},
+       {"id": "unpack", "action": ["FA_unzip_file", ["src.tar.gz", "src"]],
+                        "depends_on": ["verify"]},
+       {"id": "report", "action": ["FA_fast_find", ["src", "*.py"]],
+                        "depends_on": ["unpack"]},
+   ])
+
+迴圈、未知相依、自相依與重複 id 都會在任何節點執行前擲出
+:class:`~automation_file.exceptions.DagException`。
+JSON 形式：``FA_execute_action_dag``。
diff --git a/docs/source.zh-TW/usage/events.rst b/docs/source.zh-TW/usage/events.rst
new file mode 100644
index 0000000..07295c2
--- /dev/null
+++ b/docs/source.zh-TW/usage/events.rst
@@ -0,0 +1,58 @@
+觸發器與排程器
+==============
+
+檔案監看觸發器
+--------------
+
+當被監看的路徑上有檔案系統事件時，自動執行一份動作清單。
+模組層級的 :data:`~automation_file.trigger.trigger_manager` 維護一份
+依名稱索引的活躍監看器表，讓 JSON 外觀與 GUI 共用同一個生命週期。
+
+.. code-block:: python
+
+   from automation_file import watch_start, watch_stop
+
+   watch_start(
+       name="inbox-sweeper",
+       path="/data/inbox",
+       action_list=[["FA_copy_all_file_to_dir",
+                     {"source_dir": "/data/inbox",
+                      "target_dir": "/data/processed"}]],
+       events=["created", "modified"],
+       recursive=False,
+   )
+   # 稍後：
+   watch_stop("inbox-sweeper")
+
+也可以在 JSON 動作清單中呼叫 ``FA_watch_start`` /
+``FA_watch_stop`` / ``FA_watch_stop_all`` / ``FA_watch_list``。
+
+Cron 排程器
+-----------
+
+依重複時刻執行動作清單。5 欄位 cron 解析器支援
+``*``、精確值、``a-b`` 區間、逗號分隔清單與 ``*/n`` 步長，
+也支援 ``jan``..``dec`` / ``sun``..``sat`` 別名。
+
+.. code-block:: python
+
+   from automation_file import schedule_add
+
+   schedule_add(
+       name="nightly-snapshot",
+       cron_expression="0 2 * * *",           # 每天本地時間 02:00
+       action_list=[["FA_zip_dir", {"dir_we_want_to_zip": "/data",
+                                    "zip_name": "/backup/data_nightly"}]],
+   )
+
+背景執行緒在每分鐘邊界喚醒，因此不支援小於一分鐘的精度。
+JSON 形式：``FA_schedule_add`` / ``FA_schedule_remove`` /
+``FA_schedule_remove_all`` / ``FA_schedule_list``。
+
+當動作清單擲出
+:class:`~automation_file.exceptions.FileAutomationException` 時，
+兩個排程器都會呼叫
+:func:`~automation_file.notify.manager.notify_on_failure`。
+若未註冊任何 sink，該輔助函式即為 no-op，因此自動通知是
+註冊 :class:`~automation_file.NotificationSink` 的可選副作用——
+詳見 :doc:`notifications`。
diff --git a/docs/source.zh-TW/usage/gui.rst b/docs/source.zh-TW/usage/gui.rst
new file mode 100644
index 0000000..6aa7717
--- /dev/null
+++ b/docs/source.zh-TW/usage/gui.rst
@@ -0,0 +1,24 @@
+GUI（PySide6）
+==============
+
+分頁式控制面板封裝了所有功能：
+
+.. code-block:: bash
+
+   python -m automation_file ui
+   # 或在儲存庫根目錄開發時：
+   python main_ui.py
+
+.. code-block:: python
+
+   from automation_file import launch_ui
+
+   launch_ui()
+
+分頁：Home、Local、Transfer、Progress、JSON actions、Triggers、
+Scheduler、Servers。所有分頁下方共用一個常駐日誌面板，
+逐條輸出每次呼叫的結果或錯誤。背景工作透過 ``ActionWorker`` 在
+``QThreadPool`` 上執行，UI 始終保持回應。
+
+GUI 與函式庫其餘部分共用同一組單例——從 Python 註冊的 sink、
+自訂動作、觸發器都會立即在執行中的視窗生效。
diff --git a/docs/source.zh-TW/usage/index.rst b/docs/source.zh-TW/usage/index.rst
new file mode 100644
index 0000000..ba2d862
--- /dev/null
+++ b/docs/source.zh-TW/usage/index.rst
@@ -0,0 +1,43 @@
+使用指南
+========
+
+使用指南依主題分章。每一節皆為自包含——挑你需要的後端或功能直接進入即可。
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 入門
+
+   quickstart
+   cli
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 本地與傳輸
+
+   local
+   transfer
+   cloud
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 伺服器與整合
+
+   servers
+   mcp
+   gui
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 可靠性與事件
+
+   reliability
+   events
+   notifications
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 設定與擴充
+
+   config
+   dag
+   plugins
diff --git a/docs/source.zh-TW/usage/local.rst b/docs/source.zh-TW/usage/local.rst
new file mode 100644
index 0000000..6009d48
--- /dev/null
+++ b/docs/source.zh-TW/usage/local.rst
@@ -0,0 +1,122 @@
+本地檔案操作
+============
+
+路徑安全
+--------
+
+.. code-block:: python
+
+   from automation_file import safe_join
+
+   target = safe_join("/data/jobs", user_supplied_path)
+   # -> 若解析後的路徑越過 /data/jobs，將擲出 PathTraversalException。
+
+任何使用者提供的路徑都應透過
+:func:`~automation_file.local.safe_paths.safe_join`（或 ``is_within``
+檢查）解析。直接串接 + ``Path.resolve()`` 會被符號連結與 ``..`` 段繞過。
+
+快速檔案搜尋
+------------
+
+:func:`~automation_file.fast_find` 會挑選目前主機上代價最低的後端——
+優先使用作業系統索引，否則回退為串流式 scandir 走訪，
+讓大目錄樹以最低代價被搜尋：
+
+* macOS：``mdfind``（Spotlight）
+* Linux：``plocate`` / ``locate`` 資料庫
+* Windows：若已安裝則使用 Everything 的 ``es.exe`` CLI
+* 回退：``os.scandir`` 產生器搭配 ``fnmatch`` 比對，可由 ``limit=`` 提早結束
+
+.. code-block:: python
+
+   from automation_file import fast_find, scandir_find, has_os_index
+
+   # 若有索引則查詢，否則回退 scandir。
+   results = fast_find("/var/log", "*.log", limit=100)
+
+   # 強制走可攜路徑（不使用作業系統索引）。
+   results = fast_find("/data", "report_*.csv", use_index=False)
+
+   # 串流產生器——可不掃整棵樹就提早停止。
+   for path in scandir_find("/data", "*.csv"):
+       if "2026" in path:
+           break
+
+   # fast_find 將嘗試哪個索引？回傳 "mdfind" / "locate" /
+   # "plocate" / "es" / None。
+   has_os_index()
+
+JSON 形式：``[["FA_fast_find", {"root": "/var/log", "pattern": "*.log",
+"limit": 50}]]``。
+
+校驗和與完整性
+--------------
+
+以串流方式雜湊任意檔案（任何 :mod:`hashlib` 演算法），
+使用常數時間比較對照預期摘要：
+
+.. code-block:: python
+
+   from automation_file import file_checksum, verify_checksum
+
+   digest = file_checksum("bundle.tar.gz")                 # 預設 sha256
+   verify_checksum("bundle.tar.gz", digest)                # -> True
+   verify_checksum("bundle.tar.gz", "deadbeef...", algorithm="blake2b")
+
+JSON 形式：``FA_file_checksum`` / ``FA_verify_checksum``。
+
+檔案去重
+--------
+
+:func:`~automation_file.find_duplicates` 透過 ``os.scandir`` 一次性
+走訪目錄樹，並以「大小 → 部分雜湊 → 全量雜湊」三段式進行篩選。
+大小唯一的檔案根本不會被雜湊，因此即使百萬檔案也能廉價掃描：
+
+.. code-block:: python
+
+   from automation_file import find_duplicates
+
+   groups = find_duplicates("/data", min_size=1024)
+   # groups: list[list[str]]，每個內層清單都是互相重複的檔案，依大小遞減排列。
+
+JSON 形式：``FA_find_duplicates``。
+
+增量目錄同步
+------------
+
+:func:`~automation_file.sync_dir` 把 ``src`` 增量鏡像到 ``dst``，
+僅複製新增或變更的檔案。預設依 ``(size, mtime)`` 偵測變化；
+當 mtime 不可靠時改用 ``compare="checksum"``。``dst`` 中的多餘檔案
+預設保留——傳入 ``delete=True`` 才會清掉（``dry_run=True`` 可預覽）：
+
+.. code-block:: python
+
+   from automation_file import sync_dir
+
+   summary = sync_dir("/data/src", "/data/dst", delete=True)
+   # summary: {"copied": [...], "skipped": [...], "deleted": [...],
+   #           "errors": [...], "dry_run": False}
+
+符號連結會以連結重新建立而非被跟隨。JSON 形式：``FA_sync_dir``。
+
+目錄清單
+--------
+
+把整棵目錄樹的每個檔案寫入 JSON 清單，稍後再驗證目錄是否變化。
+適合用於發行產物驗證、備份完整性檢查與移動前的預檢：
+
+.. code-block:: python
+
+   from automation_file import write_manifest, verify_manifest
+
+   write_manifest("/release/payload", "/release/MANIFEST.json")
+
+   # 之後……
+   result = verify_manifest("/release/payload", "/release/MANIFEST.json")
+   if not result["ok"]:
+       raise SystemExit(f"manifest mismatch: {result}")
+
+``result`` 會分別回報 ``matched`` / ``missing`` / ``modified`` / ``extra``。
+多餘檔案不會讓驗證失敗（與 ``sync_dir`` 預設不刪除一致）；
+``missing`` 與 ``modified`` 才會失敗。JSON 形式：
+``FA_write_manifest`` / ``FA_verify_manifest``。
diff --git a/docs/source.zh-TW/usage/mcp.rst b/docs/source.zh-TW/usage/mcp.rst
new file mode 100644
index 0000000..e87811b
--- /dev/null
+++ b/docs/source.zh-TW/usage/mcp.rst
@@ -0,0 +1,189 @@
+MCP 伺服器（Claude Desktop / Claude Code）
+==========================================
+
+``automation_file`` 內建一個 Model Context Protocol（MCP）伺服器，
+把共用的 :class:`~automation_file.core.action_registry.ActionRegistry`
+中每一項暴露為 MCP 工具。**Claude Desktop**、**Claude Code**
+以及其他 MCP 宿主，可以像呼叫一般 MCP 工具一樣呼叫 ``FA_*`` 動作——
+無需自寫外掛、無需額外打包。
+
+傳輸方式為 **stdio**（``stdin`` / ``stdout`` 上每行一條 JSON-RPC 2.0 訊息），
+與目前 MCP 宿主使用的協定一致。
+
+提供的能力
+----------
+
+* ``initialize`` 握手，回傳協定版本 ``2024-11-05``、
+  ``serverInfo.name`` 與 ``serverInfo.version``。
+* ``tools/list`` 為每個已註冊的 ``FA_*`` 動作回傳一個 MCP 工具描述，
+  其參數 JSON Schema 由 Python 函式簽名自動推導
+  （``str → "string"``、``int → "integer"`` 等）。
+* ``tools/call`` 透過註冊表派送，並以 JSON 編碼的文字內容區塊回傳結果。
+* ``--allowed-actions`` 允許清單參數，讓你只把註冊表的子集暴露給宿主。
+* 所有內部錯誤都會以 JSON-RPC 錯誤物件形式回傳——
+  宿主不必解析例外字串即可呈現錯誤。
+
+啟動伺服器
+----------
+
+CLI::
+
+   python -m automation_file mcp
+   python -m automation_file mcp --name automation_file --version 1.0.0
+   python -m automation_file mcp --allowed-actions FA_list_dir,FA_file_checksum
+
+行程在前景執行，從 ``stdin`` 讀取分行 JSON 並把回應寫到 ``stdout``。
+通常宿主會替你啟動該行程，不需要手動執行。
+
+從 Python 啟動（例如嵌入到自家 stdio 橋接器中）：
+
+.. code-block:: python
+
+   from automation_file import MCPServer
+
+   server = MCPServer(name="automation_file", version="1.0.0")
+   server.serve_stdio()        # stdin 關閉前阻塞
+
+以自訂註冊表把可呼叫動作面縮小：
+
+.. code-block:: python
+
+   from automation_file import MCPServer
+   from automation_file.core.action_registry import ActionRegistry
+   from automation_file import executor
+
+   safe = ActionRegistry()
+   for name in ("FA_list_dir", "FA_file_checksum", "FA_fast_find"):
+       safe.register(name, executor.registry.resolve(name))
+
+   MCPServer(safe).serve_stdio()
+
+Claude Desktop 設定
+-------------------
+
+在 ``~/Library/Application Support/Claude/claude_desktop_config.json``
+（macOS）或 ``%APPDATA%\Claude\claude_desktop_config.json``
+（Windows）的 ``mcpServers`` 下新增條目：
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "automation_file": {
+         "command": "python",
+         "args": ["-m", "automation_file", "mcp"]
+       }
+     }
+   }
+
+重新啟動 Claude Desktop。``automation_file`` 伺服器會出現在工具面板，
+所有 ``FA_*`` 動作皆可呼叫。
+
+對於會操作敏感路徑的宿主，建議把可用動作鎖死為白名單：
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "automation_file": {
+         "command": "python",
+         "args": [
+           "-m", "automation_file", "mcp",
+           "--allowed-actions",
+           "FA_list_dir,FA_fast_find,FA_file_checksum,FA_verify_checksum"
+         ]
+       }
+     }
+   }
+
+顯式指定虛擬環境的直譯器（避免誤用系統 Python）：
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "automation_file": {
+         "command": "C:\\envs\\fa\\Scripts\\python.exe",
+         "args": ["-m", "automation_file", "mcp"]
+       }
+     }
+   }
+
+Claude Code 設定
+----------------
+
+Claude Code 使用相同的 MCP 定義。可透過 ``claude mcp add`` CLI 註冊::
+
+   claude mcp add automation_file -- python -m automation_file mcp
+
+或在儲存庫根目錄提交 ``.mcp.json``：
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "automation_file": {
+         "command": "python",
+         "args": ["-m", "automation_file", "mcp"]
+       }
+     }
+   }
+
+載入完成後，請 Claude Code 使用 ``mcp__automation_file__FA_*`` 工具——
+例如「使用 FA_fast_find 找出 ./var 下所有 *.log」。
+
+檢視工具目錄
+------------
+
+可呈現與宿主完全一致的描述符——便於測試、GUI 除錯或產生文件：
+
+.. code-block:: python
+
+   from automation_file import tools_from_registry, executor
+
+   for tool in tools_from_registry(executor.registry):
+       print(tool["name"], "->", tool["description"])
+
+每個描述符的形狀如下::
+
+   {
+     "name": "FA_fast_find",
+     "description": "底層可呼叫物件的第一行 docstring。",
+     "inputSchema": {
+       "type": "object",
+       "properties": {"root": {"type": "string"}, "pattern": {"type": "string"}},
+       "required": ["root", "pattern"],
+       "additionalProperties": true,
+     },
+   }
+
+手動煙霧測試
+------------
+
+直接把 JSON-RPC frame 餵給伺服器以確認其能正常載入::
+
+   printf '%s\n%s\n%s\n' \
+     '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
+     '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+     '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"FA_fast_find","arguments":{"root":".","pattern":"*.py","limit":3}}}' \
+     | python -m automation_file mcp
+
+每行輸入在 stdout 上恰得到一條 JSON-RPC 回應（通知沒有回應）。
+
+安全注意事項
+------------
+
+* MCP 伺服器以 **啟動它的 Python 行程的權限** 執行。
+  每次工具呼叫都落在你 shell 使用者帳號中。
+* 預設情況下，伺服器暴露 **全部** 已註冊的 ``FA_*`` 動作，
+  其中包含會刪除檔案、寫檔案系統、上傳到遠端後端的動作。
+  對任何你並非完全信任的宿主，請用 ``--allowed-actions`` 只白名單暴露
+  必要動作。
+* 在打算給第三方宿主使用的 MCP 伺服器啟動前，**不要** 呼叫
+  :func:`~automation_file.PackageLoader.add_package_to_executor`
+  （或暴露其動作）。該輔助函式會註冊任意套件的所有頂層函式 / 類別 / 內建，
+  威力相當於 ``eval``。
+* 伺服器啟動時會透過 ``file_automation_logger`` 以 ``INFO`` 等級記錄
+  暴露的工具數量與設定的伺服器名稱。工具呼叫負載從不被記錄。
+* 涉及對外 HTTP 的動作（``FA_download_file``、各雲端後端）仍會通過
+  SSRF 檢查；MCP 層不會放鬆任何單一動作的檢查。
diff --git a/docs/source.zh-TW/usage/notifications.rst b/docs/source.zh-TW/usage/notifications.rst
new file mode 100644
index 0000000..fdf81d8
--- /dev/null
+++ b/docs/source.zh-TW/usage/notifications.rst
@@ -0,0 +1,27 @@
+通知
+====
+
+可主動推送訊息，也可在觸發器 / 排程器失敗時自動通知，
+支援 webhook、Slack 與 SMTP：
+
+.. code-block:: python
+
+   from automation_file import (
+       SlackSink, WebhookSink, EmailSink,
+       notification_manager, notify_send,
+   )
+
+   notification_manager.register(SlackSink("https://hooks.slack.com/services/T/B/X"))
+   notify_send("deploy complete", body="rev abc123", level="info")
+
+每個 sink 皆實作相同的 ``send(subject, body, level)`` 契約；
+扇出 :class:`~automation_file.NotificationManager` 負責：
+
+- **逐 sink 錯誤隔離** —— 一個壞 sink 不會拖累其他。
+- **滑動視窗去重** —— ``dedup_seconds`` 內相同的
+  ``(subject, body, level)`` 會被丟棄，防止卡住的觸發器把通道刷爆。
+- **SSRF 檢查** —— 每個 webhook / Slack URL 都會被檢查。
+
+排程器與觸發器在失敗時會自動以 ``level="error"`` 通知——
+只要註冊任意一個 sink，就能取得正式環境告警。JSON 形式：
+``FA_notify_send`` / ``FA_notify_list``。
diff --git a/docs/source.zh-TW/usage/plugins.rst b/docs/source.zh-TW/usage/plugins.rst
new file mode 100644
index 0000000..b063dc9
--- /dev/null
+++ b/docs/source.zh-TW/usage/plugins.rst
@@ -0,0 +1,50 @@
+外掛與動態註冊
+==============
+
+進入點外掛
+----------
+
+第三方套件可在 ``pyproject.toml`` 宣告
+``automation_file.actions`` 進入點，註冊自家的 ``FA_*`` 命令::
+
+   [project.entry-points."automation_file.actions"]
+   my_plugin = "my_plugin:register"
+
+其中 ``register`` 是零參可呼叫物件，回傳
+``Mapping[str, Callable]``。一旦外掛安裝到同一個 venv，
+:func:`~automation_file.core.action_registry.build_default_registry`
+會自動拾取——呼叫端無需任何更動：
+
+.. code-block:: python
+
+   # my_plugin/__init__.py
+   def greet(name: str) -> str:
+       return f"hello {name}"
+
+   def register() -> dict:
+       return {"FA_greet": greet}
+
+.. code-block:: python
+
+   # 安裝後的呼叫端：
+   from automation_file import execute_action
+   execute_action([["FA_greet", {"name": "world"}]])
+
+外掛失敗（匯入錯誤、工廠例外、回傳形狀錯誤、被註冊表拒絕）
+會被記錄並吞掉，單一壞外掛不會拖垮整個函式庫。
+
+動態套件註冊
+------------
+
+.. code-block:: python
+
+   from automation_file import package_manager, execute_action
+
+   package_manager.add_package_to_executor("math")
+   execute_action([["math_sqrt", [16.0]]])   # -> 4.0
+
+.. warning::
+
+   ``package_manager.add_package_to_executor`` 會註冊任意套件的所有
+   頂層函式 / 類別 / 內建。**切勿** 暴露給不可信任的輸入
+   （例如透過 TCP、HTTP 或 :doc:`mcp` 伺服器）。
diff --git a/docs/source.zh-TW/usage/quickstart.rst b/docs/source.zh-TW/usage/quickstart.rst
new file mode 100644
index 0000000..66582bf
--- /dev/null
+++ b/docs/source.zh-TW/usage/quickstart.rst
@@ -0,0 +1,65 @@
+快速開始
+========
+
+JSON 動作清單
+-------------
+
+動作可採用三種形狀之一：
+
+.. code-block:: json
+
+   ["FA_name"]
+   ["FA_name", {"kwarg": "value"}]
+   ["FA_name", ["positional", "args"]]
+
+動作清單是動作的陣列。執行器依序執行並回傳
+``"execute[<index>]: <action>" -> result | repr(error)`` 的對應表。
+
+.. code-block:: python
+
+   from automation_file import execute_action, read_action_json
+
+   results = execute_action([
+       ["FA_create_dir", {"dir_path": "build"}],
+       ["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}],
+       ["FA_zip_dir", {"dir_we_want_to_zip": "build", "zip_name": "build_snapshot"}],
+   ])
+
+   # 或從檔案載入：
+   results = execute_action(read_action_json("actions.json"))
+
+驗證、dry-run、平行執行
+-----------------------
+
+.. code-block:: python
+
+   from automation_file import (
+       execute_action, execute_action_parallel, validate_action,
+   )
+
+   # Fail-fast 驗證：若有未知名稱，執行前即中止整批。
+   execute_action(actions, validate_first=True)
+
+   # Dry-run：記錄將呼叫什麼但不實際呼叫。
+   execute_action(actions, dry_run=True)
+
+   # 平行：透過執行緒池執行彼此獨立的動作。
+   execute_action_parallel(actions, max_workers=4)
+
+   # 手動驗證——回傳已解析的名稱清單。
+   names = validate_action(actions)
+
+註冊自訂動作
+------------
+
+.. code-block:: python
+
+   from automation_file import add_command_to_executor, execute_action
+
+   def greet(name: str) -> str:
+       return f"hello {name}"
+
+   add_command_to_executor({"greet": greet})
+   execute_action([["greet", {"name": "world"}]])
+
+進入點打包與動態套件註冊請見 :doc:`plugins`。
diff --git a/docs/source.zh-TW/usage/reliability.rst b/docs/source.zh-TW/usage/reliability.rst
new file mode 100644
index 0000000..b0d19ba
--- /dev/null
+++ b/docs/source.zh-TW/usage/reliability.rst
@@ -0,0 +1,33 @@
+可靠性
+======
+
+為自家的可呼叫物件套上重試：
+
+.. code-block:: python
+
+   from automation_file import retry_on_transient
+
+   @retry_on_transient(max_attempts=5, backoff_base=0.5)
+   def flaky_network_call(): ...
+
+該裝飾器只重試 ``retriable=(…)`` 中明確列出的例外型別
+（預設為 ``ConnectionError`` / ``TimeoutError`` / ``OSError``）。
+切勿放寬到裸 ``Exception``——那會把邏輯 bug 當成瞬時失敗掩蓋。
+重試耗盡後會擲出 :class:`~automation_file.RetryExhaustedException`，
+並透過 ``raise ... from err`` 鏈回最後一次原因。
+
+為單一動作設定上限：
+
+.. code-block:: python
+
+   from automation_file import Quota
+
+   quota = Quota(max_bytes=50 * 1024 * 1024, max_seconds=30.0)
+   with quota.time_budget("bulk-upload"):
+       bulk_upload_work()
+
+   # 也可以直接裝飾可呼叫物件：
+   @quota.wraps
+   def expensive(payload: bytes) -> None: ...
+
+每個上限設成 ``0`` 即表示停用該項檢查。
diff --git a/docs/source.zh-TW/usage/servers.rst b/docs/source.zh-TW/usage/servers.rst
new file mode 100644
index 0000000..78c894e
--- /dev/null
+++ b/docs/source.zh-TW/usage/servers.rst
@@ -0,0 +1,46 @@
+動作伺服器
+==========
+
+TCP 動作伺服器
+--------------
+
+.. code-block:: python
+
+   from automation_file import start_autocontrol_socket_server
+
+   server = start_autocontrol_socket_server(
+       host="localhost", port=9943, shared_secret="optional-secret",
+   )
+   # 稍後：
+   server.shutdown()
+   server.server_close()
+
+設定 ``shared_secret`` 後，用戶端必須在 JSON 動作清單之前加上
+``AUTH <secret>\n`` 前綴。伺服器預設仍綁定 loopback，除非顯式傳入
+``allow_non_loopback=True``，否則拒絕非 loopback 綁定。
+
+每條連線只接受一份 JSON 負載（``recv(8192)``）。
+若要提高該上限，必須同時改採帶長度前綴的協定。
+
+HTTP 動作伺服器
+---------------
+
+.. code-block:: python
+
+   from automation_file import start_http_action_server
+
+   server = start_http_action_server(
+       host="127.0.0.1", port=9944, shared_secret="optional-secret",
+   )
+
+   # 用戶端：
+   # curl -H 'Authorization: Bearer optional-secret' \
+   #      -d '[["FA_create_dir",{"dir_path":"x"}]]' \
+   #      http://127.0.0.1:9944/actions
+
+HTTP 回應皆為 JSON。授權失敗回 ``401``；JSON 異常回 ``400``；
+未知路徑回 ``404``。請求主體上限 1 MB。預設只綁定 loopback；
+若要綁定其他地址需傳 ``allow_non_loopback=True``。
+
+共享密鑰比較使用 :func:`hmac.compare_digest`（常數時間）。
+切勿記錄密鑰或原始負載。
diff --git a/docs/source.zh-TW/usage/transfer.rst b/docs/source.zh-TW/usage/transfer.rst
new file mode 100644
index 0000000..9f262bd
--- /dev/null
+++ b/docs/source.zh-TW/usage/transfer.rst
@@ -0,0 +1,51 @@
+HTTP 傳輸
+=========
+
+可續傳 HTTP 下載
+----------------
+
+:func:`~automation_file.download_file` 接受 ``resume=True``。位元組會寫入
+``<target>.part``；若該臨時檔案已存在，下次呼叫會送出
+``Range: bytes=<n>-``，讓傳輸從現有位元組數繼續。搭配
+``expected_sha256=`` 可在最後一塊寫入後立刻驗證：
+
+.. code-block:: python
+
+   from automation_file import download_file
+
+   download_file(
+       "https://example.com/big.bin",
+       "big.bin",
+       resume=True,
+       expected_sha256="3b0c44298fc1...",
+   )
+
+每個 URL 都會通過
+:func:`~automation_file.remote.url_validator.validate_http_url`，
+攔截 ``file://`` / ``ftp://`` / ``data:`` 等 scheme，以及
+私有 / loopback / link-local / 保留 / 多播 / 未指定地址的 IP。
+預設 20 MB 回應上限、15 秒連線逾時。TLS 驗證從不關閉。
+
+傳輸進度與取消
+--------------
+
+把 ``progress_name="<label>"`` 傳給 :func:`download_file`、
+:func:`s3_upload_file` 或 :func:`s3_download_file`，將該次傳輸登錄到
+共用進度註冊表。GUI 的 **Progress** 分頁每 0.5 秒輪詢一次該註冊表；
+``FA_progress_list``、``FA_progress_cancel``、``FA_progress_clear``
+讓 JSON 動作清單也能取得相同視圖。
+
+.. code-block:: python
+
+   from automation_file import download_file, progress_cancel
+
+   # 一個執行緒裡：
+   download_file("https://example.com/big.bin", "big.bin",
+                 progress_name="big-download")
+
+   # 另一個執行緒 / GUI：
+   progress_cancel("big-download")
+
+取消會在傳輸迴圈中擲出 :class:`~automation_file.CancelledException`。
+傳輸函式會自行捕獲並把狀態標為 ``status="cancelled"``，回傳 ``False``——
+呼叫方無需自行處理該例外。
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 961db5f..c441d14 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -162,10 +162,10 @@ A JSON action list is simply a list of these lists.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents
+   :caption: Documentation
 
    architecture
-   usage
+   usage/index
    api/index
 
 Indices
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
deleted file mode 100644
index 016527c..0000000
--- a/docs/source/usage.rst
+++ /dev/null
@@ -1,581 +0,0 @@
-Usage
-=====
-
-JSON action lists
------------------
-
-An action is one of three shapes:
-
-.. code-block:: json
-
-   ["FA_name"]
-   ["FA_name", {"kwarg": "value"}]
-   ["FA_name", ["positional", "args"]]
-
-An action list is an array of actions. The executor runs them in order and
-returns a mapping of ``"execute[<index>]: <action>" -> result | repr(error)``.
-
-.. code-block:: python
-
-   from automation_file import execute_action, read_action_json
-
-   results = execute_action([
-       ["FA_create_dir", {"dir_path": "build"}],
-       ["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}],
-       ["FA_zip_dir", {"dir_we_want_to_zip": "build", "zip_name": "build_snapshot"}],
-   ])
-
-   # Or load from a file:
-   results = execute_action(read_action_json("actions.json"))
-
-Validation, dry-run, parallel
------------------------------
-
-.. code-block:: python
-
-   from automation_file import (
-       execute_action, execute_action_parallel, validate_action,
-   )
-
-   # Fail-fast validation: aborts before any action runs if any name is unknown.
-   execute_action(actions, validate_first=True)
-
-   # Dry-run: log what would be called without invoking commands.
-   execute_action(actions, dry_run=True)
-
-   # Parallel: run independent actions through a thread pool.
-   execute_action_parallel(actions, max_workers=4)
-
-   # Manual validation — returns the list of resolved names.
-   names = validate_action(actions)
-
-CLI
----
-
-Legacy flags for running JSON action lists::
-
-   python -m automation_file --execute_file actions.json
-   python -m automation_file --execute_dir ./actions/
-   python -m automation_file --execute_str '[["FA_create_dir",{"dir_path":"x"}]]'
-   python -m automation_file --create_project ./my_project
-
-Subcommands for one-shot operations::
-
-   python -m automation_file ui
-   python -m automation_file zip ./src out.zip --dir
-   python -m automation_file unzip out.zip ./restored
-   python -m automation_file download https://example.com/file.bin file.bin
-   python -m automation_file create-file hello.txt --content "hi"
-   python -m automation_file server --host 127.0.0.1 --port 9943
-   python -m automation_file http-server --host 127.0.0.1 --port 9944
-   python -m automation_file drive-upload my.txt --token token.json --credentials creds.json
-
-Google Drive
-------------
-
-.. code-block:: python
-
-   from automation_file import driver_instance, drive_upload_to_drive
-
-   driver_instance.later_init("token.json", "credentials.json")
-   drive_upload_to_drive("example.txt")
-
-TCP action server
------------------
-
-.. code-block:: python
-
-   from automation_file import start_autocontrol_socket_server
-
-   server = start_autocontrol_socket_server(
-       host="localhost", port=9943, shared_secret="optional-secret",
-   )
-   # later:
-   server.shutdown()
-   server.server_close()
-
-When ``shared_secret`` is supplied, the client must prefix each payload with
-``AUTH <secret>\\n`` before the JSON action list. The server still binds to
-loopback by default and refuses non-loopback binds unless
-``allow_non_loopback=True`` is passed.
-
-HTTP action server
-------------------
-
-.. code-block:: python
-
-   from automation_file import start_http_action_server
-
-   server = start_http_action_server(
-       host="127.0.0.1", port=9944, shared_secret="optional-secret",
-   )
-
-   # Client side:
-   # curl -H 'Authorization: Bearer optional-secret' \
-   #      -d '[["FA_create_dir",{"dir_path":"x"}]]' \
-   #      http://127.0.0.1:9944/actions
-
-HTTP responses are JSON. When ``shared_secret`` is set the client must send
-``Authorization: Bearer <secret>``.
-
-Reliability
------------
-
-Apply retries to your own callables:
-
-.. code-block:: python
-
-   from automation_file import retry_on_transient
-
-   @retry_on_transient(max_attempts=5, backoff_base=0.5)
-   def flaky_network_call(): ...
-
-Enforce per-action limits:
-
-.. code-block:: python
-
-   from automation_file import Quota
-
-   quota = Quota(max_bytes=50 * 1024 * 1024, max_seconds=30.0)
-   with quota.time_budget("bulk-upload"):
-       bulk_upload_work()
-
-Path safety
------------
-
-.. code-block:: python
-
-   from automation_file import safe_join
-
-   target = safe_join("/data/jobs", user_supplied_path)
-   # -> raises PathTraversalException if the resolved path escapes /data/jobs.
-
-Cloud / SFTP backends
----------------------
-
-Every backend (S3, Azure Blob, Dropbox, SFTP) is bundled with ``automation_file``
-and auto-registered by :func:`~automation_file.core.action_registry.build_default_registry`.
-There is no extra install step — call ``later_init`` on the singleton and go:
-
-.. code-block:: python
-
-   from automation_file import execute_action, s3_instance
-
-   s3_instance.later_init(region_name="us-east-1")
-
-   execute_action([
-       ["FA_s3_upload_file", {"local_path": "report.csv", "bucket": "reports", "key": "report.csv"}],
-   ])
-
-All backends expose the same five operations:
-``upload_file``, ``upload_dir``, ``download_file``, ``delete_*``, ``list_*``.
-``register_<backend>_ops(registry)`` is still public for callers that build
-custom registries.
-
-SFTP specifically uses :class:`paramiko.RejectPolicy` — unknown hosts are
-rejected rather than auto-added. Provide ``known_hosts`` explicitly or rely on
-``~/.ssh/known_hosts``.
-
-File-watcher triggers
----------------------
-
-Run an action list whenever a filesystem event fires on a watched path. The
-module-level :data:`~automation_file.trigger.trigger_manager` keeps a named
-registry of active watchers so the JSON facade and the GUI share one
-lifecycle.
-
-.. code-block:: python
-
-   from automation_file import watch_start, watch_stop
-
-   watch_start(
-       name="inbox-sweeper",
-       path="/data/inbox",
-       action_list=[["FA_copy_all_file_to_dir", {"source_dir": "/data/inbox",
-                                                 "target_dir": "/data/processed"}]],
-       events=["created", "modified"],
-       recursive=False,
-   )
-   # later:
-   watch_stop("inbox-sweeper")
-
-Or drive it from a JSON action list with ``FA_watch_start`` /
-``FA_watch_stop`` / ``FA_watch_stop_all`` / ``FA_watch_list``.
-
-Cron scheduler
---------------
-
-Run an action list on a recurring schedule. The 5-field cron parser supports
-``*``, exact values, ``a-b`` ranges, comma-separated lists, and ``*/n`` step
-syntax with ``jan``..``dec`` / ``sun``..``sat`` aliases.
-
-.. code-block:: python
-
-   from automation_file import schedule_add
-
-   schedule_add(
-       name="nightly-snapshot",
-       cron_expression="0 2 * * *",           # every day at 02:00 local time
-       action_list=[["FA_zip_dir", {"dir_we_want_to_zip": "/data",
-                                    "zip_name": "/backup/data_nightly"}]],
-   )
-
-A background thread wakes on minute boundaries, so expressions with
-sub-minute precision are not supported. Use ``FA_schedule_add`` /
-``FA_schedule_remove`` / ``FA_schedule_remove_all`` / ``FA_schedule_list``
-from JSON.
-
-Transfer progress + cancellation
---------------------------------
-
-Pass ``progress_name="<label>"`` to :func:`download_file`,
-:func:`s3_upload_file`, or :func:`s3_download_file` to register the transfer
-with the shared progress registry. The GUI's **Progress** tab polls the
-registry every half second; ``FA_progress_list``, ``FA_progress_cancel``,
-and ``FA_progress_clear`` give JSON action lists the same view.
-
-.. code-block:: python
-
-   from automation_file import download_file, progress_cancel
-
-   # In one thread:
-   download_file("https://example.com/big.bin", "big.bin",
-                 progress_name="big-download")
-
-   # In another thread / from the GUI:
-   progress_cancel("big-download")
-
-Cancellation raises :class:`~automation_file.CancelledException` inside the
-transfer loop. The transfer function catches it, marks the reporter
-``status="cancelled"``, and returns ``False`` — callers don't need to handle
-the exception themselves.
-
-Fast file search
-----------------
-
-:func:`fast_find` picks the cheapest backend available on the host — OS
-index first, streaming scandir walk as a fallback — so large trees are
-searched with minimal energy:
-
-* macOS: ``mdfind`` (Spotlight)
-* Linux: ``plocate`` / ``locate`` database
-* Windows: Everything's ``es.exe`` CLI, if installed
-* Fallback: ``os.scandir`` generator with ``fnmatch`` matching and early
-  termination via ``limit=``
-
-.. code-block:: python
-
-   from automation_file import fast_find, scandir_find, has_os_index
-
-   # Query an indexer when available, fall back to scandir otherwise.
-   results = fast_find("/var/log", "*.log", limit=100)
-
-   # Force the portable path (skip the OS indexer).
-   results = fast_find("/data", "report_*.csv", use_index=False)
-
-   # Streaming generator — stop early without scanning the whole tree.
-   for path in scandir_find("/data", "*.csv"):
-       if "2026" in path:
-           break
-
-   # Which indexer will fast_find try?  Returns "mdfind" / "locate" /
-   # "plocate" / "es" / None.
-   has_os_index()
-
-The same action is available to JSON action lists as ``FA_fast_find``:
-
-.. code-block:: json
-
-   [["FA_fast_find", {"root": "/var/log", "pattern": "*.log", "limit": 50}]]
-
-Checksums and integrity verification
-------------------------------------
-
-Hash any file with a streaming reader (any :mod:`hashlib` algorithm) and
-verify it against an expected digest using constant-time comparison:
-
-.. code-block:: python
-
-   from automation_file import file_checksum, verify_checksum
-
-   digest = file_checksum("bundle.tar.gz")                 # sha256 by default
-   verify_checksum("bundle.tar.gz", digest)                # -> True
-   verify_checksum("bundle.tar.gz", "deadbeef...", algorithm="blake2b")
-
-The same functions are available to JSON action lists as
-``FA_file_checksum`` and ``FA_verify_checksum``.
-
-Resumable HTTP downloads
-------------------------
-
-:func:`~automation_file.download_file` accepts ``resume=True``. Bytes are
-written to ``<target>.part``; if the tempfile already exists the next call
-sends ``Range: bytes=<n>-`` so the transfer picks up where it left off.
-Combined with ``expected_sha256=`` the download is verified immediately
-after the last chunk is written:
-
-.. code-block:: python
-
-   from automation_file import download_file
-
-   download_file(
-       "https://example.com/big.bin",
-       "big.bin",
-       resume=True,
-       expected_sha256="3b0c44298fc1...",
-   )
-
-File deduplication
-------------------
-
-:func:`~automation_file.find_duplicates` walks a tree once with
-``os.scandir`` and runs a three-stage size → partial-hash → full-hash
-pipeline. Files with unique sizes are eliminated without being hashed at
-all, so a tree of millions of files is cheap to scan:
-
-.. code-block:: python
-
-   from automation_file import find_duplicates
-
-   groups = find_duplicates("/data", min_size=1024)
-   # groups: list[list[str]], each inner list is a set of identical files
-   # sorted by size descending.
-
-``FA_find_duplicates`` exposes the same call to JSON action lists.
-
-Incremental directory sync
---------------------------
-
-:func:`~automation_file.sync_dir` mirrors ``src`` into ``dst`` by copying
-only files that are new or changed. Change detection is ``(size, mtime)``
-by default; pass ``compare="checksum"`` when mtime is unreliable. Extras
-under ``dst`` are left alone by default — pass ``delete=True`` to prune
-them (and ``dry_run=True`` to preview):
-
-.. code-block:: python
-
-   from automation_file import sync_dir
-
-   summary = sync_dir("/data/src", "/data/dst", delete=True)
-   # summary: {"copied": [...], "skipped": [...], "deleted": [...],
-   #           "errors": [...], "dry_run": False}
-
-The JSON-action form is ``FA_sync_dir``. Symlinks are re-created as
-symlinks rather than followed, so a link pointing outside the tree can't
-blow up the mirror.
-
-Directory manifests
--------------------
-
-Write a JSON manifest of every file under a tree and verify the tree
-hasn't changed later. Useful for release-artifact verification, backup
-integrity checks, and pre-flight checks before moves:
-
-.. code-block:: python
-
-   from automation_file import write_manifest, verify_manifest
-
-   write_manifest("/release/payload", "/release/MANIFEST.json")
-
-   # Later…
-   result = verify_manifest("/release/payload", "/release/MANIFEST.json")
-   if not result["ok"]:
-       raise SystemExit(f"manifest mismatch: {result}")
-
-``result`` reports ``matched``, ``missing``, ``modified``, and ``extra``
-lists separately. Extras do not fail verification (mirror ``sync_dir``'s
-non-deleting default); ``missing`` or ``modified`` do. Both operations
-are exposed to JSON action lists as ``FA_write_manifest`` and
-``FA_verify_manifest``.
-
-Notifications
--------------
-
-Push one-off messages or auto-notify on trigger/scheduler failures via
-webhook, Slack, or SMTP:
-
-.. code-block:: python
-
-   from automation_file import (
-       SlackSink, WebhookSink, EmailSink,
-       notification_manager, notify_send,
-   )
-
-   notification_manager.register(SlackSink("https://hooks.slack.com/services/T/B/X"))
-   notify_send("deploy complete", body="rev abc123", level="info")
-
-Every sink implements the same ``send(subject, body, level)`` contract;
-the fanout :class:`~automation_file.NotificationManager` handles:
-
-- Per-sink error isolation — one broken sink doesn't starve the others.
-- Sliding-window dedup — identical ``(subject, body, level)`` messages
-  within ``dedup_seconds`` are dropped so a stuck trigger can't flood a
-  channel.
-- SSRF validation on every webhook/Slack URL.
-
-Scheduler and trigger dispatchers auto-notify on failure at
-``level="error"`` — registering a sink is all that's needed to get
-production alerts. The JSON-action forms are ``FA_notify_send`` and
-``FA_notify_list``.
-
-Config file and secret providers
---------------------------------
-
-Declare notification sinks and defaults once in a TOML file. Secret
-references resolve at load time from environment variables or a file
-root (Docker / K8s style):
-
-.. code-block:: toml
-
-   # automation_file.toml
-
-   [secrets]
-   file_root = "/run/secrets"
-
-   [defaults]
-   dedup_seconds = 120
-
-   [[notify.sinks]]
-   type = "slack"
-   name = "team-alerts"
-   webhook_url = "${env:SLACK_WEBHOOK}"
-
-   [[notify.sinks]]
-   type = "email"
-   name = "ops-email"
-   host = "smtp.example.com"
-   port = 587
-   sender = "alerts@example.com"
-   recipients = ["ops@example.com"]
-   username = "${env:SMTP_USER}"
-   password = "${file:smtp_password}"
-
-.. code-block:: python
-
-   from automation_file import AutomationConfig, notification_manager
-
-   config = AutomationConfig.load("automation_file.toml")
-   config.apply_to(notification_manager)
-
-Unresolved ``${…}`` references raise
-:class:`~automation_file.SecretNotFoundException` rather than silently
-becoming empty strings. Custom provider chains can be built via
-:class:`~automation_file.ChainedSecretProvider` /
-:class:`~automation_file.EnvSecretProvider` /
-:class:`~automation_file.FileSecretProvider` and passed to
-``AutomationConfig.load(path, provider=…)``.
-
-DAG action executor
--------------------
-
-:func:`~automation_file.execute_action_dag` runs actions in dependency
-order. Each node is ``{"id": str, "action": [name, ...], "depends_on":
-[id, ...]}``. Independent branches fan out across a thread pool; when a
-node fails, its transitive dependents are marked ``skipped``
-(``fail_fast=True``, the default) or still run (``fail_fast=False``):
-
-.. code-block:: python
-
-   from automation_file import execute_action_dag
-
-   results = execute_action_dag([
-       {"id": "fetch",  "action": ["FA_download_file",
-                                   ["https://example.com/src.tar.gz", "src.tar.gz"]]},
-       {"id": "verify", "action": ["FA_verify_checksum",
-                                   ["src.tar.gz", "3b0c44298fc1..."]],
-                        "depends_on": ["fetch"]},
-       {"id": "unpack", "action": ["FA_unzip_file", ["src.tar.gz", "src"]],
-                        "depends_on": ["verify"]},
-       {"id": "report", "action": ["FA_fast_find", ["src", "*.py"]],
-                        "depends_on": ["unpack"]},
-   ])
-
-Cycles, unknown dependencies, self-dependencies, and duplicate ids raise
-:class:`~automation_file.exceptions.DagException` before any node runs.
-The JSON-action form is ``FA_execute_action_dag``.
-
-Entry-point plugins
--------------------
-
-Third-party packages can register their own ``FA_*`` commands by
-declaring an ``automation_file.actions`` entry point in their
-``pyproject.toml``::
-
-   [project.entry-points."automation_file.actions"]
-   my_plugin = "my_plugin:register"
-
-where ``register`` is a zero-argument callable returning a
-``Mapping[str, Callable]``. Once the plugin is installed into the same
-virtual environment,
-:func:`~automation_file.core.action_registry.build_default_registry`
-picks it up automatically — no caller changes required:
-
-.. code-block:: python
-
-   # my_plugin/__init__.py
-   def greet(name: str) -> str:
-       return f"hello {name}"
-
-   def register() -> dict:
-       return {"FA_greet": greet}
-
-.. code-block:: python
-
-   # consumer code, after `pip install my_plugin`
-   from automation_file import execute_action
-   execute_action([["FA_greet", {"name": "world"}]])
-
-Plugin failures (import errors, factory exceptions, wrong return shape,
-registry rejection) are logged and swallowed so one broken plugin cannot
-break the library.
-
-GUI (PySide6)
--------------
-
-A tabbed control surface wraps every feature:
-
-.. code-block:: bash
-
-   python -m automation_file ui
-   # or from the repo root during development:
-   python main_ui.py
-
-.. code-block:: python
-
-   from automation_file import launch_ui
-
-   launch_ui()
-
-Tabs: Home, Local, Transfer, Progress, JSON actions, Triggers, Scheduler,
-Servers. A persistent log panel below the tabs streams every call's result or
-error. Background work runs on ``QThreadPool`` via ``ActionWorker`` so the UI
-stays responsive.
-
-Adding your own commands
-------------------------
-
-.. code-block:: python
-
-   from automation_file import add_command_to_executor, execute_action
-
-   def greet(name: str) -> str:
-       return f"hello {name}"
-
-   add_command_to_executor({"greet": greet})
-   execute_action([["greet", {"name": "world"}]])
-
-Dynamic package registration
-----------------------------
-
-.. code-block:: python
-
-   from automation_file import package_manager, execute_action
-
-   package_manager.add_package_to_executor("math")
-   execute_action([["math_sqrt", [16.0]]])   # -> 4.0
-
-.. warning::
-
-   ``package_manager.add_package_to_executor`` effectively registers every
-   top-level function / class / builtin of a package. Do not expose it to
-   untrusted input (e.g. via the TCP or HTTP servers).
diff --git a/docs/source/usage/cli.rst b/docs/source/usage/cli.rst
new file mode 100644
index 0000000..1b5c543
--- /dev/null
+++ b/docs/source/usage/cli.rst
@@ -0,0 +1,25 @@
+CLI
+===
+
+Legacy flags for running JSON action lists::
+
+   python -m automation_file --execute_file actions.json
+   python -m automation_file --execute_dir ./actions/
+   python -m automation_file --execute_str '[["FA_create_dir",{"dir_path":"x"}]]'
+   python -m automation_file --create_project ./my_project
+
+Subcommands for one-shot operations::
+
+   python -m automation_file ui
+   python -m automation_file zip ./src out.zip --dir
+   python -m automation_file unzip out.zip ./restored
+   python -m automation_file download https://example.com/file.bin file.bin
+   python -m automation_file create-file hello.txt --content "hi"
+   python -m automation_file server --host 127.0.0.1 --port 9943
+   python -m automation_file http-server --host 127.0.0.1 --port 9944
+   python -m automation_file mcp --allowed-actions FA_list_dir,FA_file_checksum
+   python -m automation_file drive-upload my.txt --token token.json --credentials creds.json
+
+The ``mcp`` subcommand starts a Model Context Protocol server over stdio so
+hosts such as Claude Desktop can call ``FA_*`` actions as MCP tools — see
+:doc:`mcp` for the full integration guide.
diff --git a/docs/source/usage/cloud.rst b/docs/source/usage/cloud.rst
new file mode 100644
index 0000000..232933b
--- /dev/null
+++ b/docs/source/usage/cloud.rst
@@ -0,0 +1,62 @@
+Cloud and SFTP backends
+=======================
+
+Every backend (Google Drive, S3, Azure Blob, Dropbox, SFTP) is bundled
+with ``automation_file`` and auto-registered by
+:func:`~automation_file.core.action_registry.build_default_registry`.
+There is no extra install step — call ``later_init`` on the singleton and go:
+
+.. code-block:: python
+
+   from automation_file import execute_action, s3_instance
+
+   s3_instance.later_init(region_name="us-east-1")
+
+   execute_action([
+       ["FA_s3_upload_file", {"local_path": "report.csv",
+                              "bucket": "reports", "key": "report.csv"}],
+   ])
+
+All backends expose the same five operations: ``upload_file``,
+``upload_dir``, ``download_file``, ``delete_*``, ``list_*``.
+``register_<backend>_ops(registry)`` is still public for callers that build
+custom registries.
+
+Google Drive
+------------
+
+.. code-block:: python
+
+   from automation_file import driver_instance, drive_upload_to_drive
+
+   driver_instance.later_init("token.json", "credentials.json")
+   drive_upload_to_drive("example.txt")
+
+OAuth credentials live on disk at the caller-supplied ``token_path``
+(UTF-8). Never log or print the file contents.
+
+SFTP
+----
+
+:class:`~automation_file.SFTPClient` uses :class:`paramiko.RejectPolicy`
+— unknown hosts are rejected rather than auto-added. Provide
+``known_hosts=`` explicitly or rely on ``~/.ssh/known_hosts``. Do not
+swap in ``AutoAddPolicy`` for convenience.
+
+Cross-backend copy
+------------------
+
+The cross-backend dispatcher accepts URI syntax for every backend:
+
+.. code-block:: python
+
+   from automation_file import execute_action
+
+   execute_action([
+       ["FA_cross_copy",
+        {"src": "s3://reports/2026-04.csv",
+         "dst": "drive:///Backups/april.csv"}],
+   ])
+
+URI prefixes: ``local://``, ``s3://``, ``drive://``, ``sftp://``,
+``azure://``, ``dropbox://``, ``ftp://``.
diff --git a/docs/source/usage/config.rst b/docs/source/usage/config.rst
new file mode 100644
index 0000000..10b6553
--- /dev/null
+++ b/docs/source/usage/config.rst
@@ -0,0 +1,46 @@
+Config file and secret providers
+================================
+
+Declare notification sinks and defaults once in a TOML file. Secret
+references resolve at load time from environment variables or a file
+root (Docker / K8s style):
+
+.. code-block:: toml
+
+   # automation_file.toml
+
+   [secrets]
+   file_root = "/run/secrets"
+
+   [defaults]
+   dedup_seconds = 120
+
+   [[notify.sinks]]
+   type = "slack"
+   name = "team-alerts"
+   webhook_url = "${env:SLACK_WEBHOOK}"
+
+   [[notify.sinks]]
+   type = "email"
+   name = "ops-email"
+   host = "smtp.example.com"
+   port = 587
+   sender = "alerts@example.com"
+   recipients = ["ops@example.com"]
+   username = "${env:SMTP_USER}"
+   password = "${file:smtp_password}"
+
+.. code-block:: python
+
+   from automation_file import AutomationConfig, notification_manager
+
+   config = AutomationConfig.load("automation_file.toml")
+   config.apply_to(notification_manager)
+
+Unresolved ``${…}`` references raise
+:class:`~automation_file.SecretNotFoundException` rather than silently
+becoming empty strings. Custom provider chains can be built via
+:class:`~automation_file.ChainedSecretProvider` /
+:class:`~automation_file.EnvSecretProvider` /
+:class:`~automation_file.FileSecretProvider` and passed to
+``AutomationConfig.load(path, provider=…)``.
diff --git a/docs/source/usage/dag.rst b/docs/source/usage/dag.rst
new file mode 100644
index 0000000..a65436f
--- /dev/null
+++ b/docs/source/usage/dag.rst
@@ -0,0 +1,28 @@
+DAG action executor
+===================
+
+:func:`~automation_file.execute_action_dag` runs actions in dependency
+order. Each node is ``{"id": str, "action": [name, ...], "depends_on":
+[id, ...]}``. Independent branches fan out across a thread pool; when a
+node fails, its transitive dependents are marked ``skipped``
+(``fail_fast=True``, the default) or still run (``fail_fast=False``):
+
+.. code-block:: python
+
+   from automation_file import execute_action_dag
+
+   results = execute_action_dag([
+       {"id": "fetch",  "action": ["FA_download_file",
+                                   ["https://example.com/src.tar.gz", "src.tar.gz"]]},
+       {"id": "verify", "action": ["FA_verify_checksum",
+                                   ["src.tar.gz", "3b0c44298fc1..."]],
+                        "depends_on": ["fetch"]},
+       {"id": "unpack", "action": ["FA_unzip_file", ["src.tar.gz", "src"]],
+                        "depends_on": ["verify"]},
+       {"id": "report", "action": ["FA_fast_find", ["src", "*.py"]],
+                        "depends_on": ["unpack"]},
+   ])
+
+Cycles, unknown dependencies, self-dependencies, and duplicate ids raise
+:class:`~automation_file.exceptions.DagException` before any node runs.
+The JSON-action form is ``FA_execute_action_dag``.
diff --git a/docs/source/usage/events.rst b/docs/source/usage/events.rst
new file mode 100644
index 0000000..1e1dbf8
--- /dev/null
+++ b/docs/source/usage/events.rst
@@ -0,0 +1,58 @@
+Triggers and scheduler
+======================
+
+File-watcher triggers
+---------------------
+
+Run an action list whenever a filesystem event fires on a watched path. The
+module-level :data:`~automation_file.trigger.trigger_manager` keeps a named
+registry of active watchers so the JSON facade and the GUI share one
+lifecycle.
+
+.. code-block:: python
+
+   from automation_file import watch_start, watch_stop
+
+   watch_start(
+       name="inbox-sweeper",
+       path="/data/inbox",
+       action_list=[["FA_copy_all_file_to_dir",
+                     {"source_dir": "/data/inbox",
+                      "target_dir": "/data/processed"}]],
+       events=["created", "modified"],
+       recursive=False,
+   )
+   # later:
+   watch_stop("inbox-sweeper")
+
+Or drive it from a JSON action list with ``FA_watch_start`` /
+``FA_watch_stop`` / ``FA_watch_stop_all`` / ``FA_watch_list``.
+
+Cron scheduler
+--------------
+
+Run an action list on a recurring schedule. The 5-field cron parser supports
+``*``, exact values, ``a-b`` ranges, comma-separated lists, and ``*/n`` step
+syntax with ``jan``..``dec`` / ``sun``..``sat`` aliases.
+
+.. code-block:: python
+
+   from automation_file import schedule_add
+
+   schedule_add(
+       name="nightly-snapshot",
+       cron_expression="0 2 * * *",           # every day at 02:00 local time
+       action_list=[["FA_zip_dir", {"dir_we_want_to_zip": "/data",
+                                    "zip_name": "/backup/data_nightly"}]],
+   )
+
+A background thread wakes on minute boundaries, so expressions with
+sub-minute precision are not supported. JSON forms: ``FA_schedule_add`` /
+``FA_schedule_remove`` / ``FA_schedule_remove_all`` / ``FA_schedule_list``.
+
+Both dispatchers call
+:func:`~automation_file.notify.manager.notify_on_failure` when an action
+list raises :class:`~automation_file.exceptions.FileAutomationException`.
+The helper is a no-op when no sinks are registered, so auto-notification
+is an opt-in side effect of registering any
+:class:`~automation_file.NotificationSink` — see :doc:`notifications`.
diff --git a/docs/source/usage/gui.rst b/docs/source/usage/gui.rst
new file mode 100644
index 0000000..9e684e3
--- /dev/null
+++ b/docs/source/usage/gui.rst
@@ -0,0 +1,25 @@
+GUI (PySide6)
+=============
+
+A tabbed control surface wraps every feature:
+
+.. code-block:: bash
+
+   python -m automation_file ui
+   # or from the repo root during development:
+   python main_ui.py
+
+.. code-block:: python
+
+   from automation_file import launch_ui
+
+   launch_ui()
+
+Tabs: Home, Local, Transfer, Progress, JSON actions, Triggers, Scheduler,
+Servers. A persistent log panel below the tabs streams every call's result
+or error. Background work runs on ``QThreadPool`` via ``ActionWorker`` so
+the UI stays responsive.
+
+The GUI shares the same singletons as the rest of the library — registering
+a sink, custom command, or trigger from Python takes effect immediately in
+the running window.
diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst
new file mode 100644
index 0000000..b492b6e
--- /dev/null
+++ b/docs/source/usage/index.rst
@@ -0,0 +1,44 @@
+Usage
+=====
+
+The usage guide is split by topic. Each section is self-contained — pick the
+backend or feature you need and dive in.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting started
+
+   quickstart
+   cli
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Local & transfer
+
+   local
+   transfer
+   cloud
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Servers & integrations
+
+   servers
+   mcp
+   gui
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reliability & events
+
+   reliability
+   events
+   notifications
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Configuration & extension
+
+   config
+   dag
+   plugins
diff --git a/docs/source/usage/local.rst b/docs/source/usage/local.rst
new file mode 100644
index 0000000..b69d277
--- /dev/null
+++ b/docs/source/usage/local.rst
@@ -0,0 +1,129 @@
+Local file operations
+=====================
+
+Path safety
+-----------
+
+.. code-block:: python
+
+   from automation_file import safe_join
+
+   target = safe_join("/data/jobs", user_supplied_path)
+   # -> raises PathTraversalException if the resolved path escapes /data/jobs.
+
+Always resolve user-supplied paths through
+:func:`~automation_file.local.safe_paths.safe_join` (or the ``is_within``
+check). Naive concatenation + ``Path.resolve()`` is bypassed by symlinks and
+``..`` segments.
+
+Fast file search
+----------------
+
+:func:`~automation_file.fast_find` picks the cheapest backend available on
+the host — OS index first, streaming scandir walk as a fallback — so large
+trees are searched with minimal energy:
+
+* macOS: ``mdfind`` (Spotlight)
+* Linux: ``plocate`` / ``locate`` database
+* Windows: Everything's ``es.exe`` CLI, if installed
+* Fallback: ``os.scandir`` generator with ``fnmatch`` matching and early
+  termination via ``limit=``
+
+.. code-block:: python
+
+   from automation_file import fast_find, scandir_find, has_os_index
+
+   # Query an indexer when available, fall back to scandir otherwise.
+   results = fast_find("/var/log", "*.log", limit=100)
+
+   # Force the portable path (skip the OS indexer).
+   results = fast_find("/data", "report_*.csv", use_index=False)
+
+   # Streaming generator — stop early without scanning the whole tree.
+   for path in scandir_find("/data", "*.csv"):
+       if "2026" in path:
+           break
+
+   # Which indexer will fast_find try?  Returns "mdfind" / "locate" /
+   # "plocate" / "es" / None.
+   has_os_index()
+
+JSON form: ``[["FA_fast_find", {"root": "/var/log", "pattern": "*.log",
+"limit": 50}]]``.
+
+Checksums and verification
+--------------------------
+
+Hash any file with a streaming reader (any :mod:`hashlib` algorithm) and
+verify against an expected digest with constant-time comparison:
+
+.. code-block:: python
+
+   from automation_file import file_checksum, verify_checksum
+
+   digest = file_checksum("bundle.tar.gz")                 # sha256 by default
+   verify_checksum("bundle.tar.gz", digest)                # -> True
+   verify_checksum("bundle.tar.gz", "deadbeef...", algorithm="blake2b")
+
+JSON forms: ``FA_file_checksum`` / ``FA_verify_checksum``.
+
+File deduplication
+------------------
+
+:func:`~automation_file.find_duplicates` walks a tree once with
+``os.scandir`` and runs a three-stage size → partial-hash → full-hash
+pipeline. Files with unique sizes are eliminated without being hashed at
+all, so a tree of millions of files is cheap to scan:
+
+.. code-block:: python
+
+   from automation_file import find_duplicates
+
+   groups = find_duplicates("/data", min_size=1024)
+   # groups: list[list[str]], each inner list is a set of identical files
+   # sorted by size descending.
+
+JSON form: ``FA_find_duplicates``.
+
+Incremental directory sync
+--------------------------
+
+:func:`~automation_file.sync_dir` mirrors ``src`` into ``dst`` by copying
+only files that are new or changed. Change detection is ``(size, mtime)``
+by default; pass ``compare="checksum"`` when mtime is unreliable. Extras
+under ``dst`` are left alone unless ``delete=True`` is passed; preview
+with ``dry_run=True``:
+
+.. code-block:: python
+
+   from automation_file import sync_dir
+
+   summary = sync_dir("/data/src", "/data/dst", delete=True)
+   # summary: {"copied": [...], "skipped": [...], "deleted": [...],
+   #           "errors": [...], "dry_run": False}
+
+Symlinks are re-created as symlinks rather than followed. JSON form:
+``FA_sync_dir``.
+
+Directory manifests
+-------------------
+
+Write a JSON manifest of every file under a tree and verify the tree
+hasn't changed later. Useful for release-artifact verification, backup
+integrity checks, and pre-flight checks before moves:
+
+.. code-block:: python
+
+   from automation_file import write_manifest, verify_manifest
+
+   write_manifest("/release/payload", "/release/MANIFEST.json")
+
+   # Later…
+   result = verify_manifest("/release/payload", "/release/MANIFEST.json")
+   if not result["ok"]:
+       raise SystemExit(f"manifest mismatch: {result}")
+
+``result`` reports ``matched``, ``missing``, ``modified``, and ``extra``
+lists separately. Extras do not fail verification (mirrors ``sync_dir``'s
+non-deleting default); ``missing`` or ``modified`` do. JSON forms:
+``FA_write_manifest`` / ``FA_verify_manifest``.
diff --git a/docs/source/usage/mcp.rst b/docs/source/usage/mcp.rst
new file mode 100644
index 0000000..e7febe6
--- /dev/null
+++ b/docs/source/usage/mcp.rst
@@ -0,0 +1,204 @@
+MCP server (Claude Desktop / Claude Code)
+=========================================
+
+``automation_file`` ships a Model Context Protocol (MCP) server that
+exposes every entry of the shared
+:class:`~automation_file.core.action_registry.ActionRegistry` as an MCP
+tool. Hosts such as **Claude Desktop**, **Claude Code**, and other
+MCP-aware clients can then call ``FA_*`` actions exactly like any other
+MCP tool — no plugin code, no extra packaging.
+
+Transport is **stdio** (one JSON-RPC 2.0 message per line on
+``stdin`` / ``stdout``), matching the protocol that current MCP hosts
+consume.
+
+What you get
+------------
+
+* ``initialize`` handshake reporting protocol version ``2024-11-05`` and
+  ``serverInfo.name`` / ``serverInfo.version``.
+* ``tools/list`` returns one MCP tool per registered ``FA_*`` action,
+  with an auto-derived JSON Schema for its arguments (built from the
+  Python signature: ``str → "string"``, ``int → "integer"``, etc.).
+* ``tools/call`` dispatches through the registry and returns the result
+  as a JSON-encoded text content block.
+* ``--allowed-actions`` allow-list flag to surface only a subset of the
+  registry to the host.
+* Every internal failure surfaces as a JSON-RPC error object — the host
+  can render it without parsing exception strings.
+
+Starting the server
+-------------------
+
+CLI::
+
+   python -m automation_file mcp
+   python -m automation_file mcp --name automation_file --version 1.0.0
+   python -m automation_file mcp --allowed-actions FA_list_dir,FA_file_checksum
+
+The process runs in the foreground, reading newline-delimited JSON from
+``stdin`` and writing responses to ``stdout``. MCP hosts spawn this
+process for you — you rarely run it by hand.
+
+From Python (e.g. when embedding into another stdio bridge):
+
+.. code-block:: python
+
+   from automation_file import MCPServer
+
+   server = MCPServer(name="automation_file", version="1.0.0")
+   server.serve_stdio()        # blocks until stdin closes
+
+Filter to a smaller surface area by passing your own registry:
+
+.. code-block:: python
+
+   from automation_file import MCPServer
+   from automation_file.core.action_registry import ActionRegistry
+   from automation_file import executor
+
+   safe = ActionRegistry()
+   for name in ("FA_list_dir", "FA_file_checksum", "FA_fast_find"):
+       safe.register(name, executor.registry.resolve(name))
+
+   MCPServer(safe).serve_stdio()
+
+Claude Desktop configuration
+----------------------------
+
+Add an entry under ``mcpServers`` in
+``~/Library/Application Support/Claude/claude_desktop_config.json`` (macOS) or
+``%APPDATA%\Claude\claude_desktop_config.json`` (Windows):
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "automation_file": {
+         "command": "python",
+         "args": ["-m", "automation_file", "mcp"]
+       }
+     }
+   }
+
+Restart Claude Desktop. The ``automation_file`` server appears in the
+tools panel; every ``FA_*`` action is callable.
+
+Lock the surface area down to a curated allow-list — recommended for
+hosts that operate on sensitive paths:
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "automation_file": {
+         "command": "python",
+         "args": [
+           "-m", "automation_file", "mcp",
+           "--allowed-actions",
+           "FA_list_dir,FA_fast_find,FA_file_checksum,FA_verify_checksum"
+         ]
+       }
+     }
+   }
+
+Use a virtualenv interpreter explicitly (avoids picking up the system
+Python):
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "automation_file": {
+         "command": "C:\\envs\\fa\\Scripts\\python.exe",
+         "args": ["-m", "automation_file", "mcp"]
+       }
+     }
+   }
+
+Claude Code configuration
+-------------------------
+
+Claude Code consumes the same MCP definition. Register the server with
+the ``claude mcp add`` CLI::
+
+   claude mcp add automation_file -- python -m automation_file mcp
+
+Or commit a ``.mcp.json`` to the repo root:
+
+.. code-block:: json
+
+   {
+     "mcpServers": {
+       "automation_file": {
+         "command": "python",
+         "args": ["-m", "automation_file", "mcp"]
+       }
+     }
+   }
+
+After it loads, ask Claude Code to use ``mcp__automation_file__FA_*``
+tools — for example ``"use FA_fast_find to locate every *.log under
+./var"``.
+
+Inspecting the catalogue
+------------------------
+
+Render the same descriptors a host would see — useful for tests, GUI
+debugging, or generating documentation:
+
+.. code-block:: python
+
+   from automation_file import tools_from_registry, executor
+
+   for tool in tools_from_registry(executor.registry):
+       print(tool["name"], "->", tool["description"])
+
+Each descriptor is shaped as::
+
+   {
+     "name": "FA_fast_find",
+     "description": "First docstring line of the underlying callable.",
+     "inputSchema": {
+       "type": "object",
+       "properties": {"root": {"type": "string"}, "pattern": {"type": "string"}},
+       "required": ["root", "pattern"],
+       "additionalProperties": true,
+     },
+   }
+
+Manual smoke test
+-----------------
+
+Pipe JSON-RPC frames straight at the server to confirm it loads::
+
+   printf '%s\n%s\n%s\n' \
+     '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
+     '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+     '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"FA_fast_find","arguments":{"root":".","pattern":"*.py","limit":3}}}' \
+     | python -m automation_file mcp
+
+Each input line gets exactly one JSON-RPC reply on stdout (notifications
+have no reply).
+
+Security considerations
+-----------------------
+
+* The MCP server runs with **the same privileges as the Python process
+  that starts it.** Every tool call lands in your shell's user account.
+* By default the server exposes **every** registered ``FA_*`` action,
+  including ones that delete files, write to the filesystem, or upload
+  to remote backends. Use ``--allowed-actions`` to whitelist a tight
+  surface for any host you don't fully trust.
+* Do **not** call
+  :func:`~automation_file.PackageLoader.add_package_to_executor` (or
+  expose its action) before starting an MCP server intended for a
+  third-party host. That helper registers every top-level function /
+  class / builtin of an arbitrary package and is eval-grade power.
+* The server logs at the ``INFO`` level via
+  ``file_automation_logger`` when it starts, including the number of
+  exposed tools and the configured server name. Tool-call payloads are
+  never logged.
+* Outbound HTTP-bearing actions (``FA_download_file``, the cloud
+  backends) keep their SSRF guard; the MCP layer does not loosen any
+  per-action check.
diff --git a/docs/source/usage/notifications.rst b/docs/source/usage/notifications.rst
new file mode 100644
index 0000000..278d6a0
--- /dev/null
+++ b/docs/source/usage/notifications.rst
@@ -0,0 +1,29 @@
+Notifications
+=============
+
+Push one-off messages or auto-notify on trigger / scheduler failures via
+webhook, Slack, or SMTP:
+
+.. code-block:: python
+
+   from automation_file import (
+       SlackSink, WebhookSink, EmailSink,
+       notification_manager, notify_send,
+   )
+
+   notification_manager.register(SlackSink("https://hooks.slack.com/services/T/B/X"))
+   notify_send("deploy complete", body="rev abc123", level="info")
+
+Every sink implements the same ``send(subject, body, level)`` contract;
+the fanout :class:`~automation_file.NotificationManager` handles:
+
+- **Per-sink error isolation** — one broken sink doesn't starve the
+  others.
+- **Sliding-window dedup** — identical ``(subject, body, level)`` messages
+  within ``dedup_seconds`` are dropped so a stuck trigger can't flood a
+  channel.
+- **SSRF validation** on every webhook / Slack URL.
+
+Scheduler and trigger dispatchers auto-notify on failure at
+``level="error"`` — registering a sink is all that's needed to get
+production alerts. JSON forms: ``FA_notify_send`` / ``FA_notify_list``.
diff --git a/docs/source/usage/plugins.rst b/docs/source/usage/plugins.rst
new file mode 100644
index 0000000..1fae723
--- /dev/null
+++ b/docs/source/usage/plugins.rst
@@ -0,0 +1,53 @@
+Plugins and dynamic registration
+================================
+
+Entry-point plugins
+-------------------
+
+Third-party packages can register their own ``FA_*`` commands by
+declaring an ``automation_file.actions`` entry point in their
+``pyproject.toml``::
+
+   [project.entry-points."automation_file.actions"]
+   my_plugin = "my_plugin:register"
+
+where ``register`` is a zero-argument callable returning a
+``Mapping[str, Callable]``. Once the plugin is installed into the same
+virtual environment,
+:func:`~automation_file.core.action_registry.build_default_registry`
+picks it up automatically — no caller changes required:
+
+.. code-block:: python
+
+   # my_plugin/__init__.py
+   def greet(name: str) -> str:
+       return f"hello {name}"
+
+   def register() -> dict:
+       return {"FA_greet": greet}
+
+.. code-block:: python
+
+   # consumer code, after `pip install my_plugin`
+   from automation_file import execute_action
+   execute_action([["FA_greet", {"name": "world"}]])
+
+Plugin failures (import errors, factory exceptions, wrong return shape,
+registry rejection) are logged and swallowed so one broken plugin cannot
+break the library.
+
+Dynamic package registration
+----------------------------
+
+.. code-block:: python
+
+   from automation_file import package_manager, execute_action
+
+   package_manager.add_package_to_executor("math")
+   execute_action([["math_sqrt", [16.0]]])   # -> 4.0
+
+.. warning::
+
+   ``package_manager.add_package_to_executor`` effectively registers every
+   top-level function / class / builtin of a package. Do not expose it to
+   untrusted input (e.g. via the TCP, HTTP, or :doc:`mcp` servers).
diff --git a/docs/source/usage/quickstart.rst b/docs/source/usage/quickstart.rst
new file mode 100644
index 0000000..a176af5
--- /dev/null
+++ b/docs/source/usage/quickstart.rst
@@ -0,0 +1,65 @@
+Quickstart
+==========
+
+JSON action lists
+-----------------
+
+An action is one of three shapes:
+
+.. code-block:: json
+
+   ["FA_name"]
+   ["FA_name", {"kwarg": "value"}]
+   ["FA_name", ["positional", "args"]]
+
+An action list is an array of actions. The executor runs them in order and
+returns a mapping of ``"execute[<index>]: <action>" -> result | repr(error)``.
+
+.. code-block:: python
+
+   from automation_file import execute_action, read_action_json
+
+   results = execute_action([
+       ["FA_create_dir", {"dir_path": "build"}],
+       ["FA_create_file", {"file_path": "build/hello.txt", "content": "hi"}],
+       ["FA_zip_dir", {"dir_we_want_to_zip": "build", "zip_name": "build_snapshot"}],
+   ])
+
+   # Or load from a file:
+   results = execute_action(read_action_json("actions.json"))
+
+Validation, dry-run, parallel
+-----------------------------
+
+.. code-block:: python
+
+   from automation_file import (
+       execute_action, execute_action_parallel, validate_action,
+   )
+
+   # Fail-fast validation: aborts before any action runs if any name is unknown.
+   execute_action(actions, validate_first=True)
+
+   # Dry-run: log what would be called without invoking commands.
+   execute_action(actions, dry_run=True)
+
+   # Parallel: run independent actions through a thread pool.
+   execute_action_parallel(actions, max_workers=4)
+
+   # Manual validation — returns the list of resolved names.
+   names = validate_action(actions)
+
+Adding your own commands
+------------------------
+
+.. code-block:: python
+
+   from automation_file import add_command_to_executor, execute_action
+
+   def greet(name: str) -> str:
+       return f"hello {name}"
+
+   add_command_to_executor({"greet": greet})
+   execute_action([["greet", {"name": "world"}]])
+
+See :doc:`plugins` for entry-point packaging and dynamic package registration.
diff --git a/docs/source/usage/reliability.rst b/docs/source/usage/reliability.rst
new file mode 100644
index 0000000..fb3a9f4
--- /dev/null
+++ b/docs/source/usage/reliability.rst
@@ -0,0 +1,33 @@
+Reliability
+===========
+
+Apply retries to your own callables:
+
+.. code-block:: python
+
+   from automation_file import retry_on_transient
+
+   @retry_on_transient(max_attempts=5, backoff_base=0.5)
+   def flaky_network_call(): ...
+
+The decorator only retries the exception types passed via ``retriable=(…)``
+(default: ``ConnectionError`` / ``TimeoutError`` / ``OSError``). Never
+widen to bare ``Exception`` — that masks logic bugs as transient failures.
+Always exhausts to :class:`~automation_file.RetryExhaustedException`
+chained with ``raise ... from err``.
+
+Enforce per-action limits:
+
+.. code-block:: python
+
+   from automation_file import Quota
+
+   quota = Quota(max_bytes=50 * 1024 * 1024, max_seconds=30.0)
+   with quota.time_budget("bulk-upload"):
+       bulk_upload_work()
+
+   # Or wrap a callable directly:
+   @quota.wraps
+   def expensive(payload: bytes) -> None: ...
+
+``0`` disables each cap individually.
diff --git a/docs/source/usage/servers.rst b/docs/source/usage/servers.rst
new file mode 100644
index 0000000..70d190b
--- /dev/null
+++ b/docs/source/usage/servers.rst
@@ -0,0 +1,48 @@
+Action servers
+==============
+
+TCP action server
+-----------------
+
+.. code-block:: python
+
+   from automation_file import start_autocontrol_socket_server
+
+   server = start_autocontrol_socket_server(
+       host="localhost", port=9943, shared_secret="optional-secret",
+   )
+   # later:
+   server.shutdown()
+   server.server_close()
+
+When ``shared_secret`` is supplied the client must prefix each payload with
+``AUTH <secret>\n`` before the JSON action list. The server still binds to
+loopback by default and refuses non-loopback binds unless
+``allow_non_loopback=True`` is passed.
+
+The server accepts a single JSON payload per connection (``recv(8192)``).
+Do not raise that limit without also adding a length-framed protocol.
+
+HTTP action server
+------------------
+
+.. code-block:: python
+
+   from automation_file import start_http_action_server
+
+   server = start_http_action_server(
+       host="127.0.0.1", port=9944, shared_secret="optional-secret",
+   )
+
+   # Client side:
+   # curl -H 'Authorization: Bearer optional-secret' \
+   #      -d '[["FA_create_dir",{"dir_path":"x"}]]' \
+   #      http://127.0.0.1:9944/actions
+
+HTTP responses are JSON. Auth failures return ``401``; malformed JSON
+returns ``400``; unknown paths return ``404``. Request body capped at
+1 MB. Loopback-only by default; ``allow_non_loopback=True`` is required to
+bind elsewhere.
+
+The shared secret comparison uses :func:`hmac.compare_digest` (constant
+time). Never log the secret or the raw payload.
diff --git a/docs/source/usage/transfer.rst b/docs/source/usage/transfer.rst
new file mode 100644
index 0000000..fa55746
--- /dev/null
+++ b/docs/source/usage/transfer.rst
@@ -0,0 +1,54 @@
+HTTP transfers
+==============
+
+Resumable HTTP downloads
+------------------------
+
+:func:`~automation_file.download_file` accepts ``resume=True``. Bytes are
+written to ``<target>.part``; if the tempfile already exists the next call
+sends ``Range: bytes=<n>-`` so the transfer picks up where it left off.
+Combined with ``expected_sha256=`` the download is verified immediately
+after the last chunk is written:
+
+.. code-block:: python
+
+   from automation_file import download_file
+
+   download_file(
+       "https://example.com/big.bin",
+       "big.bin",
+       resume=True,
+       expected_sha256="3b0c44298fc1...",
+   )
+
+Every URL passes through
+:func:`~automation_file.remote.url_validator.validate_http_url`, blocking
+``file://`` / ``ftp://`` / ``data:`` schemes and IPs in private, loopback,
+link-local, reserved, multicast, or unspecified ranges. Default 20 MB
+response cap and 15 s connection timeout. TLS verification is never
+disabled.
+
+Transfer progress and cancellation
+----------------------------------
+
+Pass ``progress_name="<label>"`` to :func:`download_file`,
+:func:`s3_upload_file`, or :func:`s3_download_file` to register the transfer
+with the shared progress registry. The GUI's **Progress** tab polls the
+registry every half second; ``FA_progress_list``, ``FA_progress_cancel``,
+and ``FA_progress_clear`` give JSON action lists the same view.
+
+.. code-block:: python
+
+   from automation_file import download_file, progress_cancel
+
+   # In one thread:
+   download_file("https://example.com/big.bin", "big.bin",
+                 progress_name="big-download")
+
+   # In another thread / from the GUI:
+   progress_cancel("big-download")
+
+Cancellation raises :class:`~automation_file.CancelledException` inside the
+transfer loop. The transfer function catches it, marks the reporter
+``status="cancelled"``, and returns ``False`` — callers don't need to handle
+the exception themselves.