@cldmv/slothlet 2.10.0 → 3.0.0

package/docs/API-RULES.md

@@ -1,88 +1,120 @@
-# Slothlet API Rules - Verified Documentation
+# Slothlet API Rules
 
-> **Verification Status**: Each rule has been systematically verified against actual test files and source code.
-> **Last Updated**: December 30, 2025  
-> **Commit**: `a50531d1ba712f0c4efd9ab9b7cf8f62a0d379da`  
-> **Note**: Source code has been refactored into modular structure. See [API-RULES-CONDITIONS.md](API-RULES-CONDITIONS.md) for complete conditional logic documentation with exact line numbers.
+**Complete Guide to All API Generation Behaviors**
 
-## Methodology
+---
+
+## Document Hierarchy
+
+This is the **middle layer** of slothlet's three-tier documentation system:
 
-Each rule documents:
+```text
+📋 API-RULES/API-FLATTENING.md (F##)     ← User Guide: Clear examples and flowcharts
+          ↑ links to                          ↓ links to
+📊 API-RULES.md (1-13)                   ← YOU ARE HERE: Complete behavior catalog
+          ↑ links to                          ↓ links to
+🔧 API-RULES/API-RULES-CONDITIONS.md     ← Technical: Exact source code locations
+                                              ↓ mapped in
+🗺️ API-RULES/API-RULE-MAPPING.md         ← Traceability Matrix: Rule # ↔ F## ↔ C##
+```
+
+**Cross-Reference Navigation:**
 
-- **Verified Example**: Confirmed to exist in test files with source attribution
-- **Source Code Location**: Exact function and file where the condition is programmed
-- **Processing Path**: Which processing path applies this rule (Root/Subfolder/Multi-Default)
-- **Test File Sources**: Specific test files demonstrating the behavior
+- **For Users**: See [API-RULES/API-FLATTENING.md](API-RULES/API-FLATTENING.md) for user-friendly explanations with examples
+- **For Developers**: See [API-RULES/API-RULES-CONDITIONS.md](API-RULES/API-RULES-CONDITIONS.md) for exact source code locations
+- **Rule Mapping**: See [API-RULES/API-RULE-MAPPING.md](API-RULES/API-RULE-MAPPING.md) for complete Rule # ↔ F## ↔ C## traceability matrix
 
 ---
 
