@cldmv/slothlet 2.10.0 → 2.11.0

package/AGENT-USAGE.md

@@ -144,6 +144,47 @@ export function rootFunctionShout(message) {
 
 > 📖 **See**: [API-RULES.md Rule 4](./API-RULES.md#rule-4-default-export-container-pattern) for root-level default export handling
 
+### Pattern 5: AddApi Special File Pattern (Rule 11)
+
+**File**: `addapi.mjs` loaded via `addApi()` → **API**: Always flattened for API extensions
+
+```js
+// File: plugins/addapi.mjs
+/**
+ * Special addapi.mjs file for runtime API extensions.
+ * Always flattens regardless of autoFlatten setting.
+ */
+export function initializePlugin() {
+	return "Plugin initialized";
+}
+
+export function cleanup() {
+	return "Plugin cleaned up";
+}
+
+export function configure(options) {
+	return `Configured with ${options}`;
+}
+
+// Usage:
+await api.addApi("plugins", "./plugins-folder");
+
+// Result: Always flattened (no .addapi. level)
+api.plugins.initializePlugin(); // ✅ Direct extension
+api.plugins.cleanup(); // ✅ No intermediate namespace
+api.plugins.configure(opts); // ✅ Seamless integration
+```
+
+**Result**: `addapi.mjs` always flattens → Perfect for plugin systems and runtime extensions
+
+**Use Cases**:
+
+- 🔌 **Plugin Systems**: Runtime plugin loading
+- 🔄 **Hot Reloading**: Dynamic API updates during development
+- 📦 **Modular Extensions**: Clean extension of existing API surfaces
+
+> 📖 **See**: [API-RULES.md Rule 11](./API-RULES.md#rule-11-addapi-special-file-pattern) for technical implementation details
+
 ## 🔄 Cross-Module Communication Patterns
 
 ### ✅ Using Live Bindings

package/README.md

@@ -35,14 +35,19 @@ The name might suggest we're taking it easy, but don't be fooled. **Slothlet del
 
 ## ✨ What's New
 
-### Latest: v2.9 (December 30, 2025)
+### Latest: v2.11.0 (January 2025)
 
-- **Per-Request Context Isolation** - New `api.run()` and `api.scope()` methods for isolated context execution ([Documentation](https://github.com/CLDMV/slothlet/blob/master/docs/CONTEXT-PROPAGATION.md#per-request-context-isolation))
-- API Builder Modularization - Improved maintainability and code organization
-- [View Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.9.md)
+- **AddApi Special File Pattern (Rule 11)** - Files named `addapi.mjs` now always flatten for seamless API namespace extensions
+- **Filename-Matches-Container in addApi (Rule 1 Extension)** - Auto-flattening now works in runtime `addApi()` contexts
+- **Enhanced addApi Content Preservation** - Fixed critical issue where multiple addApi calls were overwriting previous content instead of merging
+- **Rule 12 Smart Flattening Enhancements** - Comprehensive smart flattening improvements with 168-scenario test coverage
+- **API Documentation Suite Overhaul** - Enhanced 3-tier navigation system with verified examples and cross-references
+- [View Changelog](./docs/changelog/v2.11.md)
 
 ### Recent Releases
 
+- **v2.10.0** - Function metadata tagging and introspection capabilities ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.10.md))
+- **v2.9** - Per-Request Context Isolation with `api.run()` and `api.scope()` methods ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.9.md))
 - **v2.8** - NPM security fixes and package workflow updates ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.8.md))
 - **v2.7** - Security updates ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.7.md))
 - **v2.6** - Hook System with 4 interceptor types ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.6.md))
@@ -130,7 +135,8 @@ Automatic context preservation across all asynchronous boundaries:
 
 ### Requirements
 
-- **Node.js v16.4.0 or higher** (required for AsyncLocalStorage support)
+- **Node.js v16.20.2 or higher** (required for stack trace API fixes used in path resolution)
+  - Node.js 16.4-16.19 has a stack trace regression. For these versions, use slothlet 2.10.0: `npm install @cldmv/slothlet@2.10.0`
 
 ### Install
 
