diff --git a/tsconfig.json b/tsconfig.json
index 28e71a44..c7887557 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,3 +1,21 @@
+// AgentCompany TypeScript configuration.
+//
+// Three tsconfig files live at repo root; TypeScript supports JSONC-style
+// comments in tsconfig files, so this header is safe.
+//
+//   tsconfig.json       -- default config used by the editor/LSP and by tsc
+//                          (pnpm typecheck). Includes src + tests +
+//                          electron.vite.config.ts. Strict mode, noEmit.
+//   tsconfig.check.json -- extends tsconfig.json but excludes tests. Intended
+//                          for strict production typecheck paths that should
+//                          not be influenced by test files.
+//   tsconfig.base.json  -- NodeNext base config with emit enabled (outDir:
+//                          dist, rootDir: src). Currently ORPHAN: no workspace
+//                          package in this repo extends it. Kept as a reference
+//                          for a future monorepo split (see
+//                          docs/proposals/M5-monorepo-split.md). If the M5
+//                          split does not happen, this file is a candidate
+//                          for deletion per .planning/review2/08-*.
 {
   "compilerOptions": {
     "target": "ES2022",