diff --git a/src/runtime-artifact-layout.cts b/src/runtime-artifact-layout.cts
index 92feb0385..289f4c160 100644
--- a/src/runtime-artifact-layout.cts
+++ b/src/runtime-artifact-layout.cts
@@ -333,6 +333,7 @@ function convertedCommandsKind(
 //                  (single-level subdir probe of the tap path)
 //     augment    — https://docs.augmentcode.com/cli/skills (flat single-level)
 //     trae       — docs.trae.ai/ide/skills + Trae-AI/TRAE#2253 (flat; nesting errors)
+//                  Trae IDE (trae.ai), not trae-agent — see runtime-homes.cts header note
 //     antigravity— discuss.ai.google.dev/t/more-antigravity-issues/145875 ("will not recursive scan")
 //
 //   FLAT (recursive loader → nesting gives no saving):
diff --git a/src/runtime-homes.cts b/src/runtime-homes.cts
index f41dc917f..7185813b8 100644
--- a/src/runtime-homes.cts
+++ b/src/runtime-homes.cts
@@ -19,6 +19,15 @@
  *             with Kimi selecting the first existing generic skills directory.
  *             ~/.kimi-code/skills is brand-specific and can be selected as a
  *             GSD write target with --config-dir or KIMI_CONFIG_DIR.
+ *   trae    — Targets Trae IDE (trae.ai), the Electron-based IDE — NOT
+ *             trae-agent (github.com/bytedance/trae-agent), a Python CLI that
+ *             uses trae_config.yaml, has no ~/.trae directory, and has no
+ *             skills system. Both are ByteDance "Trae" products; they are
+ *             entirely distinct. The global ~/.trae/skills/ path is
+ *             community-soft-confirmed: docs.trae.ai/ide/skills documents the
+ *             SKILL.md format and project-level .trae/skills/, but does NOT
+ *             publish the global on-disk path; ~/.trae/skills/ rests on
+ *             community evidence incl. Trae-AI/TRAE#2253. Best-effort only.
  */
 
 import os from 'node:os';