Add module layout docs and require migration guide

Author: mgomes

ROADMAP.md

@@ -263,15 +263,15 @@ Goal: make multi-file script projects easier to compose and maintain.
 
 ### Developer UX
 
-- [ ] Add docs for module project layout best practices.
-- [ ] Add examples for reusable helper modules and namespaced imports.
-- [ ] Add migration guide for existing `require` users.
+- [x] Add docs for module project layout best practices.
+- [x] Add examples for reusable helper modules and namespaced imports.
+- [x] Add migration guide for existing `require` users.
 
 ### v0.17.0 Definition of Done
 
-- [ ] Module APIs are explicit and predictable.
-- [ ] Error output for cycle/import failures is actionable.
-- [ ] Security invariants around module paths are fully tested.
+- [x] Module APIs are explicit and predictable.
+- [x] Error output for cycle/import failures is actionable.
+- [x] Security invariants around module paths are fully tested.
 
 ---
 

docs/examples/module_require.md

@@ -42,6 +42,16 @@ def total_with_fee(amount)
 end
 ```
 
+Namespaced imports scale better as helper sets grow:
+
+```vibe
+def quote_total(amount)
+  require("billing/fees", as: "fees")
+  require("billing/taxes", as: "taxes")
+  taxes.apply(fees.apply(amount))
+end
+```
+
 When `total_with_fee` runs, `require("fees")` resolves the module relative to
 `Config.ModulePaths`, compiles it once, and returns an object containing the
 module’s exports. Use `export def` for explicit control; if no explicit exports
@@ -60,6 +70,21 @@ def compute(amount)
 end
 ```
 
+Reusable helper modules can be shared from a central namespace:
+
+```vibe
+# modules/shared/currency.vibe
+export def cents(value)
+  value * 100
+end
+
+# modules/billing/taxes.vibe
+export def apply(amount)
+  require("../shared/currency", as: "currency")
+  amount + currency.cents(1)
+end
+```
+
 Relative requires (`./` and `../`) resolve from the requiring module’s
 directory and cannot escape the configured module root.
 

docs/introduction.md

@@ -24,5 +24,9 @@ dives on specific topics.
 - `blocks.md` – using block literals for map/select/reduce style patterns.
 - `integration.md` – host integration patterns showing how Go services can
   expose capabilities to scripts.
+- `module_project_layout.md` – recommended structure for multi-module script
+  repositories.
+- `module_require_migration.md` – migration checklist for modern `require`
+  behavior (exports, aliasing, policy hooks).
 - `examples/module_require.md` – practical example showing how to share
   helpers with `require` and module search paths.

docs/module_project_layout.md

@@ -0,0 +1,48 @@
+# Module Project Layout Best Practices
+
+Use a stable directory layout so module paths stay predictable:
+
+```text
+workflows/
+  modules/
+    shared/
+      math.vibe
+      money.vibe
+    billing/
+      fees.vibe
+      taxes.vibe
+  scripts/
+    checkout.vibe
+    payouts.vibe
+```
+
+Guidelines:
+
+- Keep reusable helpers under `modules/shared/`.
+- Group domain logic by folder (`billing/`, `risk/`, `reporting/`).
+- Prefer `export def ...` for public API surface, keep internals unexported.
+- Use `require("module/path", as: "alias")` to avoid global name collisions.
+- Use relative requires only within a module subtree (`./`, `../`).
+- Configure `ModuleAllowList` and `ModuleDenyList` in hosts that need strict import policy boundaries.
+
+Example:
+
+```vibe
+# modules/billing/fees.vibe
+export def apply(amount)
+  amount + shared_rate()
+end
+
+def shared_rate()
+  rates = require("../shared/math", as: "math")
+  math.double(1)
+end
+```
+
+```vibe
+# scripts/checkout.vibe
+def total(amount)
+  require("billing/fees", as: "fees")
+  fees.apply(amount)
+end
+```

docs/module_require_migration.md

@@ -0,0 +1,60 @@
+# Migration Guide for `require`
+
+This guide helps older scripts move to the current module model.
+
+## 1. Prefer explicit exports
+
+Before:
+
+```vibe
+def apply_fee(amount)
+  amount + 1
+end
+```
+
+After:
+
+```vibe
+export def apply_fee(amount)
+  amount + 1
+end
+```
+
+If a module has no `export def`, non-underscore functions are still exported.
+
+## 2. Use aliases for namespacing
+
+Before:
+
+```vibe
+fees = require("fees")
+fees.apply_fee(amount)
+```
+
+After:
+
+```vibe
+require("fees", as: "fees")
+fees.apply_fee(amount)
+```
+
+Aliases make import intent explicit and reduce global collisions.
+
+## 3. Plan for conflict behavior
+
+- Existing globals are not overwritten by module exports.
+- Access conflicting functions through the returned/aliased module object.
+- Alias collisions raise runtime errors (`alias "<name>" already defined`).
+
+## 4. Add policy boundaries in hosts
+
+For long-running or multi-tenant hosts:
+
+- Configure `ModuleAllowList` and `ModuleDenyList`.
+- Use `engine.ClearModuleCache()` when module sources may change.
+
+## 5. Validate with tests
+
+- Add integration tests for required module paths.
+- Add negative tests for denied modules and traversal attempts.
+- Verify cycle errors are actionable (`a -> b -> a`).