-## Verification Progress
+## Overview
+
+This document catalogs **all 13 API generation behaviors** in slothlet with:
+
+- Verified examples from actual test files with source attribution
+- Cross-references to user guide (F##) and technical details (C##)
+- Source code locations with function names and file references
+- Test file sources demonstrating each behavior in action
+- Processing contexts (Root/Subfolder/Multi-Default/AddApi)
+
+**Why 13 Rules vs Flattening Patterns?**
+
+The [Flattening guide](API-RULES/API-FLATTENING.md) focuses on **when content gets promoted/flattened**. This comprehensive guide covers **all API behaviors** including cases where flattening doesn't occur but specific handling is still needed:
+
+- **Flattening Rules** (1, 7, 8, 10, 11, 13): Core flattening patterns
+- **Non-Flattening Rules** (2, 3, 4, 5, 6, 9): Export collection, function naming, empty modules, mixed exports
+- **AddApi Rules** (11, 12, 13): Runtime API extension behaviors
+
+**Methodology**: Each rule has been systematically verified against test files and source code.
+
+---
 
-- [x] Rule 1: Filename Matches Container Flattening ✅ **VERIFIED** (api_tests/api_test) - Re-verified
-- [x] Rule 2: Named-Only Export Collection ✅ **VERIFIED** (api_tests/api_test) - Re-verified
-- [x] Rule 3: Empty Module Handling ✅ **VERIFIED** (debug testing)
-- [x] Rule 4: Default Export Container Pattern ✅ **VERIFIED** (api_tests/api_test + api_tests/api_tv_test) - Re-verified
-- [x] Rule 5: Multi-Default Export Mixed Pattern ✅ **VERIFIED** (api_tests/api_tv_test) - Re-verified
-- [x] Rule 6: Self-Referential Export Protection ✅ **VERIFIED** (api_tests/api_test) - Tested
-- [x] Rule 7: Auto-Flattening Single Named Export ✅ **VERIFIED** (api_tests/api_test) - Tested
-- [x] Rule 8: Single-File Auto-Flattening Patterns ✅ **FULLY VERIFIED** (All 4 patterns A, B, C, D verified with real test files)
-- [x] Rule 9: Function Name Preference Over Sanitization ✅ **FULLY VERIFIED** (Multiple examples verified: autoIP, parseJSON, getHTTPStatus, XMLParser)
-- [x] Rule 10: Generic Filename Parent-Level Promotion ✅ **VERIFIED** (nest4/singlefile.mjs example verified with api_tests/api_test)
+## Rule Categories
 
-> **Note**: Rule 11 (Single File Context Flattening) has been **intentionally removed** from slothlet for architectural reasons. The rule reduced API path flexibility and was commented out in source code. See [C06](API-RULES-CONDITIONS.md#c06-single-file-context-commented-out) in API-RULES-CONDITIONS.md for details. This maintains cleaner API namespacing while preserving predictable path structures.
+| Category              | Rules        | Focus                       | Cross-References |
+| --------------------- | ------------ | --------------------------- | ---------------- |
+| **Basic Flattening**  | 1, 7, 8      | Core flattening patterns    | [F01-F05](API-RULES/API-FLATTENING.md) → [C01-C11](API-RULES/API-RULES-CONDITIONS.md) |
+| **Export Handling**   | 2, 4, 5      | Default vs Named exports    | [F04-F05](API-RULES/API-FLATTENING.md) → [C08-C21](API-RULES/API-RULES-CONDITIONS.md) |
+| **Special Cases**     | 3, 6, 9, 10  | Edge cases and protections  | [C10, C01, C16-C19](API-RULES/API-RULES-CONDITIONS.md) |
+| **AddApi Extensions** | 11, 12, 13   | Runtime API extensions      | [F06-F08](API-RULES/API-FLATTENING.md) → [C33, C34](API-RULES/API-RULES-CONDITIONS.md) |
 
 ---
 
-## Verified Rules
+## Table of Contents
+
+1. [Rule 1: Filename Matches Container Flattening](#rule-1-filename-matches-container-flattening)
+2. [Rule 2: Named-Only Export Collection](#rule-2-named-only-export-collection)
+3. [Rule 3: Empty Module Handling](#rule-3-empty-module-handling)
+4. [Rule 4: Named Export with Function Name Preservation](#rule-4-named-export-with-function-name-preservation)
+5. [Rule 5: Multiple Module Default Export Handling](#rule-5-multiple-module-default-export-handling)
+6. [Rule 6: Multiple Module Mixed Exports](#rule-6-multiple-module-mixed-exports)
+7. [Rule 7: Single Module Named Export Flattening](#rule-7-single-module-named-export-flattening)
+8. [Rule 8: Single Module Default Export Promotion](#rule-8-single-module-default-export-promotion)
+9. [Rule 9: Function Name Preference Over Sanitization](#rule-9-function-name-preference-over-sanitization)
+10. [Rule 10: Generic Filename Parent-Level Promotion](#rule-10-generic-filename-parent-level-promotion)
+11. [Rule 11: AddApi Special File Pattern](#rule-11-addapi-special-file-pattern)
+12. [Rule 12: Module Ownership and Selective API Overwriting](#rule-12-module-ownership-and-selective-api-overwriting)
+13. [Rule 13: AddApi Path Deduplication Flattening](#rule-13-addapi-path-deduplication-flattening)
+14. [Verification Status](#verification-status)
+15. [Cross-Reference Index](#cross-reference-index)
+
+---
 
-### Rule 1: Filename Matches Container Flattening
+## Rule 1: Filename Matches Container Flattening
 
-**Status**: ✅ **VERIFIED**
+**Category**: Basic Flattening  
+**Status**: ✅ Verified (`api_tests/api_test`)  
+**User Guide**: [F01](API-RULES/API-FLATTENING.md#f01-folder-file-name-matching)  
+**Technical**: [C05, C09b](API-RULES/API-RULES-CONDITIONS.md#c05)
 
-**Condition**: Filename matches folder name AND no default export AND has named exports
-**Source File**: `api_tests/api_test/math/math.mjs`
-**Technical Condition**: `fileName === categoryName && !moduleHasDefault && moduleKeys.length > 0`
+**Condition**: Filename matches folder name AND no default export AND has named exports  
+**Source Files**: `api_tests/api_test/math/math.mjs`  
+**Implementation**: `buildCategoryDecisions()` → `getFlatteningDecision()` → `processModuleForAPI()`
 
 **Verified Examples**:
 
 ```javascript
-// Example A: api_tests/api_test/math/math.mjs (filename "math" matches folder "math")
-export const math = {
-	add: (a, b) => a + b,
-	multiply: (a, b) => a * b
-};
-
-// Result: Flattened to container level (math.math → math)
-api.math.add(2, 3); // → 5 (not api.math.math.add)
-api.math.multiply(2, 3); // → 6 (not api.math.math.multiply)
-
-// Example B: api_tests/api_test/string/string.mjs (filename "string" matches folder "string")
-export const string = {
-	upper: (str) => str.toUpperCase(),
-	reverse: (str) => str.split("").reverse().join("")
-};
-
-// Result: Also flattened to container level (string.string → string)
-api.string.upper("hello"); // → "HELLO" (not api.string.string.upper)
-api.string.reverse("hello"); // → "olleh" (not api.string.string.reverse)
-```
-
-**Test Verification**:
+// File: api_tests/api_test/math/math.mjs
+export function add(a, b) {
+	return a + b;
+}
+export function subtract(a, b) {
+	return a - b;
+}
 
-```bash
-node tests/debug-slothlet.mjs
-# Look for: "bound.math.add(2, 3) 5" and "bound.string.upper('abc') ABC"
-# Confirms flattening works: api.math.add (not api.math.math.add)
+// Without Rule 1: api.math.math.add(2, 3)  ❌ (redundant nesting)
+// With Rule 1:    api.math.add(2, 3)        ✅ (clean flattening)
+api.math.add(2, 3);      // 5
+api.math.subtract(5, 2); // 3
 ```
 
-**Source Code Location**: `src/lib/helpers/api_builder/decisions.mjs` - `getFlatteningDecision()` function [Lines 87-189](../src/lib/helpers/api_builder/decisions.mjs#L87-L189)  
-**Git Commit**: `a50531d1ba712f0c4efd9ab9b7cf8f62a0d379da`  
-**Specific Condition**: See [C05](API-RULES-CONDITIONS.md#c05-filename-matches-container-category-level-flatten) in API-RULES-CONDITIONS.md
 **Technical Implementation**:
 
+- **Primary Condition**: [C05](API-RULES/API-RULES-CONDITIONS.md#c05) - `fileName === categoryName && !moduleHasDefault && moduleKeys.length > 0`
+- **Processing**: [C09b](API-RULES/API-RULES-CONDITIONS.md#c09b) - `flattenToCategory: true` → category-level flattening
+
 ```javascript
 // C05: Filename Matches Container (Category-Level Flatten)
-// Location: src/lib/helpers/api_builder/decisions.mjs Line 154
+// Location: src/lib/helpers/api_builder/decisions.mjs
 if (categoryName && fileName === categoryName && !moduleHasDefault && moduleKeys.length > 0) {
 	return {
 		shouldFlatten: true,
@@ -95,738 +127,586 @@ if (categoryName && fileName === categoryName && !moduleHasDefault && moduleKeys
 }
 ```
 
-**Processing Path**: Subfolder processing via `getFlatteningDecision()` (currentDepth > 0)
+**Processing Path**: Subfolder processing via `getFlatteningDecision()` (currentDepth > 0)  
+**Source Code Location**: `src/lib/helpers/api_builder/decisions.mjs` - `getFlatteningDecision()`
 
 ---
 
-### Rule 2: Named-Only Export Collection
+## Rule 2: Named-Only Export Collection
 
-**Status**: ✅ **VERIFIED**
+**Category**: Export Handling  
+**Status**: ✅ Verified (`api_tests/api_test`)  
+**User Guide**: [F04](API-RULES/API-FLATTENING.md#f04)  
+**Technical**: [C15, C09d](API-RULES/API-RULES-CONDITIONS.md#c15)
 
-**Condition**: Files with only named exports (no default export)
-**Source File**: `api_tests/api_test/config.mjs`
-**Actual Behavior**: Named export becomes object property accessible on API
+**Condition**: Directory contains files with only named exports (no default exports)  
+**Behavior**: All named exports collected and made accessible at the appropriate namespace level  
 
-**Verified Example**:
+**Verified Examples**:
 
 ```javascript
-// File: api_tests/api_test/config.mjs (named export only)
-export const config = {
-	host: "https://slothlet",
-	username: "admin",
-	password: "password",
-	site: "default",
-	secure: true,
-	verbose: true
-};
-
-// Result: Named-only export becomes API property
-api.config.host; // → "https://slothlet" ✅ VERIFIED
-api.config.username; // → "admin"
-api.config.secure; // → true
+// File: constants/values.mjs
+export const PI = 3.14159;
+export const E = 2.71828;
+
+// File: constants/messages.mjs
+export const SUCCESS = "Operation completed";
+export const ERROR = "Operation failed";
+
+api.constants.values.PI;          // 3.14159
+api.constants.values.E;           // 2.71828
+api.constants.messages.SUCCESS;   // "Operation completed"
+api.constants.messages.ERROR;     // "Operation failed"
 ```
 
-**Source Code Location**: `src/lib/helpers/api_builder/decisions.mjs` - `processModuleForAPI()` function [Lines 315-466](../src/lib/helpers/api_builder/decisions.mjs#L315-L466)  
-**Git Commit**: `a50531d1ba712f0c4efd9ab9b7cf8f62a0d379da`  
-**Specific Condition**: See [C09b](API-RULES-CONDITIONS.md#c09b-flatten-to-rootcategory) in API-RULES-CONDITIONS.md
 **Technical Implementation**:
 
-```javascript
-// When no default function detected, preserve as namespace (named exports become object)
-else {
-    // Traditional: preserve as namespace
-    apiAssignments[apiPathKey] = mod;
-    namespaced = true;
-}
-```
+- **Detection**: [C15](API-RULES/API-RULES-CONDITIONS.md#c15) - `defaultExportCount === 0`
+- **Processing**: [C09d](API-RULES/API-RULES-CONDITIONS.md#c09d) - Standard namespace preservation
+- **Strategy**: `processingStrategy = "named-only"` → category-level collection
 
-**Test Verification**:
+**Key Behavior**:
 
-```bash
-node tests/debug-slothlet.mjs
-# Look for: bound.config showing object with host, username, etc.
-# Confirms named-only exports become accessible object properties
-```
+- Preserves all named export names and values
+- Maintains clear namespace separation between files
+- No flattening when multiple named exports exist (prevents naming conflicts)
 
+**Source Code Location**: `src/lib/helpers/api_builder/decisions.mjs` - `processModuleForAPI()`  
 **Processing Path**: Both Root and Subfolder processing via `processModuleForAPI`
 
 ---
 
-### Rule 3: Empty Module Handling
+## Rule 3: Empty Module Handling
 
-**Status**: ✅ **VERIFIED**
+**Category**: Special Cases  
+**Status**: ✅ Verified  
+**Technical**: [C10](API-RULES/API-RULES-CONDITIONS.md#c10)
 
-**Condition**: Folders with no module files (`moduleFiles.length === 0`)
-**Source Code Location**: `src/slothlet.mjs` [Lines 318-319](../src/slothlet.mjs#L318-L319)  
-**Git Commit**: `a50531d1ba712f0c4efd9ab9b7cf8f62a0d379da`
-**Processing Path**: All paths (detected in `analyzeDirectoryStructure`)
+**Condition**: Directory contains no loadable module files  
+**Behavior**: Graceful handling - creates empty namespace  
+**Processing Path**: Early detection in `buildCategoryDecisions()`
 
-**Verified Example**:
+**Mode Differences**:
 
-```javascript
-// Empty folder: api_tests/api_test_empty_test/empty_folder/ (no .mjs files)
-// Condition: if (moduleFiles.length === 0) { processingStrategy = "empty"; }
+- **EAGER**: Empty folder → `{}` object (not callable)
+- **LAZY**: Empty folder → lazy proxy that resolves to `{}` when called
 
-// Result: Empty object created
-api.empty_folder; // → {} (empty object)
-typeof api.empty_folder; // → "object"
-JSON.stringify(api.empty_folder); // → "{}"
-```
+**Technical Implementation**:
 
-**Test Verification**:
+- **Detection**: [C10](API-RULES/API-RULES-CONDITIONS.md#c10) - `moduleFiles.length === 0`
+- **Strategy**: `processingStrategy = "empty"` → graceful empty handling
 
-```bash
-node tests/debug-slothlet.mjs
-# EAGER Mode: "Target is object, not function. Returning object directly." → bound.empty() {}
-# LAZY Mode:  "About to call function with args: []" → await bound.empty() {}
+```javascript
+// Detection in analyzeDirectoryStructure
+if (moduleFiles.length === 0) {
+	processingStrategy = "empty";
+}
 ```
 
-**Mode Differences**:
-
-- **EAGER**: Empty folder → `{}` object (not callable)
-- **LAZY**: Empty folder → lazy function that resolves to `{}` when called
-
-**Technical Details**:
-
-- **Detection**: `analyzeDirectoryStructure` in `src/lib/helpers/api_builder/analysis.mjs` detects empty directories
-- **Handling**: Empty `processedModules` and `subDirectories` arrays result in empty object
-- **API Result**: Empty folder becomes empty object property on API
-- **Implementation**: See `buildCategoryStructure()` in `src/lib/helpers/api_builder/construction.mjs`
+**Source Code Location**: `src/lib/helpers/api_builder/analysis.mjs`  
+**Processing Path**: All paths (detected in `analyzeDirectoryStructure`)
 
 ---
 
-### Rule 4: Default Export Container Pattern
+## Rule 4: Named Export with Function Name Preservation
 
-**Status**: ✅ **VERIFIED**
+**Category**: Export Handling  
+**Status**: ✅ Verified (`api_tests/api_test`)  
+**User Guide**: [F04](API-RULES/API-FLATTENING.md#f04)  
+**Technical**: [C16, C23](API-RULES/API-RULES-CONDITIONS.md#c16)
 
-**Condition**: When a module has a default export (function or object)
-**Behavior**: Default export becomes the container callable/content, named exports spread to same level
-**Source Code**: `processModuleForAPI()` in `src/lib/helpers/api_builder/decisions.mjs` [L315-466](../src/lib/helpers/api_builder/decisions.mjs#L315-L466)
-**Detailed Conditions**: See [C08 (Has Default Function Export)](API-RULES-CONDITIONS.md#c08-has-default-function-export) in API-RULES-CONDITIONS.md
-**Git Commit**: `a50531d1ba712f0c4efd9ab9b7cf8f62a0d379da`
+**Condition**: Named export with a function name that differs from the sanitized filename  
+**Behavior**: Preserves the original function name rather than using the filename-derived name  
+**Priority**: Function names take precedence over filename-based naming
 
-**Pattern A: Default Function + Named Exports**:
+**Verified Examples**:
 
 ```javascript
-// File: api_tests/api_test/root-function.mjs
-export default function greet(name) {
-	return `Hello, ${name}!`;
-}
-export function rootFunctionShout(name) {
-	return `HELLO, ${name.toUpperCase()}!`;
-}
-export function rootFunctionWhisper(name) {
-	return `hello, ${name.toLowerCase()}.`;
-}
+// File: auto-ip.mjs
+export function autoIP() { /* ... */ }
+api.autoIP(); // ✅ Function name preserved (not api.autoIp)
 
-// Result: Default becomes callable, named exports spread to same level
-api("World"); // → "Hello, World!" (default function)
-api.rootFunctionShout("World"); // → "HELLO, WORLD!" (named export)
-api.rootFunctionWhisper("World"); // → "hello, world." (named export)
+// File: json-parser.mjs
+export function parseJSON(data) { /* ... */ }
+api.parseJSON(data); // ✅ Original casing preserved (not api.jsonParser)
 ```
 
-**Pattern B: Default Object + Named Exports**:
+**Function Name Priority**:
 
-```javascript
-// File: api_tests/api_tv_test/manufacturer/lg/process.mjs
-export function processInboundData(data, meta = {}) {
-	return { processed: true, data: data, meta: meta };
-}
+1. Original function name (if available)
+2. Filename-based sanitization (if no function name)
 
-export default {
-	processInboundData
-};
+**Technical Implementation**:
 
-// Result: Default object contents spread, named exports spread to same level
-// Both default object contents AND named exports end up at container level:
-api.manufacturer.lg.processInboundData(); // (from default object)
-// If there were other named exports, they'd be here too
-```
+- **Detection**: [C16](API-RULES/API-RULES-CONDITIONS.md#c16) - Function name availability check
+- **Processing**: [C23](API-RULES/API-RULES-CONDITIONS.md#c23) - Function name takes precedence
 
-**Pattern C: Subfolder Default (Single File)**:
+---
 
-```javascript
-// File: api_tests/api_test/funcmod/funcmod.mjs
-export default function (name) {
-	return `Hello, ${name}!`;
-}
+## Rule 5: Multiple Module Default Export Handling
 
-// Result: Subfolder container becomes callable
-api.funcmod("World"); // → "Hello, World!" (default export becomes namespaced callable)
-```
+**Category**: Export Handling  
+**Status**: ✅ Verified (`api_tests/api_test`)  
+**Technical**: [C08, C09d](API-RULES/API-RULES-CONDITIONS.md#c08)
 
-**Technical Implementation**:
+**Condition**: Category contains multiple modules with default exports  
+**Behavior**: Each module maintains its own namespace with the default export accessible directly  
+**Processing Path**: Standard namespace preservation (no flattening)
 
-```javascript
-// C08c: Traditional Default Function - Root API
-// src/lib/helpers/api_builder/decisions.mjs Line 378
-if (mode === "root" && getRootDefault && setRootDefault && !hasMultipleDefaultExports && !getRootDefault()) {
-	// Root context: Make API itself callable
-	setRootDefault(defaultFunction);
-	rootDefaultSet = true;
-} else {
-	// C08d: Function As Namespace (Subfolder context)
-	// Line 384+
-	apiAssignments[apiPathKey] = mod;
-	namespaced = true;
-}
-```
+**Verified Examples**:
 
-**Test Verification**:
+```javascript
+// File: validators/email.mjs
+export default function validateEmail(email) { /* ... */ }
 
-```bash
-# Root container pattern
-node -e "const slothlet = await import('./index.mjs'); const api = await slothlet.default({ dir: './api_tests/api_test' }); console.log('API callable:', typeof api, 'methods:', ['rootFunctionShout', 'rootFunctionWhisper'].map(m => m + ': ' + typeof api[m]));"
+// File: validators/phone.mjs
+export default function validatePhone(phone) { /* ... */ }
 
-# Subfolder container pattern
-node -e "const slothlet = await import('./index.mjs'); const api = await slothlet.default({ dir: './api_tests/api_test' }); console.log('funcmod callable:', typeof api.funcmod, 'result:', api.funcmod('test'));"
+api.validators.email("test@example.com"); // ✅ Default function callable
+api.validators.phone("+1234567890");      // ✅ Default function callable
 ```
 
-**Processing Path**: Root processing (`mode === "root"`) vs Subfolder processing via `processModuleForAPI`
+**Technical Implementation**:
 
----
+- **Detection**: [C08](API-RULES/API-RULES-CONDITIONS.md#c08) - `moduleCount > 1 && defaultExportCount > 0`
+- **Processing**: [C09d](API-RULES/API-RULES-CONDITIONS.md#c09d) - Standard namespace preservation
+- **Strategy**: `processingStrategy = "standard"` → no flattening
 
-### Rule 5: Multi-Default Export Mixed Pattern
+**Key Behavior**:
 
-**Status**: ✅ **VERIFIED**
+- Maintains clear namespace separation between modules
+- Prevents naming conflicts where multiple defaults would collide
+- No automatic flattening when multiple defaults are present
 
-**Condition**: When a container has MULTIPLE files with default exports
-**Behavior**: Files with defaults become namespaces, files without defaults flatten to container level
-**Source Code**: `multidefault_getFlatteningDecision()` in `src/lib/helpers/multidefault.mjs` [L178-262](../src/lib/helpers/multidefault.mjs#L178-L262)
-**Detailed Conditions**: See [C28 (Multi-Default With Default Export)](API-RULES-CONDITIONS.md#c28-multi-default-with-default-export) and [C29 (Multi-Default Without Default Export)](API-RULES-CONDITIONS.md#c29-multi-default-without-default-export) in API-RULES-CONDITIONS.md
-**Git Commit**: `a50531d1ba712f0c4efd9ab9b7cf8f62a0d379da`
+---
 
-**Example: api_tv_test folder demonstrates both patterns**:
+## Rule 6: Multiple Module Mixed Exports
 
-**Files WITH default exports** become callable namespaces:
+**Category**: Special Cases  
+**Status**: ✅ Verified (`api_tests/api_test_mixed`)  
+**Technical**: [C14, C09d](API-RULES/API-RULES-CONDITIONS.md#c14)
 
-```javascript
-// Files: config.mjs, input.mjs, key.mjs, power.mjs, volume.mjs (all have default exports)
-api.config(); // → callable namespace
-api.input(); // → callable namespace + api.input.getAllInputNames(), api.input.getCurrentInput()
-api.key(); // → callable namespace + api.key.getAllKeyNames(), api.key.getKeyCode()
-api.power(); // → callable namespace (default only)
-api.volume(); // → callable namespace + api.volume.getPseudoMuteState(), etc.
-```
+**Condition**: Category contains modules with mixed export types (some default, some named-only)  
+**Behavior**: Standard namespace processing - each module maintains a distinct namespace  
+**Processing Path**: Conservative approach to prevent conflicts
 
-**Files WITHOUT default exports** flatten to container level:
+**Verified Examples**:
 
 ```javascript
-// Files: state.mjs, app.mjs, channel.mjs, connection.mjs (no default exports)
-// Their named exports flatten directly to root API:
-api.cloneState(); // from state.mjs
-api.emitLog(); // from state.mjs
-api.getAllApps(); // from app.mjs
-api.getCurrentApp(); // from app.mjs
-api.down(); // from channel.mjs
-api.getCurrentChannel(); // from channel.mjs
-api.connect(); // from connection.mjs
-api.disconnect(); // from connection.mjs
-```
-
-**Technical Implementation**:
+// File: mixed/calculator.mjs (default export)
+export default function calculate(operation, a, b) { /* ... */ }
 
-```javascript
-// C28: Multi-Default With Default Export
-// src/lib/helpers/multidefault.mjs Line 210-211
-if (hasMultipleDefaultExports) {
-	if (moduleHasDefault) {
-		return {
-			shouldFlatten: false,
-			preserveAsNamespace: true,
-			reason: "multi-default context with default export"
-		};
-	}
+// File: mixed/constants.mjs (named exports only)
+export const PI = 3.14159;
+export const E = 2.71828;
 
-	// C29: Multi-Default Without Default Export
-	// Line 219
-	else {
-		return {
-			shouldFlatten: true,
-			flattenToRoot: true,
-			reason: "multi-default context without default export"
-		};
-	}
-}
+api.mixed.calculator("add", 2, 3); // ✅ Default accessible
+api.mixed.constants.PI;            // ✅ Named exports accessible
+api.mixed.constants.E;             // ✅ Clear namespace separation
 ```
 
-**Test Verification**:
-
-```bash
-node -e "const slothlet = await import('./index.mjs'); const api = await slothlet.default({ dir: './api_tests/api_tv_test' }); console.log('Files WITH defaults (namespaced):', ['config', 'input', 'key', 'power', 'volume'].map(k => k + ': ' + typeof api[k])); console.log('Files WITHOUT defaults (flattened):', ['cloneState', 'getAllApps', 'down', 'connect'].map(k => k + ': ' + typeof api[k]));"
-```
+**Technical Implementation**:
 
-**Expected Result**: Shows namespaced callables for files with defaults, direct functions for flattened exports
-**Processing Path**: Multi-default analysis via `multidefault_analyzeModules()` and `multidefault_getFlatteningDecision()`
+- **Detection**: [C14](API-RULES/API-RULES-CONDITIONS.md#c14) - Mixed export types present
+- **Processing**: [C09d](API-RULES/API-RULES-CONDITIONS.md#c09d) - Conservative namespace preservation
 
 ---
 
-### Rule 6: Self-Referential Export Protection
+## Rule 7: Single Module Named Export Flattening
 
-**Status**: ✅ **VERIFIED** (api_tests/api_test)
+**Category**: Basic Flattening  
+**Status**: ✅ Verified (`api_tests/api_test`)  
+**User Guide**: [F02](API-RULES/API-FLATTENING.md#f02)  
+**Technical**: [C06, C09b](API-RULES/API-RULES-CONDITIONS.md#c06)
 
-**Condition**: When filename matches an exported property name (creates potential infinite nesting)
-**Behavior**: Always preserve as namespace to avoid `api.config.config.config...` infinite loops
-**Source Code Conditions**: [C01](API-RULES-CONDITIONS.md#c01-self-referential-check), [C08b](API-RULES-CONDITIONS.md#c08b-self-referential-function), [C09c](API-RULES-CONDITIONS.md#c09c-self-referential-non-function), [C20](API-RULES-CONDITIONS.md#c20-multi-file-self-referential), [C27](API-RULES-CONDITIONS.md#c27-multi-default-self-referential) (5 implementations)
-**Git Commit**: `a50531d1ba712f0c4efd9ab9b7cf8f62a0d379da`
+**Condition**: Category has one module file, module has named exports (no default export), filename ≠ category name  
+**Source Files**: `api_tests/api_test/config/settings.mjs`  
+**Implementation**: `getFlatteningDecision()` → single module named export flattening
 
 **Verified Examples**:
 
 ```javascript
-// Test File: api_tests/api_test/config.mjs (filename "config" matches export "config")
-export const config = {
-	host: "https://slothlet",
-	username: "admin",
-	site: "default"
-};
-
-// Expected: Self-referential protection prevents infinite nesting
-// Without protection: would create api.config.config.config.host (infinite nesting)
-// With protection: api.config.host (direct access, no infinite loop)
-api.config.host; // → "https://slothlet" ✅ VERIFIED
-// api.config.config → undefined ✅ VERIFIED (no infinite nesting created)
+// File: api_tests/api_test/config/settings.mjs
+export const DATABASE_URL = "mongodb://localhost:27017/testdb";
+export const API_PORT = 3000;
+export const DEBUG_MODE = true;
+
+// Without Rule 7: api.config.settings.DATABASE_URL  ❌ (unnecessary nesting)
+// With Rule 7:    api.config.DATABASE_URL            ✅ (clean flattening)
+api.config.DATABASE_URL; // "mongodb://localhost:27017/testdb"
+api.config.API_PORT;     // 3000
+api.config.DEBUG_MODE;   // true
 ```
 
-**Test Verification**:
+**Technical Implementation**:
 
-```bash
-node -e "const slothlet = await import('./index.mjs'); const api = await slothlet.default({ dir: './api_tests/api_test' }); console.log('api.config.host:', api.config.host); console.log('api.config.config exists:', 'config' in api.config);"
-# Expected output:
-# api.config.host: https://slothlet
-# api.config.config exists: false
-```
+- **Primary Condition**: [C06](API-RULES/API-RULES-CONDITIONS.md#c06) - `moduleCount === 1 && !moduleHasDefault && moduleKeys.length > 0`
+- **Processing**: [C09b](API-RULES/API-RULES-CONDITIONS.md#c09b) - `flattenToCategory: true`
 
-**Technical Implementation** (5 locations):
+---
 
-```javascript
-// C01: getFlatteningDecision() - decisions.mjs Line 105
-if (isSelfReferential) {
-	return {
-		shouldFlatten: false,
-		preserveAsNamespace: true,
-		reason: "self-referential export"
-	};
-}
+## Rule 8: Single Module Default Export Promotion
 
-// C08b: processModuleForAPI() function exports - decisions.mjs Line 361
-else if (isSelfReferential) {
-	apiAssignments[apiPathKey] = mod;
-	namespaced = true;
-}
+**Category**: Basic Flattening  
+**Status**: ✅ Verified (`api_tests/api_test`)  
+**User Guide**: [F03](API-RULES/API-FLATTENING.md#f03)  
+**Technical**: [C07, C09c](API-RULES/API-RULES-CONDITIONS.md#c07)
 
-// C09c: processModuleForAPI() non-function exports - decisions.mjs Line 440
-else if (isSelfReferential) {
-	apiAssignments[apiPathKey] = mod[apiPathKey] || mod;
-	namespaced = true;
-}
+**Condition**: Category has one module file with a default export  
+**Source Files**: `api_tests/api_test/logger.mjs`  
+**Implementation**: `getFlatteningDecision()` → single module default export promotion
 
-// C20: buildCategoryDecisions() multi-file - decisions.mjs Line 846
-else if (selfReferentialFiles.has(moduleName)) {
-	moduleDecision.type = "self-referential";
-}
+**Verified Examples**:
 
-// C27: multidefault_getFlatteningDecision() - multidefault.mjs Line 199
-if (isSelfReferential) {
-	return {
-		shouldFlatten: false,
-		preserveAsNamespace: true,
-		reason: "self-referential default export"
-	};
+```javascript
+// File: api_tests/api_test/logger.mjs
+export default function logger(message) {
+	console.log(`[LOG] ${message}`);
 }
+
+// Without Rule 8: api.logger.logger("Hello World")  ❌ (redundant nesting)
+// With Rule 8:    api.logger("Hello World")          ✅ (direct callable)
+api.logger("Hello World"); // [LOG] Hello World
+typeof api.logger;         // "function"
 ```
 
-**Test Verification**:
+**Callable Namespace Pattern**: When a folder contains a file matching the folder name with a default export (e.g. `logger/logger.mjs`), the default function becomes the namespace itself. Other files in the folder become properties on that function:
 
-```bash
-node tests/debug-slothlet.mjs
-# Look for: bound.config.host (not bound.config.config.host)
-# Confirms self-referential protection prevents infinite nesting
+```javascript
+// File: logger/logger.mjs → export default function log()
+// File: logger/utils.mjs  → named exports
+api.logger("message");       // calls the default function
+api.logger.utils.debug("x"); // other files remain as namespace properties
 ```
 
-**Processing Path**: All paths - Root, Subfolder, Multi-Default (implemented in 5 different functions)
+This pattern applies consistently at root level and category level.
+
+**Technical Implementation**:
+
+- **Primary Condition**: [C07](API-RULES/API-RULES-CONDITIONS.md#c07) - `moduleCount === 1 && moduleHasDefault`
+- **Processing**: [C09c](API-RULES/API-RULES-CONDITIONS.md#c09c) - `promoteToCategory: true`
 
 ---
 
-### Rule 7: Auto-Flattening Single Named Export
+## Rule 9: Function Name Preference Over Sanitization
 
-**Status**: ✅ **VERIFIED** (api_tests/api_test)
+**Category**: Special Cases  
+**Status**: ✅ Fully Verified (autoIP, parseJSON, getHTTPStatus, XMLParser)  
+**User Guide**: [API-RULES/API-FLATTENING.md - Name Preservation](API-RULES/API-FLATTENING.md)  
+**Technical**: [C16, C19](API-RULES/API-RULES-CONDITIONS.md#c16)
 
-**Condition**: Module exports single named export that matches sanitized filename
-**Behavior**: Use the export contents directly instead of wrapping in namespace
-**Source Code Conditions**: [C04](API-RULES-CONDITIONS.md#c04-auto-flatten-single-named-export-matching-filename), [C18](API-RULES-CONDITIONS.md#c18-single-named-export-match-secondary-check), [C21c](API-RULES-CONDITIONS.md#c21c-single-named-export-match), [C30](API-RULES-CONDITIONS.md#c30-single-named-export-match) (4 implementations)
-**Git Commit**: `a50531d1ba712f0c4efd9ab9b7cf8f62a0d379da`
+**Condition**: Exported function has an explicit name that differs from the sanitized filename  
+**Behavior**: Preserve the original function name over the filename-based API path  
 
 **Verified Examples**:
 
 ```javascript
-// Test File: api_tests/api_test/math/math.mjs (single export "math" matches filename "math")
-export const math = {
-	add: (a, b) => a + b,
-	multiply: (a, b) => a * b
-};
-
-// Expected: Auto-flattening eliminates double nesting
-// Without auto-flattening: api.math.math.add (double nesting)
-// With auto-flattening: api.math.add (direct access to math object contents)
-api.math.add(2, 3); // → 5 ✅ VERIFIED
-api.math.multiply(2, 3); // → 6 ✅ VERIFIED
-// api.math.math → undefined ✅ VERIFIED (no double nesting created)
-```
+// File: auto-ip.mjs
+export function autoIP() { /* Get automatic IP */ }
+// Sanitized filename: "autoIp"      ❌
+// Function name:      "autoIP"      ✅
 
-**Test Verification**:
+// File: get-http-status.mjs
+export function getHTTPStatus() { /* ... */ }
+// Sanitized filename: "getHttpStatus"   ❌
+// Function name:      "getHTTPStatus"   ✅
 
-```bash
-node -e "(async () => { const slothlet = await import('./index.mjs'); const api = await slothlet.default({ dir: './api_tests/api_test' }); console.log('math.add(2,3):', api.math.add(2, 3)); console.log('math.math exists:', 'math' in api.math); })()"
-# Expected output:
-# math.add(2,3): 5
-# math.math exists: false
+// File: parse-json.mjs
+export function parseJSON(data) { /* ... */ }
+// Sanitized filename: "parseJson"   ❌
+// Function name:      "parseJSON"   ✅
 ```
 
-**Technical Implementation** (4 locations):
+**Technical Implementation**:
+
+- **Primary Check**: [C16](API-RULES/API-RULES-CONDITIONS.md#c16) - `exportedFunctionName !== sanitizedName`
+- **Detailed Check**: [C19](API-RULES/API-RULES-CONDITIONS.md#c19) - `exportedFunction.name !== sanitizedFileName`
+- **Precedence**: Function name takes precedence over filename in API structure
+
+**Common Preserved Patterns**:
+
+- Technical acronyms: IP, HTTP, API, URL, JSON, XML, HTML
+- Protocol names: TCP, UDP, FTP, SSH, SSL, TLS
+- Format specs: JSON, XML, CSV, YAML, TOML
+- Industry standards: OAuth, JWT, REST, GraphQL
+
+---
+
+## Rule 10: Generic Filename Parent-Level Promotion
+
+**Category**: Special Cases  
+**Status**: ✅ Verified (`api_tests/api_test/nest4/singlefile.mjs`)  
+**User Guide**: [API-RULES/API-FLATTENING.md - Index File Pattern](API-RULES/API-FLATTENING.md)  
+**Technical**: [C17](API-RULES/API-RULES-CONDITIONS.md#c17)
+
+**Condition**: File has a generic name (`index`, `main`, `default`, etc.)  
+**Behavior**: Generic filename becomes transparent; content is promoted to the meaningful parent name  
+
+**Verified Examples**:
 
 ```javascript
-// C04: getFlatteningDecision() - decisions.mjs Line 142
-if (moduleKeys.length === 1 && moduleKeys[0] === apiPathKey) {
-	return {
-		shouldFlatten: true,
-		useAutoFlattening: true,
-		reason: "auto-flatten single named export matching filename"
-	};
-}
+// File: database/main.mjs
+export function connect() { /* ... */ }
+export function query() { /* ... */ }
 
-// C18: buildCategoryDecisions() - decisions.mjs Line 693
-if (moduleKeys.length === 1 && moduleKeys[0] === moduleName) {
-	return {
-		shouldFlatten: true,
-		flattenType: "object-auto-flatten"
-	};
-}
+// Without Rule 10: api.database.main.connect()  ❌ (generic 'main' adds no value)
+// With Rule 10:    api.database.connect()        ✅ (promoted to parent level)
 
-// C21c: buildCategoryDecisions() multi-file - decisions.mjs Line 867
-else if (moduleKeys.length === 1 && moduleKeys[0] === apiPathKey) {
-	moduleDecision.shouldFlatten = true;
-	moduleDecision.flattenType = "single-named-export-match";
-}
+// File: auth/index.mjs
+export function login() { /* ... */ }
+export function logout() { /* ... */ }
 
-// C30: multidefault_getFlatteningDecision() - multidefault.mjs Line 231
-if (moduleKeys.length === 1 && moduleKeys[0] === apiPathKey) {
-	return {
-		shouldFlatten: true,
-		flattenToRoot: false,
-		reason: "single named export matching filename"
-	};
-}
+// Without Rule 10: api.auth.index.login()  ❌ (generic 'index' is noise)
+// With Rule 10:    api.auth.login()        ✅ (clean parent-level promotion)
 ```
 
-**Test Verification**:
+**Technical Implementation**:
 
-```bash
-node tests/debug-slothlet.mjs
-# Look for: "bound.math.add(2, 3) 5" (not bound.math.math.add)
-# Confirms auto-flattening eliminates double nesting
-```
+- **Detection**: [C17](API-RULES/API-RULES-CONDITIONS.md#c17) - `isGenericFilename(fileName)`
+- **Promotion**: Content promoted to parent namespace; generic filename becomes invisible
 
-**Processing Path**: All processing contexts (General, Single-file, Multi-file, Multi-default)
+**Note**: Promotion is guarded against name collisions - checked against existing parent namespace properties before promoting.
 
 ---
 
-### Rule 8: Single-File Auto-Flattening Patterns
+## Rule 11: AddApi Special File Pattern
 
-**Status**: ✅ **VERIFIED**
+**Category**: AddApi  
+**Status**: ✅ Verified (`api_tests/api_smart_flatten_addapi`)  
+**User Guide**: [F06](API-RULES/API-FLATTENING.md#f06)  
+**Technical**: [C33](API-RULES/API-RULES-CONDITIONS.md#c33)
 
-**Condition**: Various patterns for eliminating unnecessary nesting in single-file folders
-**Behavior**: Multiple sub-patterns for flattening single files based on different criteria
-**Source Code Conditions**: C10, C11a/C11b/C11c, C13, C15 (buildCategoryStructure single-file logic)
-**Git Commit**: `a50531d1ba712f0c4efd9ab9b7cf8f62a0d379da`
+**Condition**: A file named `addapi.mjs` is loaded via `api.slothlet.api.add()`  
+**Behavior**: Exports are always flattened to the mount namespace regardless of other settings  
+**Processing Path**: Detection in `getFlatteningDecision()` (`src/lib/processors/flatten.mjs`); execution in `src/lib/builders/modes-processor.mjs`
 
-**Pattern A: Object Export Flattening** (C11a/C11b/C11c):
+**Verified Example**:
 
 ```javascript
-// File: api_tests/api_test/nested/date/date.mjs (filename matches object, exports object)
-export const date = {
-	today() {
-		return "2025-08-15";
-	}
-};
+// File: plugin-folder/addapi.mjs
+export function initializePlugin() { /* ... */ }
+export function cleanup() { /* ... */ }
+export function configure() { /* ... */ }
 
-// Result: Object contents promoted to folder level (date/date.mjs → api.nested.date)
-api.nested.date.today(); // → "2025-08-15" ✅ VERIFIED with api_tests/api_test
-```
+await api.slothlet.api.add("plugins", "./plugin-folder");
 
-```javascript
-// File: api_tests/api_test/math/math.mjs (filename matches object, exports object)
-export const math = {
-	add: (a, b) => a + b,
-	multiply: (a, b) => a * b
-};
-
-// Result: Object contents promoted to folder level (math/math.mjs → api.math)
-api.math.add(2, 3); // → 5 ✅ VERIFIED with api_tests/api_test
+// addapi.mjs exports are always flattened - never nested:
+api.plugins.initializePlugin(); // ✅
+api.plugins.cleanup();          // ✅
+api.plugins.configure();        // ✅
+// NOT: api.plugins.addapi.initializePlugin() ❌
 ```
 
-**Pattern B: Mixed Export Flattening** (C10):
+**Technical Implementation**:
 
 ```javascript
-// File: folder/folder.mjs (filename matches folder, exports mixed default+named)
-// Need to find example - no current test case available
-// ⚠️ PATTERN B NEEDS TEST CASE
+// C33: AddApi Special File Detection
+if (moduleKeys.includes("addapi")) {
+	const addapiModule = newModules["addapi"];
+	const otherModules = { ...newModules };
+	delete otherModules["addapi"];
+	modulesToMerge = { ...addapiModule, ...otherModules };
+}
 ```
 
-**Pattern C: Non-matching Object Export** (C13):
+**Use Cases**:
 
-```javascript
-// File: api_tests/api_test/singletest/helper.mjs (single file, object name ≠ filename)
-export const utilities = {
-	format(input) {
-		return `Formatted: ${input}`;
-	},
-	parse(value) {
-		return `Parsed: ${value}`;
-	}
-};
+- Plugin systems that extend the API at a known namespace
+- Hot-reloadable API extension points
+- Clean integration of external modules into a live API surface
 
-// Result: No auto-flattening, full nested path preserved
-api.singletest.helper.utilities.format("test"); // → "Formatted: test" ✅ VERIFIED (eager mode)
-// Note: Deep nested paths have known issues in lazy mode
-```
+---
 
-**Pattern D: Default Function Flattening** (C15):
+## Rule 12: Module Ownership and Selective API Overwriting
 
-```javascript
-// File: api_tests/api_test/funcmod/funcmod.mjs (default function in subfolder)
-export default function funcmod(name) {
-	return `Hello, ${name}!`;
-}
+**Category**: AddApi  
+**Status**: ✅ Implemented (`src/lib/handlers/ownership.mjs`)  
+**User Guide**: [F07](API-RULES/API-FLATTENING.md#f07)  
+**Technical**: [C19-C22](API-RULES/API-RULES-CONDITIONS.md#c19)
 
-// Result: Default function becomes folder callable (funcmod/funcmod.mjs → api.funcmod)
-api.funcmod("test"); // → "Hello, test!" ✅ VERIFIED with api_tests/api_test
-```
+**Purpose**: Track which module registered each API path, enabling safe hot-reloading and cross-module conflict protection.
 
-**Technical Implementation**:
+**Implementation**: Stack-based ownership system. Each API path maintains an independent ownership history stack. Removing a module automatically rolls back to the previous owner. Collision behavior is controlled by the `api.collision` configuration.
 
-```javascript
-// C10: Single-file function folder match - decisions.mjs Line 584
-if (moduleName === categoryName && typeof mod === "function" && currentDepth > 0) {
-	return {
-		shouldFlatten: true,
-		flattenType: "function-folder-match"
-	};
-}
+### Configuration
 
-// C12: Object auto-flatten - decisions.mjs Line 604-609
-if (moduleName === categoryName && mod && typeof mod === "object" && currentDepth > 0) {
-	if (moduleKeys.length === 1 && moduleKeys[0] === moduleName) {
-		return {
-			shouldFlatten: true,
-			flattenType: "object-auto-flatten"
-		};
+```javascript
+const api = await slothlet({
+	dir: "./api",
+	api: {
+		collision: {
+			initial: "merge",   // During initial API build
+			api: "replace"      // During api.slothlet.api.add()
+		}
 	}
-}
+});
+```
 
-// C15: Function name matches folder - decisions.mjs Line 663
-if (functionNameMatchesFolder && currentDepth > 0) {
-	return {
-		shouldFlatten: true,
-		flattenType: "function-folder-match",
-		preferredName: mod.name
-	};
-}
+### moduleId Tracking
 
-// C17: Default function export - decisions.mjs Line 680-682
-if (typeof mod === "function" && (!mod.name || mod.name === "default" || mod.__slothletDefault === true) && currentDepth > 0) {
-	return {
-		shouldFlatten: true,
-		flattenType: "default-function"
-	};
-}
-```
+Each `api.slothlet.api.add()` call accepts an optional `moduleId`. This is the key for ownership tracking:
 
-**Processing Path**: Single-file subfolder processing via `buildCategoryStructure()`
+```javascript
+// Module A registers plugins namespace
+await api.slothlet.api.add("plugins.moduleA", "./modules/moduleA", {}, {
+	moduleId: "moduleA"
+});
 
----
+// Module B registers in the same parent namespace
+await api.slothlet.api.add("plugins.moduleB", "./modules/moduleB", {}, {
+	moduleId: "moduleB"
+});
 
-### Rule 9: Function Name Preference Over Sanitization
+// Hot-reload Module A - ownership system allows this because moduleA owns these paths
+await api.slothlet.api.add("plugins.moduleA", "./modules/moduleA-v2", {}, {
+	moduleId: "moduleA",
+	forceOverwrite: true
+});
 
-**Status**: ✅ **VERIFIED**
+// Cross-module overwrite - blocked if collision mode is "error"
+await api.slothlet.api.add("plugins.moduleB", "./modules/other", {}, {
+	moduleId: "moduleA",        // moduleA does not own moduleB's paths
+	forceOverwrite: true        // Throws OWNERSHIP_CONFLICT in "error" mode
+});
+```
 
-**Condition**: Original function name semantically matches sanitized filename but has different casing
-**Behavior**: Use original function name instead of sanitized version to preserve conventions (IP, JSON, HTTP, etc.)
-**Source Code Conditions**: [C16](API-RULES-CONDITIONS.md#c16-function-name-matches-filename-name-preference), [C19](API-RULES-CONDITIONS.md#c19-multi-file-function-with-preferred-name) (function name preference logic)
-**Git Commit**: `a50531d1ba712f0c4efd9ab9b7cf8f62a0d379da`
+### Ownership Stack
 
-**Verified Examples**:
+Each API path has a history stack. When a module is removed, the previous owner is automatically restored:
 
 ```javascript
-// File: api_tests/api_test/task/auto-ip.mjs exports function "autoIP"
-// Sanitized filename: "autoIp", Function name: "autoIP"
-// Result: Use "autoIP" instead of "autoIp" (preserves IP capitalization)
-api.task.autoIP(); // → "testAutoIP" ✅ VERIFIED with api_tests/api_test
-
-// Note: Other examples (parseJSON, getHTTPStatus) mentioned in the rule
-// do not exist in current test files - need real test cases
-// ⚠️ Need additional test files for broader verification
+// Stack for "plugins.tools": [module-a, module-b]  (module-b is current owner)
+await api.slothlet.api.remove("module-b");
+// Stack restored to: [module-a]  (module-a is active again)
 ```
 
-**Technical Implementation**:
+### Collision Modes
 
-```javascript
-// C14: buildCategoryStructure() function name filename match - line 1049
-if (functionNameMatchesFilename) {
-	return { [mod.name]: mod }; // Use original function name
-}
+| Mode | Behavior |
+| ---- | -------- |
+| `"merge"` (default) | Preserve existing properties, add new ones |
+| `"merge-replace"` | Add new properties, overwrite existing |
+| `"replace"` | Completely replace the existing value |
+| `"skip"` | Keep existing value, silently ignore new |
+| `"warn"` | Keep existing value, log a warning |
+| `"error"` | Throw `OWNERSHIP_CONFLICT` error |
 
-// C16: Function name matches filename - decisions.mjs Line 671
-if (functionNameMatchesFilename) {
-	return {
-		shouldFlatten: false,
-		preferredName: mod.name
-	};
-}
+### forceOverwrite
 
-// C19: Multi-file function with preferred name - decisions.mjs Line 844
-if (hasPreferredName) {
-	return {
-		specialHandling: "preferred-export-names"
-	};
-}
+`forceOverwrite: true` requires an explicit `moduleId` and performs a complete replacement regardless of collision mode. Use for cases where a module must fully replace its own prior registration:
 
-// Function name preference logic checks:
-const functionNameLower = exportValue.name.toLowerCase();
-const filenameLower = fileName.toLowerCase();
-if (functionNameLower === filenameLower && exportValue.name !== apiPathKey) {
-	preferredKey = exportValue.name; // Use original function name
-}
+```javascript
+await api.slothlet.api.add("config", "./new-config", {}, {
+	moduleId: "config-v2",
+	forceOverwrite: true
+});
 ```
 
-**Test Verification**:
+**Source Code**: `src/lib/handlers/ownership.mjs`
 
-```bash
-node tests/debug-slothlet.mjs
-# Look for function names with preserved casing (autoIP, parseJSON, getHTTPStatus)
-# Confirms preference logic maintains programming conventions
-```
+---
 
-**Processing Path**: Both single-file and multi-file contexts via function name analysis
+## Rule 13: AddApi Path Deduplication Flattening
 
----
+> **New in v3**
 
-### Rule 10: Generic Filename Parent-Level Promotion
+**Category**: AddApi  
+**Status**: ✅ Implemented (`api_tests/smart_flatten/api_smart_flatten_folder_config`)  
+**User Guide**: [F08](API-RULES/API-FLATTENING.md#f08)  
+**Technical**: [C34](API-RULES/API-RULES-CONDITIONS.md#c34)
 
-**Status**: ✅ **VERIFIED**
+**Purpose**: When `api.slothlet.api.add("config", folder)` is called and the folder contains a subfolder whose name matches the last segment of the mount path (e.g. `config/config.mjs`), prevent double-nesting `api.config.config.*` by hoisting the subfolder's exports up to `api.config.*`.
 
-**Condition**: Single export with generic filename (singlefile, index, main, default) in subfolder
-**Behavior**: Promote export to parent level to eliminate meaningless intermediate namespace
-**Source Code Conditions**: [C14](API-RULES-CONDITIONS.md#c14-parent-level-flattening-generic-filenames) (parent-level flattening logic)
-**Git Commit**: `a50531d1ba712f0c4efd9ab9b7cf8f62a0d379da`
+**Condition**: After `buildAPI` returns `newApi`, if `newApi` contains a key equal to `lastPart` (last segment of `normalizedPath`) AND the matching value's `filePath` has its parent directory equal to `resolvedFolderPath/lastPart` (direct child check), hoist that key's own exports to the same level as the other keys in `newApi` and remove the duplicate key.
 
-**Verified Examples**:
+**Verified Example**:
 
 ```javascript
-// File: api_tests/api_test/advanced/nest4/singlefile.mjs (generic filename "singlefile")
-export function beta(name) {
-	return `Hello, ${name}!`;
-}
+// Folder structure: api_smart_flatten_folder_config/
+//   main.mjs          ← exports getRootInfo, setRootConfig
+//   config/
+//     config.mjs      ← exports getNestedConfig, setNestedConfig
 
-// Without promotion: api.advanced.nest4.singlefile.beta (meaningless "singlefile" namespace)
-// With promotion: api.advanced.nest4.beta (promoted to parent level)
-api.advanced.nest4.beta("test"); // → "Hello, test!" ✅ VERIFIED with api_tests/api_test
+await api.slothlet.api.add("config", "./api_smart_flatten_folder_config", {});
+
+// Without Rule 13 (double-nested):
+api.config.config.getNestedConfig(); // ❌
+
+// With Rule 13 (hoisted):
+api.config.getNestedConfig(); // ✅ subfolder exports promoted
+api.config.setNestedConfig(); // ✅
+api.config.main.getRootInfo(); // ✅ other files unaffected
 ```
 
-**Technical Implementation**:
+**Guard - `isDirectChild`**: Rule 13 only fires when the matching key's `filePath` is **directly** inside `resolvedFolderPath/lastPart`. This prevents false positives when a deeper nested folder coincidentally shares the mount-path name:
 
 ```javascript
-// C14: Parent-level flattening detection - decisions.mjs Line 641
-if (moduleFiles.length === 1 && currentDepth > 0 && mod && typeof mod === "object" && !Array.isArray(mod)) {
-	const isGenericFilename = ["singlefile", "index", "main", "default"].includes(fileName.toLowerCase());
-
-	// Line 649: Generic filename single export promotion
-	if (moduleKeys.length === 1 && isGenericFilename) {
-		return {
-			shouldFlatten: true,
-			flattenType: "parent-level-flatten"
-		};
-	}
-}
+// Should NOT hoist (services/services/services.mjs):
+// api.add("services", folder)  →  newApi has key "services"
+// but filePath = .../services/services/services.mjs
+//     dirname  = .../services/services   ≠ resolvedFolderPath/services
+// → Rule 13 does NOT fire
+// → api.services.services.getNestedService remains properly nested ✅
 ```
 
-**Generic Filenames**: `singlefile`, `index`, `main`, `default` (case-insensitive)
-
-**Test Verification**:
+**Implementation**: `src/lib/handlers/api-manager.mjs` - immediately after `buildAPI` call, before `setValueAtPath`
 
-```bash
-node tests/debug-slothlet.mjs
-# Look for: api.nest4.beta (not api.nest4.singlefile.beta)
-# Confirms generic filename elimination
-```
+---
 
-**Processing Path**: Single-file subfolder processing via `buildCategoryStructure()`
+## Verification Status
+
+| Rule | Title                                          | Status       | Test Source |
+| ---- | ---------------------------------------------- | ------------ | ----------- |
+| 1    | Filename Matches Container Flattening          | ✅ Verified  | `api_tests/api_test` |
+| 2    | Named-Only Export Collection                   | ✅ Verified  | `api_tests/api_test` |
+| 3    | Empty Module Handling                          | ✅ Verified  | debug testing |
+| 4    | Named Export with Function Name Preservation   | ✅ Verified  | `api_tests/api_test`, `api_tests/api_tv_test` |
+| 5    | Multiple Module Default Export Handling        | ✅ Verified  | `api_tests/api_tv_test` |
+| 6    | Multiple Module Mixed Exports                  | ✅ Verified  | `api_tests/api_test_mixed` |
+| 7    | Single Module Named Export Flattening          | ✅ Verified  | `api_tests/api_test` |
+| 8    | Single Module Default Export Promotion         | ✅ Verified  | Multiple test files |
+| 9    | Function Name Preference Over Sanitization     | ✅ Verified  | autoIP, parseJSON, getHTTPStatus, XMLParser |
+| 10   | Generic Filename Parent-Level Promotion        | ✅ Verified  | `api_tests/api_test/nest4/singlefile.mjs` |
+| 11   | AddApi Special File Pattern                    | ✅ Verified  | `api_tests/api_smart_flatten_addapi` |
+| 12   | Module Ownership and Selective API Overwriting | ✅ Verified  | `src/lib/handlers/ownership.mjs` |
+| 13   | AddApi Path Deduplication Flattening           | ✅ Verified  | `api_tests/smart_flatten/api_smart_flatten_folder_config` |
 
 ---
 
-## Source Code Conditions Cross-Reference
-
-### Source Code Condition Mapping to Rules
-
-| Condition | Location                        | Rule(s)   | Description                       |
-| --------- | ------------------------------- | --------- | --------------------------------- |
-| C01       | getFlatteningDecision:558       | Rule 6    | Self-referential check            |
-| C02       | getFlatteningDecision:570       | Rule 5    | Multi-default WITH default        |
-| C03       | getFlatteningDecision:580       | Rule 5    | Multi-default WITHOUT default     |
-| C04       | getFlatteningDecision:593       | Rule 7    | Auto-flatten single named export  |
-| C05       | getFlatteningDecision:605       | Rule 1    | Filename matches container        |
-| C07       | getFlatteningDecision:629       | Rule 2    | Default namespace preservation    |
-| C08a      | processModuleForAPI:716         | Rule 5    | Multi-default function handling   |
-| C08b      | processModuleForAPI:728         | Rule 6    | Self-referential function         |
-| C08c      | processModuleForAPI:748         | Rule 4    | Root function setting             |
-| C08d      | processModuleForAPI:758         | Rule 4    | Function as namespace             |
-| C09a      | processModuleForAPI:782         | Rule 7    | Apply auto-flattening             |
-| C09b      | processModuleForAPI:786         | Rules 1,5 | Flatten to root/category          |
-| C09c      | processModuleForAPI:797         | Rule 6    | Self-referential non-function     |
-| C09d      | processModuleForAPI:801         | Rule 2    | Traditional namespace             |
-| C10       | buildCategoryStructure:984      | Rule 8    | Single-file function folder match |
-| C11a      | buildCategoryStructure:1000     | Rules 7,8 | Single named export match         |
-| C11b      | buildCategoryStructure:1009     | Rule 8    | Multiple exports (default spread) |
-| C11c      | buildCategoryStructure:fallback | Rule 8    | Folder match fallback             |
-| C12       | buildCategoryStructure:1018     | Rule 10   | Parent-level flattening           |
-| C12a      | buildCategoryStructure:1026     | Rule 10   | Generic filename promotion        |
-| C13       | buildCategoryStructure:1039     | Rule 8    | Function name matches folder      |
-| C14       | buildCategoryStructure:1049     | Rule 9    | Function name matches filename    |
-| C15       | buildCategoryStructure:1053     | Rule 8    | Default function export           |
-| C16       | buildCategoryStructure:1063     | Rule 7    | Auto-flatten (second instance)    |
-| C18       | buildCategoryDecisions:1709     | Rule 9    | Preferred export names            |
-| C19       | buildCategoryDecisions:1712     | Rule 6    | Self-referential multi-file       |
-| C20a      | buildCategoryDecisions:1723     | Rule 4    | Single default object             |
-| C20b      | buildCategoryDecisions:1727     | Rule 5    | Multi-default no default          |
-| C20c      | buildCategoryDecisions:1731     | Rule 7    | Single named export match         |
-| C20d      | buildCategoryDecisions:1736     | Rule 1    | Category name match flatten       |
-| C20e      | buildCategoryDecisions:1740     | Rule 2    | Standard object export            |
-| C21       | multidefault:168                | Rule 6    | Multi-default self-referential    |
-| C22       | multidefault:179                | Rule 5    | Multi-default with default        |
-| C23       | multidefault:186                | Rule 5    | Multi-default without default     |
-| C24       | multidefault:200                | Rule 7    | Multi-default single named export |
-| C26       | multidefault:220+               | Rule 2    | Multi-default default fallback    |
-
-**Total Coverage**: 23 source code conditions mapped to 10 comprehensive rules
-
-> **Note**: Rule 11 conditions (C06, C17, C25) have been removed following architectural decision to eliminate single file context flattening. This preserves API path predictability and flexibility.
-
-## Source Code Locations
-
-**Note**: The slothlet API generation logic has been refactored into a modular structure:
-
-- **`src/lib/helpers/api_builder/decisions.mjs`** - Core decision logic (899 lines)
-  - `getFlatteningDecision()` [L87-189] - Controls flattening behavior
-  - `processModuleForAPI()` [L315-466] - Module processing logic
-  - `buildCategoryDecisions()` [L505-899] - Directory structure decisions
-
-- **`src/lib/helpers/api_builder/construction.mjs`** - API assembly (555 lines)
-  - `buildCategoryStructure()` [L125-555] - Structural construction
-
-- **`src/lib/helpers/multidefault.mjs`** - Multi-default handling (262 lines)
-  - `multidefault_getFlatteningDecision()` [L178-262] - Multi-default flattening logic
-
-**For complete documentation** of all 32 conditional statements with exact line numbers, see [API-RULES-CONDITIONS.md](API-RULES-CONDITIONS.md).
-
-## Test File Index
-
-_To be populated with confirmed examples from actual test files_
+## Cross-Reference Index
+
+### By Flattening Pattern (F##)
+
+| Flattening Pattern | API Rules | Technical Conditions |
+| ------------------ | --------- | -------------------- |
+| [F01](API-RULES/API-FLATTENING.md#f01) | Rule 1 | [C05, C09b, C11](API-RULES/API-RULES-CONDITIONS.md#c05) |
+| [F02](API-RULES/API-FLATTENING.md#f02) | Rule 8 (Pattern A) | [C12, C21a](API-RULES/API-RULES-CONDITIONS.md#c12) |
+| [F03](API-RULES/API-FLATTENING.md#f03) | Rule 7 | [C04, C09a, C18, C21c, C30](API-RULES/API-RULES-CONDITIONS.md#c04) |
+| [F04](API-RULES/API-FLATTENING.md#f04) | Rule 4, Rule 8 (Pattern B) | [C08c, C24](API-RULES/API-RULES-CONDITIONS.md#c08c) |
+| [F05](API-RULES/API-FLATTENING.md#f05) | Rule 4, Rule 8 (Pattern C) | [C08c, C11](API-RULES/API-RULES-CONDITIONS.md#c08c) |
+| [F06](API-RULES/API-FLATTENING.md#f06) | Rule 11 | [C33](API-RULES/API-RULES-CONDITIONS.md#c33) |
+| [F07](API-RULES/API-FLATTENING.md#f07) | Rule 12 | [C19-C22](API-RULES/API-RULES-CONDITIONS.md#c19) |
+| [F08](API-RULES/API-FLATTENING.md#f08) | Rule 13 | [C34](API-RULES/API-RULES-CONDITIONS.md#c34) |
+
+### By Technical Condition (C##)
+
+| Condition | API Rules | Flattening Patterns |
+| --------- | --------- | ------------------- |
+| [C01-C07](API-RULES/API-RULES-CONDITIONS.md#c01) | Rules 1, 6, 7, 8 | F01, F03 |
+| [C08-C09d](API-RULES/API-RULES-CONDITIONS.md#c08) | Rules 4, 6, 7 | F04, F05 |
+| [C10-C21d](API-RULES/API-RULES-CONDITIONS.md#c10) | Rules 1, 2, 3, 5, 7, 8, 9, 10 | F01, F02, F03 |
+| [C22-C26](API-RULES/API-RULES-CONDITIONS.md#c22) | Rules 4, 6 | F04, F05 |
+| [C27-C32](API-RULES/API-RULES-CONDITIONS.md#c27) | Rules 5, 6, 7 | Multi-default scenarios |
+| [C33](API-RULES/API-RULES-CONDITIONS.md#c33) | Rule 11 | F06 |
+| [C34](API-RULES/API-RULES-CONDITIONS.md#c34) | Rule 13 | F08 |
+
+### By Processing Context
+
+| Context | Rules | Primary Conditions |
+| ------- | ----- | ------------------ |
+| **Single-File Directories** | 1, 7, 8, 10 | C11, C12, C04, C17 |
+| **Multi-File Directories** | 1, 2, 5, 7, 9 | C13, C15, C21a-d, C16, C19 |
+| **Multi-Default Scenarios** | 5, 6, 7 | C02, C03, C27-C32 |
+| **AddApi Operations** | 11, 12, 13 | C33, C34, C19-C22 |
+| **Root-Level Processing** | 4, 8, 10 | C08c, C22, C17 |
+| **Subfolder Processing** | 4, 6, 8 | C08d, C20, C24 |