diff --git a/AGENTS.md b/AGENTS.md
index be7921ba2..4bccb9b07 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -54,7 +54,9 @@ behind human approval.
   audience.
 - Worktrees live in `.worktrees/<branch>`; branch = `cl-<issue#>-<slug>`.
 - Tests are meaningful red/green tests only — no coverage theater. Merged
-  line coverage floor: 80%.
+  line coverage floor: 80%. Unit tests for pure modules sit next to the
+  source they cover (`src/**/*.test.ts`); multi-module / DOM / composition
+  suites stay under a package `test/` tree (or top-level e2e).
 - Deployment is explicit via Pulumi (Railway); CI runs tests only — nothing
   auto-deploys on main.
 
diff --git a/apps/web/README.md b/apps/web/README.md
index 6023f76a4..16d85b186 100644
--- a/apps/web/README.md
+++ b/apps/web/README.md
@@ -62,6 +62,13 @@ Approvals are not a page: pending permission requests land as actionable
 cards in the contextual panel's Notifications band (and, when a channel is
 open, inline in that channel). The `/approvals` route is gone.
 
+## Tests
+
+- **Unit tests** for pure modules (path helpers, reducers, parsers) sit next
+  to the source file under `src/` as `*.test.ts`.
+- **Integration / composition / shell probes** stay under `test/`.
+- `bun test` (via the package script) runs both `./src` and `./test`.
+
 ## Library
 
 `/library` (`src/pages/library-page.tsx`) is the artifact gallery: search,
diff --git a/apps/web/package.json b/apps/web/package.json
index 07bebb35d..978857866 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit",
     "build": "vite build",
     "watch": "vite build --watch",
-    "test": "bun test ./test"
+    "test": "bun test ./src ./test"
   },
   "dependencies": {
     "@corbits/artifact-ui": "workspace:*",
diff --git a/apps/web/test/channel-path.test.ts b/apps/web/src/channel-path.test.ts
similarity index 90%
rename from apps/web/test/channel-path.test.ts
rename to apps/web/src/channel-path.test.ts
index cc90b366e..052120b43 100644
--- a/apps/web/test/channel-path.test.ts
+++ b/apps/web/src/channel-path.test.ts
@@ -1,10 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import {
-  channelIdFromPath,
-  channelPath,
-  isChannelPath,
-} from "../src/channel-path";
+import { channelIdFromPath, channelPath, isChannelPath } from "./channel-path";
 
 describe("channelPath helpers", () => {
   test("builds canonical /c paths", () => {
diff --git a/apps/web/test/canvas-column-state.test.ts b/apps/web/src/shell/canvas-column-state.test.ts
similarity index 97%
rename from apps/web/test/canvas-column-state.test.ts
rename to apps/web/src/shell/canvas-column-state.test.ts
index 41b2b49a2..593481376 100644
--- a/apps/web/test/canvas-column-state.test.ts
+++ b/apps/web/src/shell/canvas-column-state.test.ts
@@ -6,7 +6,7 @@ import {
   openChannelInCanvas,
   resolveCanvasVisibility,
   toggleCanvasColumn,
-} from "../src/shell/canvas-column-state";
+} from "./canvas-column-state";
 
 describe("canvas column state", () => {
   test("starts closed with no channel", () => {