diff --git a/.jules/bolt.md b/.jules/bolt.md
new file mode 100644
index 0000000..c280c08
--- /dev/null
+++ b/.jules/bolt.md
@@ -0,0 +1,3 @@
+## 2024-05-18 - fs.readdirSync performance bottleneck
+**Learning:** Found a severe performance bottleneck in `walkFiles` which combines `fs.readdirSync` with `fs.statSync`. This forces synchronous I/O blocks for every file/directory just to determine if it's a directory.
+**Action:** Replace `fs.readdirSync(..., { withFileTypes: true })` which returns `Dirent` objects, avoiding the need for individual `statSync` calls to check `isDirectory()`. This improves I/O performance significantly when traversing large file trees in this CLI app.
diff --git a/src/files.ts b/src/files.ts
index b1e1e43..06e1521 100644
--- a/src/files.ts
+++ b/src/files.ts
@@ -27,10 +27,9 @@ export function projectKey(start = process.cwd()): string | null {
 export function walkFiles(root: string, predicate: (path: string) => boolean): string[] {
   if (!existsSync(root)) return [];
   const files: string[] = [];
-  for (const entry of readdirSync(root)) {
-    const path = join(root, entry);
-    const stat = statSync(path);
-    if (stat.isDirectory()) files.push(...walkFiles(path, predicate));
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) files.push(...walkFiles(path, predicate));
     else if (predicate(path)) files.push(path);
   }
   return files.sort();