diff --git a/docs/superpowers/plans/2026-05-04-plan-2-blog-feature.md b/docs/superpowers/plans/2026-05-04-plan-2-blog-feature.md
index 45825f8..eb1d156 100644
--- a/docs/superpowers/plans/2026-05-04-plan-2-blog-feature.md
+++ b/docs/superpowers/plans/2026-05-04-plan-2-blog-feature.md
@@ -152,11 +152,21 @@ The domain `Article.content` field is also widened: the existing entity has `con
 - [ ] **Step 4: Create vitest.config.ts**
 
 ```typescript
+import path from "node:path";
 import { baseVitestConfig } from "@repo/typescript-config/vitest.base";
 
-export default baseVitestConfig;
+export default {
+  ...baseVitestConfig,
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+};
 ```
 
+> Note: Vitest does NOT automatically read tsconfig `paths`. The `@/` alias used in `src/**/*.ts` source/test files must be declared explicitly in vitest.config.ts via `resolve.alias`. Same pattern repeats for every feature package's vitest.config.ts.
+
 - [ ] **Step 5: Create empty index.ts**
 
 ```typescript