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 392ea0e..08cfaae 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
@@ -138,7 +138,7 @@ The domain `Article.content` field is also widened: the existing entity has `con
 }
 ```
 
-> Note: `@/*` path alias is feature-local (resolves to `packages/blog/src/*`). This is the same pattern `packages/core/tsconfig.json` already uses.
+> Note: `@/*` path alias is defined here for use in **test files** only. Source files inside `src/` should use **relative imports** (`../../entities/article` etc.). Reason: when a downstream package like `@repo/core-api` typechecks and follows imports into `@repo/blog`, it descends into blog's source files but doesn't have blog's `@/` alias in its own tsconfig — causing TS2307 errors. Relative imports in source files avoid this. Tests stay in `tests/` or alongside source where they use the same package context, so `@/` works there. Same convention applies to all feature packages in subsequent plans.
 
 - [ ] **Step 3: Create turbo.json**