@@ -324,21 +330,22 @@ console.log("My version:", self.version);
 
 ## 📚 Configuration Options
 
-| Option              | Type      | Default       | Description                                                                                                                                                                                              |
-| ------------------- | --------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `dir`               | `string`  | `"api"`       | Directory to load API modules from (absolute or relative path)                                                                                                                                           |
-| `mode`              | `string`  | `"eager"`     | **New** loading mode - `"lazy"` for on-demand loading, `"eager"` for immediate loading                                                                                                                   |
-| `lazy`              | `boolean` | `false`       | **Legacy** loading strategy (use `mode` instead)                                                                                                                                                         |
-| `engine`            | `string`  | `"singleton"` | Execution environment: `"singleton"`, `"vm"`, `"worker"`, or `"fork"` (experimental modes)                                                                                                               |
-| `runtime`           | `string`  | `"async"`     | Runtime binding system: `"async"` for AsyncLocalStorage (requires Node.js v16.4.0+), `"live"` for live-bindings (works on Node.js v12.20.0+)                                                             |
-| `apiDepth`          | `number`  | `Infinity`    | Directory traversal depth - `0` for root only, `Infinity` for all levels                                                                                                                                 |
-| `debug`             | `boolean` | `false`       | Enable verbose logging (also via `--slothletdebug` flag or `SLOTHLET_DEBUG=true` env var)                                                                                                                |
-| `api_mode`          | `string`  | `"auto"`      | API structure behavior: `"auto"` (detect), `"function"` (force callable), `"object"` (force object)                                                                                                      |
-| `allowApiOverwrite` | `boolean` | `true`        | Allow `addApi()` to overwrite existing endpoints (`false` = prevent overwrites with warning)                                                                                                             |
-| `context`           | `object`  | `{}`          | Context data injected into live-binding (available via `import { context } from "@cldmv/slothlet/runtime"`)                                                                                              |
-| `reference`         | `object`  | `{}`          | Reference object merged into API root level                                                                                                                                                              |
-| `sanitize`          | `object`  | `{}`          | Advanced filename-to-API transformation control with `lowerFirst`, `preserveAllUpper`, `preserveAllLower`, and `rules` (supports exact matches, glob patterns `*json*`, and boundary patterns `**url**`) |
-| `hooks`             | `mixed`   | `false`       | Enable hook system: `true` (enable all), `"pattern"` (enable with pattern), or object with `enabled`, `pattern`, `suppressErrors` options                                                                |
+| Option                  | Type      | Default       | Description                                                                                                                                                                                              |
+| ----------------------- | --------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dir`                   | `string`  | `"api"`       | Directory to load API modules from (absolute or relative path)                                                                                                                                           |
+| `mode`                  | `string`  | `"eager"`     | **New** loading mode - `"lazy"` for on-demand loading, `"eager"` for immediate loading                                                                                                                   |
+| `lazy`                  | `boolean` | `false`       | **Legacy** loading strategy (use `mode` instead)                                                                                                                                                         |
+| `engine`                | `string`  | `"singleton"` | Execution environment: `"singleton"`, `"vm"`, `"worker"`, or `"fork"` (experimental modes)                                                                                                               |
+| `runtime`               | `string`  | `"async"`     | Runtime binding system: `"async"` for AsyncLocalStorage (requires Node.js v16.20.2+), `"live"` for live-bindings (works on Node.js v12.20.0+)                                                            |
+| `apiDepth`              | `number`  | `Infinity`    | Directory traversal depth - `0` for root only, `Infinity` for all levels                                                                                                                                 |
+| `debug`                 | `boolean` | `false`       | Enable verbose logging (also via `--slothletdebug` flag or `SLOTHLET_DEBUG=true` env var)                                                                                                                |
+| `api_mode`              | `string`  | `"auto"`      | API structure behavior: `"auto"` (detect), `"function"` (force callable), `"object"` (force object)                                                                                                      |
+| `allowApiOverwrite`     | `boolean` | `true`        | Allow `addApi()` to overwrite existing endpoints (`false` = prevent overwrites with warning)                                                                                                             |
+| `enableModuleOwnership` | `boolean` | `false`       | Enable module-based API ownership tracking (`true` = track ownership for selective overwrites, `false` = disabled for performance)                                                                       |
+| `context`               | `object`  | `{}`          | Context data injected into live-binding (available via `import { context } from "@cldmv/slothlet/runtime"`)                                                                                              |
+| `reference`             | `object`  | `{}`          | Reference object merged into API root level                                                                                                                                                              |
+| `sanitize`              | `object`  | `{}`          | Advanced filename-to-API transformation control with `lowerFirst`, `preserveAllUpper`, `preserveAllLower`, and `rules` (supports exact matches, glob patterns `*json*`, and boundary patterns `**url**`) |
+| `hooks`                 | `mixed`   | `false`       | Enable hook system: `true` (enable all), `"pattern"` (enable with pattern), or object with `enabled`, `pattern`, `suppressErrors` options                                                                |
 
 **For complete API documentation with detailed parameter descriptions and examples, see [docs/generated/API.md](https://github.com/CLDMV/slothlet/blob/master/docs/generated/API.md)**
 

package/dist/lib/helpers/api_builder/add_api.mjs

@@ -24,7 +24,20 @@ import { resolvePathFromCaller } from "@cldmv/slothlet/helpers/resolve-from-call
 import { cleanMetadata, tagLoadedFunctions } from "./metadata.mjs";
 
 
-export async function addApiFromFolder({ apiPath, folderPath, instance, metadata = {} }) {
+
+
+export async function addApiFromFolder({ apiPath, folderPath, instance, metadata = {}, options = {} }) {
+	const { forceOverwrite = false, moduleId } = options;
+
+	
+	if (forceOverwrite && !moduleId) {
+		throw new Error(`[slothlet] Rule 12: forceOverwrite requires moduleId parameter for ownership tracking`);
+	}
+
+	if (forceOverwrite && !instance.config.enableModuleOwnership) {
+		throw new Error(`[slothlet] Rule 12: forceOverwrite requires enableModuleOwnership: true in slothlet configuration`);
+	}
+
 	if (!instance.loaded) {
 		throw new Error("[slothlet] Cannot add API: API not loaded. Call create() or load() first.");
 	}
@@ -81,6 +94,74 @@ export async function addApiFromFolder({ apiPath, folderPath, instance, metadata
 	}
 
 	
+	
+	
+
+	
+	let earlyCurrentTarget = instance.api;
+	let earlyCurrentBoundTarget = instance.boundapi;
+	const earlyPathParts = normalizedApiPath.split(".");
+
+	for (let i = 0; i < earlyPathParts.length - 1; i++) {
+		const part = earlyPathParts[i];
+		const key = instance._toapiPathKey(part);
+		if (earlyCurrentTarget[key]) {
+			earlyCurrentTarget = earlyCurrentTarget[key];
+		} else {
+			earlyCurrentTarget = null;
+			break;
+		}
+		if (earlyCurrentBoundTarget[key]) {
+			earlyCurrentBoundTarget = earlyCurrentBoundTarget[key];
+		} else {
+			earlyCurrentBoundTarget = null;
+			break;
+		}
+	}
+
+	const earlyFinalKey = instance._toapiPathKey(earlyPathParts[earlyPathParts.length - 1]);
+	let superEarlyExistingTargetContent = null;
+	let superEarlyExistingBoundContent = null;
+
+	if (earlyCurrentTarget && earlyCurrentTarget[earlyFinalKey]) {
+		if (typeof earlyCurrentTarget[earlyFinalKey] === "function" && earlyCurrentTarget[earlyFinalKey].__slothletPath) {
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: SUPER EARLY - Target is lazy proxy - materializing to capture existing content`);
+			}
+			const _ = earlyCurrentTarget[earlyFinalKey].__trigger;
+			await earlyCurrentTarget[earlyFinalKey]();
+		}
+		if (typeof earlyCurrentTarget[earlyFinalKey] === "object") {
+			superEarlyExistingTargetContent = { ...earlyCurrentTarget[earlyFinalKey] };
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: SUPER EARLY - Captured existing target content:`, Object.keys(superEarlyExistingTargetContent));
+			}
+		}
+	}
+
+	if (earlyCurrentBoundTarget && earlyCurrentBoundTarget[earlyFinalKey]) {
+		if (instance.config.debug) {
+			console.log(
+				`[DEBUG] addApi: SUPER EARLY - currentBoundTarget[${earlyFinalKey}] exists, type:`,
+				typeof earlyCurrentBoundTarget[earlyFinalKey]
+			);
+		}
+		if (typeof earlyCurrentBoundTarget[earlyFinalKey] === "function" && earlyCurrentBoundTarget[earlyFinalKey].__slothletPath) {
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: SUPER EARLY - Bound target is lazy proxy - materializing to capture existing bound content`);
+			}
+			const _ = earlyCurrentBoundTarget[earlyFinalKey].__trigger;
+			await earlyCurrentBoundTarget[earlyFinalKey]();
+		}
+		if (typeof earlyCurrentBoundTarget[earlyFinalKey] === "object") {
+			superEarlyExistingBoundContent = { ...earlyCurrentBoundTarget[earlyFinalKey] };
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: SUPER EARLY - Captured existing bound content:`, Object.keys(superEarlyExistingBoundContent));
+			}
+		}
+	}
+
+	
 	let newModules;
 	if (instance.config.lazy) {
 		
@@ -90,6 +171,87 @@ export async function addApiFromFolder({ apiPath, folderPath, instance, metadata
 		newModules = await instance.modes.eager.create.call(instance, resolvedFolderPath, instance.config.apiDepth || Infinity, 0);
 	}
 
+	if (instance.config.debug) {
+		console.log(`[DEBUG] addApi: Loaded modules structure:`, Object.keys(newModules || {}));
+		console.log(`[DEBUG] addApi: Full newModules:`, newModules);
+	}
+
+	
+	
+	if (newModules && typeof newModules === "object" && newModules.addapi) {
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: Found addapi.mjs - applying Rule 6 flattening`);
+			console.log(`[DEBUG] addApi: Original structure:`, Object.keys(newModules));
+			console.log(`[DEBUG] addApi: Addapi contents:`, Object.keys(newModules.addapi));
+		}
+
+		
+		const addapiContent = newModules.addapi;
+
+		
+		delete newModules.addapi;
+
+		
+		if (addapiContent && typeof addapiContent === "object") {
+			
+			Object.assign(newModules, addapiContent);
+
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: After addapi flattening:`, Object.keys(newModules));
+			}
+		} else if (typeof addapiContent === "function") {
+			
+			Object.assign(newModules, addapiContent);
+
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: Flattened addapi function with properties:`, Object.keys(newModules));
+			}
+		}
+	}
+
+	
+	
+	
+	const pathSegments = normalizedApiPath.split(".");
+	const lastSegment = pathSegments[pathSegments.length - 1];
+	let rootLevelFileContent = null;
+
+	if (newModules && typeof newModules === "object" && newModules[lastSegment]) {
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: Found root-level file matching API path segment "${lastSegment}" - applying Rule 7 flattening`);
+		}
+
+		
+		let fileContent = newModules[lastSegment];
+		if (typeof fileContent === "function" && fileContent.name && fileContent.name.startsWith("lazyFolder_")) {
+			
+			if (fileContent.__slothletPath) {
+				const _ = fileContent.__trigger; 
+				await fileContent(); 
+				
+				fileContent = newModules[lastSegment]; 
+				if (instance.config.debug) {
+					console.log(`[DEBUG] addApi: Materialized lazy proxy for root-level file:`, Object.keys(fileContent || {}));
+				}
+			}
+		}
+
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: Root-level file content:`, Object.keys(fileContent || {}));
+		}
+
+		
+		
+		rootLevelFileContent = fileContent && typeof fileContent === "object" ? { ...fileContent } : fileContent;
+
+		
+		delete newModules[lastSegment];
+
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: After removing root-level file, remaining structure:`, Object.keys(newModules));
+		}
+	}
+
 	
 	
 	
@@ -169,6 +331,14 @@ export async function addApiFromFolder({ apiPath, folderPath, instance, metadata
 	
 	const finalKey = instance._toapiPathKey(pathParts[pathParts.length - 1]);
 
+	if (instance.config.debug) {
+		console.log(`[DEBUG] addApi: Final assignment - newModules type:`, typeof newModules, "keys:", Object.keys(newModules || {}));
+	}
+
+	
+	
+	
+
 	
 	if (typeof newModules === "function") {
 		
@@ -177,7 +347,21 @@ export async function addApiFromFolder({ apiPath, folderPath, instance, metadata
 			const existing = currentTarget[finalKey];
 
 			
-			if (instance.config.allowApiOverwrite === false) {
+			if (instance.config.enableModuleOwnership && existing) {
+				const normalizedPath = normalizedApiPath + (normalizedApiPath ? "." : "") + finalKey;
+				const canOverwrite = instance._validateModuleOwnership(normalizedPath, moduleId, forceOverwrite);
+
+				if (forceOverwrite && !canOverwrite) {
+					const existingOwner = instance._getApiOwnership(normalizedPath);
+					throw new Error(
+						`[slothlet] Rule 12: Cannot overwrite API "${normalizedPath}" - owned by module "${existingOwner}", ` +
+							`attempted by module "${moduleId}". Modules can only overwrite APIs they own.`
+					);
+				}
+			}
+
+			
+			if (!forceOverwrite && instance.config.allowApiOverwrite === false) {
 				console.warn(
 					`[slothlet] Skipping addApi: API path "${normalizedApiPath}" final key "${finalKey}" ` +
 						`already exists (type: "${typeof existing}"). Set allowApiOverwrite: true to allow overwrites.`
@@ -206,7 +390,21 @@ export async function addApiFromFolder({ apiPath, folderPath, instance, metadata
 			const existing = currentTarget[finalKey];
 
 			
-			if (instance.config.allowApiOverwrite === false && existing !== undefined && existing !== null) {
+			if (instance.config.enableModuleOwnership && existing) {
+				const normalizedPath = normalizedApiPath + (normalizedApiPath ? "." : "") + finalKey;
+				const canOverwrite = instance._validateModuleOwnership(normalizedPath, moduleId, forceOverwrite);
+
+				if (forceOverwrite && !canOverwrite) {
+					const existingOwner = instance._getApiOwnership(normalizedPath);
+					throw new Error(
+						`[slothlet] Rule 12: Cannot overwrite API "${normalizedPath}" - owned by module "${existingOwner}", ` +
+							`attempted by module "${moduleId}". Modules can only overwrite APIs they own.`
+					);
+				}
+			}
+
+			
+			if (!forceOverwrite && instance.config.allowApiOverwrite === false && existing !== undefined && existing !== null) {
 				
 				const hasContent = typeof existing === "object" ? Object.keys(existing).length > 0 : true;
 				if (hasContent) {
@@ -267,8 +465,54 @@ export async function addApiFromFolder({ apiPath, folderPath, instance, metadata
 		
 		
 		
+
+		
+		if (superEarlyExistingTargetContent) {
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: Restoring existing content - keys:`, Object.keys(superEarlyExistingTargetContent));
+			}
+			Object.assign(currentTarget[finalKey], superEarlyExistingTargetContent);
+		}
+		if (superEarlyExistingBoundContent) {
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: Restoring existing BOUND content - keys:`, Object.keys(superEarlyExistingBoundContent));
+			}
+			Object.assign(currentBoundTarget[finalKey], superEarlyExistingBoundContent);
+		}
+
+		
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: Before merging new modules - current keys:`, Object.keys(currentTarget[finalKey] || {}));
+			console.log(`[DEBUG] addApi: New modules to merge - keys:`, Object.keys(newModules));
+		}
 		Object.assign(currentTarget[finalKey], newModules);
 		Object.assign(currentBoundTarget[finalKey], newModules);
