diff --git a/packages/astro/src/core/sync/write-files.ts b/packages/astro/src/core/sync/write-files.ts
index 8a33e08ba0..9b5135d02d 100644
--- a/packages/astro/src/core/sync/write-files.ts
+++ b/packages/astro/src/core/sync/write-files.ts
@@ -96,6 +96,8 @@ async function setupTsconfig(settings: AstroSettings, fs: typeof fsMod, logger:
 		relative(fileURLToPath(settings.dotAstroDir), fileURLToPath(settings.config.outDir)),
 	);
 
+	// TODO: handle relative include/exclude! Users will add values relative to the root,
+	// but here they should be relative to dotAstroDir
 	const expectedContent = JSON.stringify(
 		{
 			include: [...(settings.config.experimental.typescript?.include ?? []), relativeDtsPath],
diff --git a/packages/astro/src/types/public/config.ts b/packages/astro/src/types/public/config.ts
index db33e2e49d..cc962b48ef 100644
--- a/packages/astro/src/types/public/config.ts
+++ b/packages/astro/src/types/public/config.ts
@@ -1445,7 +1445,6 @@ export interface AstroUserConfig {
 		validateSecrets?: boolean;
 	};
 
-
 	/**
 	 * @docs
 	 * @kind heading
@@ -1975,7 +1974,38 @@ export interface AstroUserConfig {
 		 * @version 5.0.0
 		 * @description
 		 *
-		 * TODO:
+		 * Enables the generation of `.astro/tsconfig.json`. This allows to exclude the `distDir` by default to avoid `astro check` false positives.
+		 *
+		 * If you enable this option, you'll need to update your `tsconfig.json` with a new `extends` value:
+		 *
+		 * ```json title="tsconfig.json" del={2} ins={3}
+		 * {
+		 *   extends: 'astro/tsconfigs/base',
+		 * 	 extends: ['astro/tsconfigs/base', './.astro/tsconfig.json']
+		 * }
+		 * ```
+		 *
+		 * If you have `include` or `exclude` inside your root `tsconfig.json`, you'll need to move them to your Astro config:
+		 *
+		 * ```json title="tsconfig.json" del={2-3}
+		 * {
+		 *   include: ['foo'],
+		 *   exclude: ['bar']
+		 * }
+		 * ```
+		 *
+		 * ```js title="astro.config.*" ins={6-7}
+		 * import { defineConfig } from 'astro/config'
+		 *
+		 * export default defineConfig({
+		 *   experimental: {
+		 *    typescript: {
+		 *      include: ['foo'],
+		 *      exclude: ['bar']
+		 *    }
+		 *   }
+		 * })
+		 * ```
 		 */
 		typescript?: {
 			/**
@@ -1986,7 +2016,25 @@ export interface AstroUserConfig {
 			 * @version 5.0.0
 			 * @description
 			 *
-			 * TODO:
+			 * If you have `include` your root `tsconfig.json`, you'll need to move it to your Astro config:
+			 *
+			 * ```json title="tsconfig.json" del={2}
+			 * {
+			 *   include: ['foo']
+			 * }
+			 * ```
+			 *
+			 * ```js title="astro.config.*" ins={6}
+			 * import { defineConfig } from 'astro/config'
+			 *
+			 * export default defineConfig({
+			 *   experimental: {
+			 *    typescript: {
+			 *      include: ['foo']
+			 *    }
+			 *   }
+			 * })
+			 * ```
 			 */
 			include?: Array<string>;
 
@@ -1998,7 +2046,25 @@ export interface AstroUserConfig {
 			 * @version 5.0.0
 			 * @description
 			 *
-			 * TODO:
+			 * If you have `exclude` your root `tsconfig.json`, you'll need to move it to your Astro config:
+			 *
+			 * ```json title="tsconfig.json" del={2}
+			 * {
+			 *   exclude: ['bar']
+			 * }
+			 * ```
+			 *
+			 * ```js title="astro.config.*" ins={6}
+			 * import { defineConfig } from 'astro/config'
+			 *
+			 * export default defineConfig({
+			 *   experimental: {
+			 *    typescript: {
+			 *      exclude: ['bar']
+			 *    }
+			 *   }
+			 * })
+			 * ```
 			 */
 			exclude?: Array<string>;
 		};
diff --git a/scripts/smoke/check.js b/scripts/smoke/check.js
index 9f00384681..6e3753a4a0 100644
--- a/scripts/smoke/check.js
+++ b/scripts/smoke/check.js
@@ -76,6 +76,8 @@ function prepareExample(examplePath) {
 	const tsconfig = JSON.parse(toJson(originalConfig));
 
 	// Swap to strictest config to make sure it also passes
+	// TODO: once experimental.typescript is not a thing anymore, this needs to be updated
+	// to replace the first member of the array instead of overriding
 	tsconfig.extends = 'astro/tsconfigs/strictest';
 	tsconfig.compilerOptions ??= {}
 	tsconfig.compilerOptions.types = tsconfig.compilerOptions.types ?? []; // Speeds up tests