diff --git a/__tests__/tsconfig.json b/__tests__/tsconfig.json
index 366c4ab8..83d5121c 100644
--- a/__tests__/tsconfig.json
+++ b/__tests__/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../tsconfig.json",
+  "extends": "../tsconfig.base.json",
   "compilerOptions": {
     "noEmit": true,
     "isolatedModules": false,
diff --git a/docs/tsconfig.json b/docs/tsconfig.json
index 35cd2ee8..df2be3de 100644
--- a/docs/tsconfig.json
+++ b/docs/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../tsconfig.json",
+  "extends": "../tsconfig.base.json",
   "compilerOptions": {
     "allowImportingTsExtensions": true,
     "noEmit": true,
diff --git a/tsconfig.client.json b/tsconfig.client.json
index 0e47095d..d625950b 100644
--- a/tsconfig.client.json
+++ b/tsconfig.client.json
@@ -1,5 +1,5 @@
 {
-  "extends": "./tsconfig.json",
+  "extends": "./tsconfig.base.json",
   "compilerOptions": {
     "lib": ["ES2023", "DOM", "DOM.Iterable"],
     "types": ["./client.d.ts"],
diff --git a/tsconfig.json b/tsconfig.json
index ffcbb947..719f8eca 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,3 +1,24 @@
+// the editor's project for the sources. Self-contained: `vitepress` resolves
+// onto src (same trick as tsconfig.client.json), so the built dist — whose
+// bundled types re-declare the `vite` and default-theme augmentations under
+// different type identities — never enters this program. Tests and docs have
+// their own nearest tsconfigs and resolve the package normally.
 {
-  "extends": "./tsconfig.base.json"
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "paths": {
+      "vitepress": ["./src/client/index.ts"],
+      "vitepress/theme": ["./types/default-theme.d.ts"],
+      "@siteData": ["./src/client/shims.d.ts"],
+      "@theme/index": ["./src/client/shims.d.ts"],
+      "@localSearchIndex": ["./src/client/shims.d.ts"]
+    }
+  },
+  "include": [
+    "src",
+    "types",
+    "scripts",
+    "shared-globals.d.ts",
+    "tsdown.config.ts"
+  ]
 }
diff --git a/tsconfig.node.json b/tsconfig.node.json
index 3de1cdef..36330db4 100644
--- a/tsconfig.node.json
+++ b/tsconfig.node.json
@@ -1,5 +1,5 @@
 {
-  "extends": "./tsconfig.json",
+  "extends": "./tsconfig.base.json",
   "compilerOptions": {
     "lib": ["ES2023"],
     "types": ["node"]
diff --git a/tsconfig.shared.json b/tsconfig.shared.json
index 0a9eb997..0956fe06 100644
--- a/tsconfig.shared.json
+++ b/tsconfig.shared.json
@@ -1,5 +1,5 @@
 {
-  "extends": "./tsconfig.json",
+  "extends": "./tsconfig.base.json",
   "compilerOptions": {
     "lib": ["ES2023"],
     "types": [],