+		if (instance.config.debug) {
+			console.log(`[DEBUG] addApi: After merging new modules - keys:`, Object.keys(currentTarget[finalKey] || {}));
+		}
+
+		
+		if (rootLevelFileContent !== null) {
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: Merging root-level file content into API path "${normalizedApiPath}"`);
+				console.log(`[DEBUG] addApi: Root-level file functions:`, Object.keys(rootLevelFileContent));
+				console.log(`[DEBUG] addApi: Target before root-level merge:`, Object.keys(currentTarget[finalKey]));
+			}
+
+			
+			if (rootLevelFileContent && typeof rootLevelFileContent === "object") {
+				Object.assign(currentTarget[finalKey], rootLevelFileContent);
+				Object.assign(currentBoundTarget[finalKey], rootLevelFileContent);
+			} else if (typeof rootLevelFileContent === "function") {
+				
+				Object.assign(currentTarget[finalKey], rootLevelFileContent);
+				Object.assign(currentBoundTarget[finalKey], rootLevelFileContent);
+			}
+
+			if (instance.config.debug) {
+				console.log(`[DEBUG] addApi: After merging root-level file, final API structure:`, Object.keys(currentTarget[finalKey]));
+			}
+		}
 	} else if (newModules === null || newModules === undefined) {
 		
 		const receivedType = newModules === null ? "null" : "undefined";
@@ -284,7 +528,24 @@ export async function addApiFromFolder({ apiPath, folderPath, instance, metadata
 	}
 
 	
+	if (instance.config.debug) {
+		console.log(`[DEBUG] addApi: Before updateBindings - currentTarget[${finalKey}]:`, Object.keys(currentTarget[finalKey] || {}));
+		console.log(
+			`[DEBUG] addApi: Before updateBindings - currentBoundTarget[${finalKey}]:`,
+			Object.keys(currentBoundTarget[finalKey] || {})
+		);
+	}
+
+	
+	if (instance.config.enableModuleOwnership && moduleId) {
+		const fullApiPath = normalizedApiPath + (normalizedApiPath ? "." : "") + finalKey;
+		instance._registerApiOwnership(fullApiPath, moduleId);
+	}
+
 	instance.updateBindings(instance.context, instance.reference, instance.boundapi);
+	if (instance.config.debug) {
+		console.log(`[DEBUG] addApi: After updateBindings - api[${finalKey}]:`, Object.keys(instance.api[finalKey] || {}));
+	}
 
 	if (instance.config.debug) {
 		console.log(`[DEBUG] addApi: Successfully added modules at ${normalizedApiPath}`);

package/dist/lib/helpers/api_builder/construction.mjs

@@ -66,7 +66,8 @@ export async function buildCategoryStructure(categoryPath, options = {}) {
 		maxDepth,
 		mode,
 		subdirHandler,
-		instance
+		instance,
+		existingApi: options.existingApi
 	});
 
 	
@@ -320,6 +321,34 @@ export async function buildCategoryStructure(categoryPath, options = {}) {
 	}
 
 	
+	
+	let defaultFunctions = [];
+	for (const moduleDecision of processedModules) {
+		const { mod, type } = moduleDecision;
+		if (type === "function" && typeof mod === "function") {
+			defaultFunctions.push({ mod, moduleDecision });
+		}
+	}
+
+	
+	
+	
+	if (defaultFunctions.length === 1 && Object.keys(categoryModules).length === 1) {
+		const categoryDefaultFunction = defaultFunctions[0].mod;
+
+		
+		if (categoryDefaultFunction.name !== categoryName) {
+			try {
+				Object.defineProperty(categoryDefaultFunction, "name", { value: categoryName, configurable: true });
+			} catch {
+				
+			}
+		}
+
+		return categoryDefaultFunction;
+	}
+
+	
 	const keys = Object.keys(categoryModules);
 	if (keys.length === 1) {
 		const singleKey = keys[0];
@@ -416,7 +445,16 @@ export async function buildRootAPI(dir, options = {}) {
 
 			if (lazy) {
 				
-				api[instance._toapiPathKey(entry.name)] = await instance._loadCategory(categoryPath, 0, maxDepth);
+				api[instance._toapiPathKey(entry.name)] = await buildCategoryStructure(categoryPath, {
+					currentDepth: 1,
+					maxDepth,
+					mode: "lazy",
+					subdirHandler: (ctx) => {
+						
+						return instance._loadCategory(ctx.subDirPath, ctx.currentDepth, ctx.maxDepth);
+					},
+					instance
+				});
 			} else {
 				
 				api[instance._toapiPathKey(entry.name)] = await buildCategoryStructure(categoryPath, {

package/dist/lib/helpers/api_builder/decisions.mjs

@@ -321,10 +321,21 @@ export function processModuleForAPI(options) {
 
 	
 	for (const [key, value] of Object.entries(apiAssignments)) {
-		if (debug && key && typeof value === "function" && value.name) {
-			console.log(`[DEBUG] ${mode}: Assigning key '${key}' to function '${value.name}'`);
+		if (debug) {
+			console.log(`[DEBUG] ${mode}: About to assign key '${key}' - current api[${key}]:`, api[key] ? Object.keys(api[key]) : "undefined");
+			console.log(`[DEBUG] ${mode}: New value for key '${key}':`, typeof value === "object" && value ? Object.keys(value) : typeof value);
+		}
+
+		
+		if (api[key] && typeof api[key] === "object" && typeof value === "object" && !Array.isArray(api[key]) && !Array.isArray(value)) {
+			if (debug) {
+				console.log(`[DEBUG] ${mode}: Merging objects for key '${key}' - existing:`, Object.keys(api[key]), "new:", Object.keys(value));
+			}
+			
+			Object.assign(api[key], value);
+		} else {
+			api[key] = value;
 		}
-		api[key] = value;
 	}
 
 	return {
@@ -342,7 +353,7 @@ export function processModuleForAPI(options) {
 
 
 export async function buildCategoryDecisions(categoryPath, options = {}) {
-	const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler } = options;
+	const { currentDepth = 0, maxDepth = Infinity, mode = "eager", subdirHandler, existingApi: _ } = options;
 	const { instance } = options;
 
 	if (!instance || typeof instance._toapiPathKey !== "function") {

package/dist/lib/helpers/resolve-from-caller.mjs

@@ -55,37 +55,74 @@ function pickPrimaryBaseFile() {
 	for (const cs of getStack(pickPrimaryBaseFile)) {
 		const f = toFsPath(cs?.getFileName?.());
 		if (!f) continue;
-		if (f.startsWith?.("node:internal")) continue;
+		
+		if (f.startsWith?.("node:")) continue;
 		files.push(f);
 	}
 
+	console.log(`[DEBUG_RESOLVE] pickPrimaryBaseFile - Total stack frames: ${files.length}`);
+	console.log(`[DEBUG_RESOLVE] ALL stack frames:`);
+	for (let i = 0; i < files.length; i++) {
+		console.log(`[DEBUG_RESOLVE]   [${i}] ${files[i]}`);
+	}
+
 	let iSloth = -1;
 	for (let i = 0; i < files.length; i++) {
-		if (path.basename(files[i]).toLowerCase() === "slothlet.mjs") iSloth = i;
+		if (path.basename(files[i]).toLowerCase() === "slothlet.mjs") {
+			iSloth = i;
+		}
 	}
+
+	console.log(`[DEBUG_RESOLVE] Found slothlet.mjs at index: ${iSloth}, total files: ${files.length}`);
 	if (iSloth !== -1) {
-		const j = iSloth + 1;
-		if (j < files.length) {
-			const b = path.basename(files[j]).toLowerCase();
-			if (/^index\.(mjs|cjs|js)$/.test(b) && j + 1 < files.length) return files[j + 1];
-			return files[j];
+		console.log(`[DEBUG_RESOLVE] Files after slothlet.mjs:`);
+		for (let k = iSloth + 1; k < Math.min(files.length, iSloth + 5); k++) {
+			console.log(`[DEBUG_RESOLVE]   [${k}] ${files[k]}`);
 		}
 	}
-	return null;
+
+	if (iSloth !== -1) {
+		
+		let j = iSloth + 1;
+
+		
+function isSlothletInternalFile(filePath) {
+	if (!filePath) return true;
+
+	
+	if (filePath.includes(path.sep + "src" + path.sep + "lib" + path.sep)) return true;
+
+	
+	if (path.basename(filePath).toLowerCase() === "slothlet.mjs") return true;
+
+	
+	if (filePath.startsWith(THIS_DIR + path.sep)) return true;
+
+	return false;
 }
 
 
 function pickFallbackBaseFile() {
+	console.log("[DEBUG_RESOLVE] pickFallbackBaseFile called");
 	for (const cs of getStack(pickFallbackBaseFile)) {
 		const f = toFsPath(cs?.getFileName?.());
 		if (!f) continue;
-		if (f.startsWith?.("node:internal")) continue;
+		
+		if (f.startsWith?.("node:")) continue;
 		if (f === THIS_FILE) continue;
 		if (f.startsWith(THIS_DIR + path.sep)) continue; 
 		if (path.basename(f).toLowerCase() === "slothlet.mjs") continue;
+		if (isSlothletInternalFile(f)) {
+			console.log(`[DEBUG_RESOLVE] Fallback skipping internal file: ${f}`);
+			continue; 
+		}
+		console.log(`[DEBUG_RESOLVE] Fallback considering: ${f}`);
 		return f;
 	}
-	return THIS_FILE;
+	
+	
+	console.log(`[DEBUG_RESOLVE] Fallback: No user code found in stack, using process.cwd(): ${process.cwd()}`);
+	return process.cwd();
 }
 
 

package/dist/lib/modes/slothlet_eager.mjs

@@ -100,7 +100,35 @@ export async function create(dir, maxDepth = Infinity, currentDepth = 0) {
 	for (const entry of entries) {
 		if (entry.isDirectory() && !entry.name.startsWith(".") && currentDepth < maxDepth) {
 			const categoryPath = path.join(dir, entry.name);
-			api[this._toapiPathKey(entry.name)] = await this._loadCategory(categoryPath, currentDepth + 1, maxDepth);
+			const categoryKey = this._toapiPathKey(entry.name);
+			const categoryResult = await this._buildCategory(categoryPath, {
+				currentDepth: currentDepth + 1,
+				maxDepth,
+				mode: "eager",
+				existingApi: api 
+			});
+
+			
+			if (
+				api[categoryKey] &&
+				typeof api[categoryKey] === "object" &&
+				typeof categoryResult === "object" &&
+				!Array.isArray(api[categoryKey]) &&
+				!Array.isArray(categoryResult)
+			) {
+				if (this.config.debug) {
+					console.log(
+						`[DEBUG] eager: Merging subdirectory '${categoryKey}' - existing:`,
+						Object.keys(api[categoryKey]),
+						"new:",
+						Object.keys(categoryResult)
+					);
+				}
+				
+				Object.assign(api[categoryKey], categoryResult);
+			} else {
+				api[categoryKey] = categoryResult;
+			}
 		}
 	}