Changeset 0.38.0 (#233)

Co-authored-by: gobha <jasafpro@gmail.com>
Co-committed-by: gobha <jasafpro@gmail.com>

docs/ICD/extensions.md

@@ -275,6 +275,68 @@ def on_tool_call(call):
 - All sandbox modules (including `db`) are available per granted permissions
 - No additional permission is required beyond package being `active`
 
+### Multi-File Starlark Packages (v0.38.0)
+
+Starlark packages support `load()` for splitting code across multiple
+files. The entry point script is `script.star` (or the `entry_point`
+manifest field). Submodules live in `star/`.
+
+**Archive structure:**
+
+```
+my-extension/
+├── manifest.json          ← metadata only (no _starlark_script)
+├── script.star            ← entry point (required for starlark tier)
+├── star/                  ← optional submodules
+│   ├── auth.star
+│   ├── repos.star
+│   └── helpers.star
+├── js/                    ← optional surface assets
+└── css/
+```
+
+**Manifest `entry_point` field (optional):**
+
+```json
+{
+  "tier": "starlark",
+  "entry_point": "script.star"
+}
+```
+
+Default is `script.star`. The installer validates the entry point exists
+in the archive for starlark-tier packages (returns 400 if missing).
+
+**`load()` in Starlark scripts:**
+
+```python
+# script.star
+load("star/auth.star", "auth_headers")
+load("star/repos.star", "get_repos")
+
+def on_request(req):
+    headers = auth_headers(conn)
+    repos = get_repos(conn)
+    return {"status": 200, "body": json.encode(repos)}
+```
+
+**Constraints:**
+- Package-scoped: can only load files within the package's own directory
+- `.star` files only — cannot load `.js`, `.json`, etc.
+- Path traversal (`..`) and absolute paths are rejected
+- Circular dependencies are detected and rejected
+- Loaded files get the same injected modules (`db`, `http`, etc.) as the entry point
+- All loaded files share the same step limit budget (1M ops total)
+
+**Backward compatibility:** Existing packages with `_starlark_script`
+in their manifest continue to work. The runner tries disk first, then
+falls back to the manifest field. Reinstalling extracts `script.star`
+to disk.
+
+**Install errors:**
+- `400` — `starlark package missing entry point "script.star"` (or
+  custom `entry_point` value)
+
 ### Builtin Seeding
 
 On startup, `SeedBuiltinExtensions()` scans `extensions/builtin/`