Document that package.json aliases may target only direct subfolders of src

.agents/memory/imports-aliases-barrels.md

@@ -6,7 +6,16 @@ description: Shared code comes through # aliases in package.json imports, each d
 
 Shared code is imported through Node subpath imports declared in
 `package.json` `imports`, never by a relative path that climbs out of a
-directory:
+directory.
+
+**Targets (user rule, 2026-10-16):** an alias may point ONLY at a direct
+subfolder of `src/`: its `index.ts` (`"#helpers": "./src/helpers/index.ts"`)
+or a `#x/*` pattern inside that one folder. Never alias anything outside
+`src/` (`scripts/`, root files), `src/` itself (no `#plugin` for
+`./src/index.ts`), or a deeper folder (`./src/a/b/`). Code that would need
+such an alias uses a relative import instead; `scripts/` and
+`vite.config.ts` import each other relatively. Layer rules
+(`enforce-layer-order`) must still pass, so reorder entries if needed.
 
 ```jsonc
 "imports": {

.agents/memory/tests-layout-vitest.md

@@ -11,8 +11,9 @@ Decided 2026-10-14 for all repos.
   config needed. Packages publish only `dist/`, so colocated tests cost nothing
   in the tarball.
 - **Regression and integration tests** live in the top-level `tests/` folder
-  and use only the public entry point (an alias like `#plugin`), never
-  internals. `vp test tests` runs just these.
+  and use only the public entry point through a relative import
+  (`../src/index.ts`; no alias may target `src/` itself, see
+  [[imports-aliases-barrels]]), never internals. `vp test tests` runs just these.
 - **No in-source tests** (`import.meta.vitest`).
 - **`scripts/` gets no tests** (2026-10-15): it is repo tooling, not
   production code (`project-lint.ts`, `decorators.ts`, `lit-check.ts`,

.agents/skills/migrate-deno-repo/SKILL.md

@@ -27,7 +27,9 @@ with everything.
       { sortPackageJson: false }` and the category-based `lint` block.
 - [ ] Delete `deno.json`, `deno.lock`, and Deno-only files. `mod.ts` →
       `index.ts`; `deno.json` imports → `package.json` `imports` (`#x/*`
-      patterns for trailing-slash mappings); `jsr:`/`npm:` → npm packages.
+      patterns for trailing-slash mappings; aliases may target only direct
+      subfolders of `src/`, anything else becomes a relative import);
+      `jsr:`/`npm:` → npm packages.
 
 **Code**
 

AGENTS.md

@@ -19,6 +19,11 @@ dependency. Keep the sources to erasable syntax and `.ts` imports, which
 type-checks, and `vp test` runs Vitest. Unit tests sit next to the code as
 `src/*.test.ts`; repository-level tests live in `tests/`.
 
+`src/` is flat, so `package.json` has no `imports` aliases and modules, tests,
+and `scripts/` import each other relatively. If one is ever added, it may point
+only at a direct subfolder of `src/` (its `index.ts`, or a `#x/*` pattern
+inside it); never at `src/` itself, a deeper folder, or anything outside `src/`.
+
 The only config files are `package.json`, `tsconfig.json`, and
 `vite.config.ts`, plus `package-lock.json`. Repo-local lint rules and the rule
 list live in `scripts/project-lint.ts`. Lint disable comments are not allowed;