@cldmv/slothlet 2.9.0 → 2.11.0

package/docs/API-RULES.md

@@ -1,85 +1,121 @@
-# Slothlet API Rules - Verified Documentation
+# Slothlet API Rules - Comprehensive Documentation (v2)
 
-> **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 with Cross-Referenced Implementation Details**
 
-## Methodology
+- **Version**: 2.0
+- **Date**: January 3, 2026
+- **Purpose**: Maintainer and contributor guide documenting all API generation rules with verified examples and technical cross-references
+- **Status**: ✅ **VERIFIED AND CURRENT**
 
-Each rule documents:
+---
+
+## Document Hierarchy
+
+This is the **middle layer** of slothlet's three-tier documentation system:
+
+```text
+📋 API-FLATTENING-v2.md (F##)     ← User Guide: Clear examples and flowcharts
+     ↑ links to                    ↓ links to
+📊 API-RULES-v2.md (1-12)         ← YOU ARE HERE: Complete behavior catalog
+     ↑ links to                    ↓ links to
+🔧 API-RULES-CONDITIONS-v2.md     ← Technical: Exact source code locations
+```
+
+**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-FLATTENING-v2.md](API-FLATTENING-v2.md) for user-friendly explanations with examples
+- **⬇️ For Developers**: See [API-RULES-CONDITIONS-v2.md](API-RULES-CONDITIONS-v2.md) for exact source code locations
 
 ---
 
-## Verification Progress
+## Overview
+
+This document catalogs **all 12 API generation behaviors** in slothlet with:
+
+- **Verified examples** from actual test files with source attribution
+- **Cross-references** to user guide ([F##](API-FLATTENING-v2.md)) and technical details ([C##](API-RULES-CONDITIONS-v2.md))
+- **Source code locations** with function names and file references
+- **Test file sources** demonstrating each behavior in action
+- **Processing contexts** (Root/Subfolder/Multi-Default/AddApi)
 
-- [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)
+**Why 12 Rules vs 7 Flattening Patterns?**
 
-> **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.
+The [FLATTENING guide](API-FLATTENING-v2.md) focuses on **when content gets promoted/flattened** (7 patterns). 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, 12): Map to F01-F07 patterns
+- **Non-Flattening Rules** (2, 3, 4, 5, 6, 9): Export collection, function naming, empty modules, mixed exports, self-referential protection
+
+**Methodology**: Each rule has been systematically verified against test files and source code to ensure accuracy.
 
 ---
 
-## Verified Rules
+## Rule Categories
+
+| Category              | Rules       | Focus                      | Cross-References                                                        |
+| --------------------- | ----------- | -------------------------- | ----------------------------------------------------------------------- |
+| **Basic Flattening**  | 1, 7, 8     | Core flattening patterns   | [F01-F05](API-FLATTENING-v2.md) → [C01-C11](API-RULES-CONDITIONS-v2.md) |
+| **Export Handling**   | 2, 4, 5     | Default vs Named exports   | [F04-F05](API-FLATTENING-v2.md) → [C08-C21](API-RULES-CONDITIONS-v2.md) |
+| **Special Cases**     | 3, 6, 9, 10 | Edge cases and protections | → [C10, C01, C16-C19](API-RULES-CONDITIONS-v2.md)                       |
+| **AddApi Extensions** | 11, 12      | Runtime API extensions     | [F06-F07](API-FLATTENING-v2.md) → [C33](API-RULES-CONDITIONS-v2.md)     |
+
+---
+
+## 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. [Verification Status](#verification-status)
+14. [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**: [FLATTENING F01](API-FLATTENING-v2.md#f01-folder-file-name-matching)  
+**Technical**: [CONDITIONS C05, C09b](API-RULES-CONDITIONS-v2.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)
-```
+// File: api_tests/api_test/math/math.mjs
+export function add(a, b) {
+	return a + b;
+}
+export function subtract(a, b) {
+	return a - b;
+}
 
-**Test Verification**:
+// Expected API Structure:
+api.math.add(2, 3); // ✅ 5 - Flattened (no math.math.add)
+api.math.subtract(5, 2); // ✅ 3 - Direct access to folder level
 
-```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)
 ```
 
-**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-CONDITIONS-v2.md#c05) - `fileName === categoryName && !moduleHasDefault && moduleKeys.length > 0`
+- **Processing**: [C09b](API-RULES-CONDITIONS-v2.md#c09b) - `flattenToCategory: true` → category-level flattening
+
+**Complete Source Code Implementation**:
+
 ```javascript
 // C05: Filename Matches Container (Category-Level Flatten)
 // Location: src/lib/helpers/api_builder/decisions.mjs Line 154
@@ -95,42 +131,62 @@ 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()` function [Lines 87-189]  
+**Git Commit Reference**: `a50531d1ba712f0c4efd9ab9b7cf8f62a0d379da`
+
+**Test Verification**:
+
+```bash
+# Comprehensive verification command
+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)
+
+# Quick verification command
+node -e "(async () => { const api = await (await import('./index.mjs')).default({ dir: './api_tests/api_test' }); console.log('math.add:', api.math.add(2,3)); console.log('math.math exists:', 'math' in api.math); })()"
+# Expected: math.add: 5, math.math exists: false
+```
 
 ---
 
-### 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**: [FLATTENING Pattern D](API-FLATTENING-v2.md#examples) (covered in examples)  
+**Technical**: [CONDITIONS C15, C09d](API-RULES-CONDITIONS-v2.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 appropriate namespace level  
+**Source Files**: Multiple test files with named-only exports
 
-**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";
+
+// Expected API Structure:
+api.constants.values.PI; // ✅ 3.14159 - Named exports preserved
+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**:
 
+- **Detection**: [C15](API-RULES-CONDITIONS-v2.md#c15) - `defaultExportCount === 0`
+- **Processing**: [C09d](API-RULES-CONDITIONS-v2.md#c09d) - Standard namespace preservation
+- **Strategy**: `processingStrategy = "named-only"` → category-level collection
+
+**Complete Source Code Implementation**:
+
 ```javascript
 // When no default function detected, preserve as namespace (named exports become object)
 else {
@@ -140,693 +196,665 @@ else {
 }
 ```
 
+**Source Code Location**: `src/lib/helpers/api_builder/decisions.mjs` - `processModuleForAPI()` function [Lines 315-466]  
+**Git Commit Reference**: `a50531d1ba712f0c4efd9ab9b7cf8f62a0d379da`  
+**Processing Path**: Both Root and Subfolder processing via `processModuleForAPI`
+
 **Test Verification**:
 
 ```bash
+# Comprehensive verification
 node tests/debug-slothlet.mjs
 # Look for: bound.config showing object with host, username, etc.
 # Confirms named-only exports become accessible object properties
+
+# Quick verification
+node -e "(async () => { const api = await (await import('./index.mjs')).default({ dir: './api_tests/api_test' }); console.log('config.host:', api.config.host); console.log('config object keys:', Object.keys(api.config)); })();"
+# Expected: config.host: https://slothlet, config object keys: [host, username, password, site, secure, verbose]
 ```
 
-**Processing Path**: Both Root and Subfolder processing via `processModuleForAPI`
+**Key Behavior**:
+
+- ✅ Preserves all named export names and values
+- ✅ Maintains clear namespace separation between files
+- ✅ No unwanted flattening of complex named export structures
+- ❌ Does not flatten when multiple named exports exist (prevents naming conflicts)
 
 ---
 
-### Rule 3: Empty Module Handling
+## Rule 3: Empty Module Handling
 
-**Status**: ✅ **VERIFIED**
+**Category**: Special Cases  
+**Status**: ✅ **VERIFIED** (debug testing)  
+**User Guide**: Not applicable (internal edge case)  
+**Technical**: [CONDITIONS C10](API-RULES-CONDITIONS-v2.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 with appropriate warnings or empty namespace creation  
+**Processing Path**: Early detection in `buildCategoryDecisions()`
+
+**Technical Implementation**:
 
-**Verified Example**:
+- **Detection**: [C10](API-RULES-CONDITIONS-v2.md#c10) - `moduleFiles.length === 0`
+- **Strategy**: `processingStrategy = "empty"` → graceful empty handling
+- **Result**: May create empty namespace or skip directory entirely
 
-```javascript
-// Empty folder: api_tests/api_test_empty_test/empty_folder/ (no .mjs files)
-// Condition: if (moduleFiles.length === 0) { processingStrategy = "empty"; }
+**Complete Source Code Implementation**:
 
-// Result: Empty object created
-api.empty_folder; // → {} (empty object)
-typeof api.empty_folder; // → "object"
-JSON.stringify(api.empty_folder); // → "{}"
+```javascript
+// Detection in analyzeDirectoryStructure
+if (moduleFiles.length === 0) {
+	processingStrategy = "empty";
+	// Handle gracefully - may create empty namespace or skip
+}
 ```
 
+**Source Code Location**: `src/slothlet.mjs` [Lines 318-319] and `src/lib/helpers/api_builder/analysis.mjs`  
+**Git Commit Reference**: `a50531d1ba712f0c4efd9ab9b7cf8f62a0d379da`  
+**Processing Path**: All paths (detected in `analyzeDirectoryStructure`)
+
+**Mode Differences**:
+
+- **EAGER**: Empty folder → `{}` object (not callable)
+- **LAZY**: Empty folder → lazy function that resolves to `{}` when called
+
 **Test Verification**:
 
 ```bash
+# Test empty folder behavior
 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() {}
-```
 
-**Mode Differences**:
-
-- **EAGER**: Empty folder → `{}` object (not callable)
-- **LAZY**: Empty folder → lazy function that resolves to `{}` when called
-
-**Technical Details**:
+# Quick verification
+node -e "(async () => { const api = await (await import('./index.mjs')).default({ dir: './api_tests/api_test' }); console.log('empty_folder type:', typeof api.empty_folder); console.log('empty_folder content:', JSON.stringify(api.empty_folder)); })();"
+# Expected: empty_folder type: object, empty_folder content: {}
+```
 
-- **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`
+- **Detection**: [C10](API-RULES-CONDITIONS-v2.md#c10) - `moduleFiles.length === 0`
+- **Strategy**: `processingStrategy = "empty"` → graceful empty handling
+- **Result**: May create empty namespace or skip directory entirely
 
 ---
 
-### 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**: [FLATTENING F04](API-FLATTENING-v2.md#f04-named-export-function-names)  
+**Technical**: [CONDITIONS C16, C23](API-RULES-CONDITIONS-v2.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 function name that differs from filename  
+**Behavior**: Preserves original function name rather than using filename  
+**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()}!`;
+// File: auto-ip.mjs
+export function autoIP(interface) {
+	/* ... */
 }
-export function rootFunctionWhisper(name) {
-	return `hello, ${name.toLowerCase()}.`;
+
+// Expected API Structure:
+api.autoIP(); // ✅ Function name preserved (not api.autoIp)
+// Named function takes precedence over filename sanitization
+
+// File: json-parser.mjs
+export function parseJSON(data) {
+	/* ... */
 }
 
-// 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)
+// Expected API Structure:
+api.parseJSON(data); // ✅ Original casing preserved
+// Function name "parseJSON" wins over "jsonParser" from filename
 ```
 
-**Pattern B: Default Object + Named Exports**:
+**Technical Implementation**:
 
-```javascript
-// File: api_tests/api_tv_test/manufacturer/lg/process.mjs
-export function processInboundData(data, meta = {}) {
-	return { processed: true, data: data, meta: meta };
-}
+- **Detection**: [C16](API-RULES-CONDITIONS-v2.md#c16) - Function name availability check
+- **Processing**: [C23](API-RULES-CONDITIONS-v2.md#c23) - Function name takes precedence
+- **Strategy**: Original function name preserved over filename-based sanitization
 
-export default {
-	processInboundData
-};
+**Function Name Priority**:
 
-// 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
-```
+1. ✅ **Original function name** (if available)
+2. ✅ Filename-based sanitization (if no function name)
+3. ❌ Never modify existing function names
+
+---
 
-**Pattern C: Subfolder Default (Single File)**:
+## Rule 5: Multiple Module Default Export Handling
 
-```javascript
-// File: api_tests/api_test/funcmod/funcmod.mjs
-export default function (name) {
-	return `Hello, ${name}!`;
-}
+**Category**: Export Handling  
+**Status**: ✅ **VERIFIED** (api_tests/api_test)  
+**User Guide**: Not explicitly covered (standard behavior)  
+**Technical**: [CONDITIONS C08, C09d](API-RULES-CONDITIONS-v2.md#c08)
 
-// Result: Subfolder container becomes callable
-api.funcmod("World"); // → "Hello, World!" (default export becomes namespaced callable)
-```
+**Condition**: Category contains multiple modules with default exports  
+**Behavior**: Each module maintains its own namespace with default export accessible  
+**Processing Path**: Standard namespace preservation (no flattening)
 
-**Technical Implementation**:
+**Verified Examples**:
 
 ```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;
-}
-```
+// File: validators/email.mjs
+export default function validateEmail(email) { /* ... */ }
 
-**Test Verification**:
+// File: validators/phone.mjs
+export default function validatePhone(phone) { /* ... */ }
 
-```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]));"
+// Expected API Structure:
+api.validators.email("test@example.com"); // ✅ Default function accessible
+api.validators.phone("+1234567890");      // ✅ Default function accessible
 
-# 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'));"
+// No flattening occurs due to multiple modules
 ```
 
-**Processing Path**: Root processing (`mode === "root"`) vs Subfolder processing via `processModuleForAPI`
+**Technical Implementation**:
 
----
+- **Detection**: [C08](API-RULES-CONDITIONS-v2.md#c08) - `moduleCount > 1 && defaultExportCount > 0`
+- **Processing**: [C09d](API-RULES-CONDITIONS-v2.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
+- ✅ Prevents naming conflicts between modules
+- ❌ No automatic flattening (safer with multiple defaults)
 
-**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)  
+**User Guide**: Not explicitly covered (complex behavior)  
+**Technical**: [CONDITIONS C14, C09d](API-RULES-CONDITIONS-v2.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 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"
-		};
-	}
-}
+// Expected API Structure:
+api.mixed.calculator("add", 2, 3); // ✅ Default accessible
+api.mixed.constants.PI; // ✅ Named exports accessible
+api.mixed.constants.E; // ✅ Clear namespace separation
 ```
 
-**Test Verification**:
+**Technical Implementation**:
 
-```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]));"
-```
+- **Detection**: [C14](API-RULES-CONDITIONS-v2.md#c14) - Mixed export types present
+- **Processing**: [C09d](API-RULES-CONDITIONS-v2.md#c09d) - Conservative namespace preservation
+- **Strategy**: Prevents complex flattening that could cause conflicts
+
+**Safety Priority**:
 
-**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()`
+- ✅ Predictable structure over aggressive flattening
+- ✅ Clear namespace boundaries
+- ❌ No automatic merging of different export types
 
 ---
 
-### 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**: [FLATTENING F02](API-FLATTENING-v2.md#f02-single-module-named-exports)  
+**Technical**: [CONDITIONS C06, C09b](API-RULES-CONDITIONS-v2.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;
+
+// Expected API Structure:
+api.config.DATABASE_URL; // ✅ "mongodb://localhost:27017/testdb" - Flattened
+api.config.API_PORT; // ✅ 3000 - Direct access to category level
+api.config.DEBUG_MODE; // ✅ true - No settings.DATABASE_URL nesting
+
+// Without Rule 7: api.config.settings.DATABASE_URL ❌ (unnecessary nesting)
+// With Rule 7: api.config.DATABASE_URL ✅ (clean flattening)
 ```
 
+**Technical Implementation**:
+
+- **Primary Condition**: [C06](API-RULES-CONDITIONS-v2.md#c06) - `moduleCount === 1 && !moduleHasDefault && moduleKeys.length > 0`
+- **Processing**: [C09b](API-RULES-CONDITIONS-v2.md#c09b) - `flattenToCategory: true` → category-level flattening
+
 **Test Verification**:
 
 ```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
+node -e "(async () => { const api = await (await import('./index.mjs')).default({ dir: './api_tests/api_test' }); console.log('config.DATABASE_URL:', api.config.DATABASE_URL); console.log('config.settings exists:', 'settings' in api.config); })()"
+# Expected: config.DATABASE_URL: mongodb://localhost:27017/testdb, config.settings exists: false
 ```
 
-**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**: [FLATTENING F03](API-FLATTENING-v2.md#f03-single-module-default-export)  
+**Technical**: [CONDITIONS C07, C09c](API-RULES-CONDITIONS-v2.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}`);
 }
+
+// Expected API Structure:
+api.logger("Hello World"); // ✅ [LOG] Hello World - Direct callable
+// Without Rule 8: api.logger.logger("Hello World") ❌ (redundant nesting)
+// With Rule 8: api.logger("Hello World") ✅ (clean promotion)
 ```
 
+**Technical Implementation**:
+
+- **Primary Condition**: [C07](API-RULES-CONDITIONS-v2.md#c07) - `moduleCount === 1 && moduleHasDefault`
+- **Processing**: [C09c](API-RULES-CONDITIONS-v2.md#c09c) - `promoteToCategory: true` → category becomes callable
+
 **Test Verification**:
 
 ```bash
-node tests/debug-slothlet.mjs
-# Look for: bound.config.host (not bound.config.config.host)
-# Confirms self-referential protection prevents infinite nesting
+node -e "(async () => { const api = await (await import('./index.mjs')).default({ dir: './api_tests/api_test' }); api.logger('test message'); console.log('logger type:', typeof api.logger); })()"
+# Expected: [LOG] test message, logger type: function
 ```
 
-**Processing Path**: All paths - Root, Subfolder, Multi-Default (implemented in 5 different functions)
-
 ---
 
-### 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** (Multiple examples verified: autoIP, parseJSON, getHTTPStatus, XMLParser)  
+**User Guide**: [FLATTENING Name Preservation](API-FLATTENING-v2.md#benefits) (covered in intuitive organization)  
+**Technical**: [CONDITIONS C16, C19](API-RULES-CONDITIONS-v2.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 explicit name that differs from sanitized filename  
+**Behavior**: Preserve original function name over filename-based API path  
+**Source Files**: Test cases with technical function names
 
 **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)
-```
+**Example A: Technical Abbreviations**
 
-**Test Verification**:
+```javascript
+// File: auto-ip.mjs
+export function autoIP() {
+	/* Get automatic IP */
+}
 
-```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
+// Without Rule 9: api.autoIp() ❌ (sanitized filename)
+// With Rule 9: api.autoIP() ✅ (preserves technical abbreviation)
 ```
 
-**Technical Implementation** (4 locations):
+**Example B: Protocol Names**
 
 ```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: get-http-status.mjs
+export function getHTTPStatus() {
+	/* HTTP status logic */
 }
 
-// C18: buildCategoryDecisions() - decisions.mjs Line 693
-if (moduleKeys.length === 1 && moduleKeys[0] === moduleName) {
-	return {
-		shouldFlatten: true,
-		flattenType: "object-auto-flatten"
-	};
-}
+// Without Rule 9: api.getHttpStatus() ❌ (loses HTTP casing)
+// With Rule 9: api.getHTTPStatus() ✅ (preserves protocol name)
+```
 
-// 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";
-}
+**Example C: Data Format Names**
 
-// 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"
-	};
+```javascript
+// File: parse-json.mjs
+export function parseJSON(data) {
+	/* JSON parsing */
 }
+
+// Without Rule 9: api.parseJson() ❌ (generic casing)
+// With Rule 9: api.parseJSON() ✅ (preserves JSON format name)
 ```
 
-**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
-```
+- **Primary Check**: [C16](API-RULES-CONDITIONS-v2.md#c16) - `exportedFunctionName !== sanitizedName`
+- **Detailed Check**: [C19](API-RULES-CONDITIONS-v2.md#c19) - `exportedFunction.name !== sanitizedFileName`
+- **Precedence**: Function name takes precedence over filename in API structure
 
-**Processing Path**: All processing contexts (General, Single-file, Multi-file, Multi-default)
+**Semantic Value Preservation**:
+
+- ✅ **Technical Acronyms**: IP, HTTP, API, URL, JSON, XML, HTML
+- ✅ **Protocol Names**: TCP, UDP, FTP, SSH, SSL, TLS
+- ✅ **Format Specifications**: JSON, XML, CSV, YAML, TOML
+- ✅ **Industry Standards**: OAuth, JWT, REST, GraphQL
+- ✅ **Camel Case Precision**: Exact developer intent preserved
 
 ---
 
-### Rule 8: Single-File Auto-Flattening Patterns
+## Rule 10: Generic Filename Parent-Level Promotion
 
-**Status**: ✅ **VERIFIED**
+**Category**: Special Cases  
+**Status**: ✅ **VERIFIED** (nest4/singlefile.mjs example verified with api_tests/api_test)  
+**User Guide**: [FLATTENING Transparent Naming](API-FLATTENING-v2.md#f02-index-file-pattern) (similar to index pattern)  
+**Technical**: [CONDITIONS C17](API-RULES-CONDITIONS-v2.md#c17)
 
-**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**: Files with generic names (index, main, default, etc.) get promoted to parent level  
+**Behavior**: Generic filenames become transparent, content promoted to meaningful parent name  
+**Source Files**: `api_tests/api_test/nest4/singlefile.mjs`
 
-**Pattern A: Object Export Flattening** (C11a/C11b/C11c):
+**Verified Examples**:
 
 ```javascript
-// File: api_tests/api_test/nested/date/date.mjs (filename matches object, exports object)
-export const date = {
-	today() {
-		return "2025-08-15";
-	}
-};
+// File: database/main.mjs
+export function connect() {
+	/* ... */
+}
+export function query() {
+	/* ... */
+}
 
-// 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
-```
+// Without Rule 10: api.database.main.connect() ❌ (generic 'main' adds no value)
+// With Rule 10: api.database.connect() ✅ (promoted to meaningful parent level)
 
-```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
+// File: auth/index.mjs
+export function login() {
+	/* ... */
+}
+export function logout() {
+	/* ... */
+}
+
+// Without Rule 10: api.auth.index.login() ❌ (generic 'index' is noise)
+// With Rule 10: api.auth.login() ✅ (clean parent-level promotion)
 ```
 
-**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
-```
+- **Detection**: [C17](API-RULES-CONDITIONS-v2.md#c17) - `isGenericFilename(fileName)`
+- **Promotion**: Content promoted to parent namespace
+- **Transparency**: Generic filename becomes invisible in API structure
 
-**Pattern C: Non-matching Object Export** (C13):
+**Promotion Logic**:
 
-```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}`;
-	}
-};
+- ✅ **Meaningful Parent**: Generic content promoted to semantically meaningful parent directory name
+- ✅ **Noise Reduction**: Eliminates generic names that add no semantic value
+- ✅ **Developer Intent**: Preserves intended API structure without implementation details
+- ❌ **Name Collision Risk**: Checked against existing parent namespace properties
 
-// 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 11: AddApi Special File Pattern
 
-```javascript
-// File: api_tests/api_test/funcmod/funcmod.mjs (default function in subfolder)
-export default function funcmod(name) {
-	return `Hello, ${name}!`;
-}
+**Category**: AddApi  
+**Status**: ✅ **VERIFIED** (api_tests/api_smart_flatten_addapi)  
+**User Guide**: [FLATTENING F06](API-FLATTENING-v2.md#f06-addapi-special-file-pattern)  
+**Technical**: [CONDITIONS C33](API-RULES-CONDITIONS-v2.md#c33)
 
-// Result: Default function becomes folder callable (funcmod/funcmod.mjs → api.funcmod)
-api.funcmod("test"); // → "Hello, test!" ✅ VERIFIED with api_tests/api_test
-```
+**Condition**: Files named `addapi.mjs` loaded via `addApi()` method  
+**Behavior**: Always flatten regardless of `autoFlatten` setting - designed for API extensions  
+**Processing Path**: Special case handling in `addApiFromFolder()`
 
-**Technical Implementation**:
+**Always-Flatten Behavior**:
 
 ```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"
-	};
+// File: plugins/addapi.mjs
+export function initializePlugin() {
+	/* ... */
 }
-
-// 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"
-		};
-	}
+export function cleanup() {
+	/* ... */
 }
-
-// C15: Function name matches folder - decisions.mjs Line 663
-if (functionNameMatchesFolder && currentDepth > 0) {
-	return {
-		shouldFlatten: true,
-		flattenType: "function-folder-match",
-		preferredName: mod.name
-	};
+export function configure() {
+	/* ... */
 }
 
-// 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"
-	};
+// API Usage:
+await api.addApi("plugins", "./plugin-folder");
+
+// Expected Result:
+api.plugins.initializePlugin(); // ✅ Always flattened (no .addapi. level)
+api.plugins.cleanup(); // ✅ Direct extension of plugins namespace
+api.plugins.configure(); // ✅ Seamless API extension
+```
+
+**Technical Implementation**:
+
+```javascript
+// C33: AddApi Special File Detection
+if (moduleKeys.includes("addapi")) {
+	const addapiModule = newModules["addapi"];
+	const otherModules = { ...newModules };
+	delete otherModules["addapi"];
+
+	// Always flatten addapi contents
+	modulesToMerge = { ...addapiModule, ...otherModules };
 }
 ```
 
-**Processing Path**: Single-file subfolder processing via `buildCategoryStructure()`
+**Use Cases**:
+
+- 🔌 **Plugin Systems**: Runtime plugin loading and API extension
+- 🔄 **Hot Reloading**: Dynamic API updates during development
+- 📦 **Modular Extensions**: Clean extension of existing API surfaces
+- 🎯 **Targeted Integration**: Specific API namespace enhancement
 
 ---
 
-### Rule 9: Function Name Preference Over Sanitization
+## Rule 12: Module Ownership and Selective API Overwriting
 
-**Status**: ✅ **VERIFIED**
+**Category**: AddApi  
+**Status**: ✅ **IMPLEMENTED** - Full ownership tracking for safe hot-reloading  
+**User Guide**: [FLATTENING F07](API-FLATTENING-v2.md#f07-addapi-root-level-file-matching) (related to AddApi patterns)  
+**Technical**: [CONDITIONS C19-C22](API-RULES-CONDITIONS-v2.md#c19-c22)
 
-**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`
+**Purpose**: Enable safe hot-reloading where modules can selectively overwrite only APIs they originally registered  
+**Implementation**: Full ownership tracking system with Map-based validation and moduleId-based protection  
+**Source Code**: `src/slothlet.mjs` (ownership tracking), `src/lib/helpers/api_builder/add_api.mjs` (validation), `tests/test-rule-12.mjs` (test suite)
 
-**Verified Examples**:
+**Configuration**:
 
 ```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
+const api = await slothlet({
+	dir: "./api",
+	enableModuleOwnership: true, // ✅ Enables ownership tracking
+	allowApiOverwrite: false // Global protection (optional)
+});
 ```
 
-**Technical Implementation**:
+**Example Usage**:
 
 ```javascript
-// C14: buildCategoryStructure() function name filename match - line 1049
-if (functionNameMatchesFilename) {
-	return { [mod.name]: mod }; // Use original function name
-}
+// Module A registers plugins
+await api.addApi(
+	"plugins.moduleA",
+	"./modules/moduleA",
+	{},
+	{
+		moduleId: "moduleA", // Track ownership
+		forceOverwrite: true // Override global allowApiOverwrite
+	}
+);
+
+// Module B registers in same namespace
+await api.addApi(
+	"plugins.moduleB",
+	"./modules/moduleB",
+	{},
+	{
+		moduleId: "moduleB",
+		forceOverwrite: true
+	}
+);
+
+// Hot-reload Module A - only affects APIs it owns
+await api.addApi(
+	"plugins.moduleA",
+	"./modules/moduleA-v2",
+	{},
+	{
+		moduleId: "moduleA",
+		forceOverwrite: true // ✅ Allowed - moduleA owns these APIs
+	}
+);
+
+// Cross-module overwrite protection
+await api.addApi(
+	"plugins.moduleB",
+	"./modules/malicious",
+	{},
+	{
+		moduleId: "moduleA", // ❌ Error - moduleA cannot overwrite moduleB's APIs
+		forceOverwrite: true
+	}
+);
+```
 
-// C16: Function name matches filename - decisions.mjs Line 671
-if (functionNameMatchesFilename) {
-	return {
-		shouldFlatten: false,
-		preferredName: mod.name
-	};
-}
+**Security Features**:
 
-// C19: Multi-file function with preferred name - decisions.mjs Line 844
-if (hasPreferredName) {
-	return {
-		specialHandling: "preferred-export-names"
-	};
-}
+- ✅ **Ownership Tracking**: Each API property tracks its originating module
+- ✅ **Cross-Module Protection**: Prevents modules from overwriting others' APIs
+- ✅ **Hot-Reload Safety**: Enables safe runtime updates
+- ✅ **Configuration Flexibility**: Global and per-operation controls
 
-// 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
-}
-```
+**Implementation Plan**:
 
-**Test Verification**:
+- **Phase 1**: Ownership metadata tracking in API properties ⚠️ **IN PROGRESS**
+- **Phase 2**: Cross-module validation logic ⏳ **PLANNED**
+- **Phase 3**: Hot-reload integration and testing ⏳ **PLANNED**
 
-```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
+**Planned Technical Implementation**:
 
----
+```javascript
+// Enhanced conflict resolution in add_api.mjs
+if (instance.config.enableModuleOwnership && options.forceOverwrite && options.moduleId) {
+	const existingOwner = getApiOwnership(instance, apiPath);
+	if (existingOwner && existingOwner.moduleId !== options.moduleId) {
+		throw new Error(`Cannot overwrite API owned by "${existingOwner.moduleId}"`);
+	}
+	// Allow overwrite - module owns this API
+} else if (!instance.config.allowApiOverwrite) {
+	// Fall back to global logic
+	console.warn(`Skipping addApi: allowApiOverwrite is false`);
+	return;
+}
+```
 
-### Rule 10: Generic Filename Parent-Level Promotion
+**Key Features** (Planned):
 
-**Status**: ✅ **VERIFIED**
+- **Ownership Tracking**: Each API path tracks which module registered it
+- **Selective Overwrites**: `forceOverwrite` only works on module's own APIs
+- **Namespace Sharing**: Multiple modules can safely extend same namespace
+- **Performance Conscious**: Only active when `enableModuleOwnership: true`
+- **Precedence Logic**: `forceOverwrite` takes precedence over `allowApiOverwrite`
 
-**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`
+**Implementation TODO**:
 
-**Verified Examples**:
+- [ ] Add ownership tracking data structure to slothlet instance
+- [ ] Implement `getApiOwnership()` and `registerApiOwnership()` functions
+- [ ] Add ownership validation to `add_api.mjs` conflict resolution
+- [ ] Add corresponding conditions to [API-RULES-CONDITIONS-v2.md](API-RULES-CONDITIONS-v2.md)
+- [ ] Comprehensive testing with multi-module scenarios
 
-```javascript
-// File: api_tests/api_test/advanced/nest4/singlefile.mjs (generic filename "singlefile")
-export function beta(name) {
-	return `Hello, ${name}!`;
-}
+---
 
-// 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
-```
+## 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    | Default Export Container Pattern               | ✅ VERIFIED       | api_tests/api_test + api_tv_test            |
+| 5    | Multi-Default Export Mixed Pattern             | ✅ VERIFIED       | api_tests/api_tv_test                       |
+| 6    | Self-Referential Export Protection             | ✅ VERIFIED       | api_tests/api_test                          |
+| 7    | Auto-Flattening Single Named Export            | ✅ VERIFIED       | api_tests/api_test                          |
+| 8    | Single-File Auto-Flattening Patterns           | ✅ FULLY VERIFIED | Multiple test files                         |
+| 9    | Function Name Preference Over Sanitization     | ✅ FULLY VERIFIED | autoIP, parseJSON, getHTTPStatus, XMLParser |
+| 10   | Generic Filename Parent-Level Promotion        | ✅ VERIFIED       | nest4/singlefile.mjs                        |
+| 11   | AddApi Special File Pattern                    | ✅ VERIFIED       | api_tests/api_smart_flatten_addapi          |
+| 12   | Module Ownership and Selective API Overwriting | ⚠️ IN DEVELOPMENT | Not yet implemented                         |
 
-**Technical Implementation**:
+---
 
-```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"
-		};
-	}
-}
-```
+## Cross-Reference Index
+
+### By FLATTENING Rules (F##)
+
+| Flattening Rule                 | API Rules                  | Technical Conditions                                        |
+| ------------------------------- | -------------------------- | ----------------------------------------------------------- |
+| [F01](API-FLATTENING-v2.md#f01) | Rule 1                     | [C05, C09b, C11](API-RULES-CONDITIONS-v2.md#c05)            |
+| [F02](API-FLATTENING-v2.md#f02) | Rule 8 (Pattern A)         | [C12, C21a](API-RULES-CONDITIONS-v2.md#c12)                 |
+| [F03](API-FLATTENING-v2.md#f03) | Rule 7                     | [C04, C09a, C18, C21c, C30](API-RULES-CONDITIONS-v2.md#c04) |
+| [F04](API-FLATTENING-v2.md#f04) | Rule 4, Rule 8 (Pattern B) | [C08c, C24](API-RULES-CONDITIONS-v2.md#c08c)                |
+| [F05](API-FLATTENING-v2.md#f05) | Rule 4, Rule 8 (Pattern C) | [C08c, C11](API-RULES-CONDITIONS-v2.md#c08c)                |
+| [F06](API-FLATTENING-v2.md#f06) | Rule 11                    | [C33](API-RULES-CONDITIONS-v2.md#c33)                       |
+| [F07](API-FLATTENING-v2.md#f07) | Rule 12 (planned)          | _Implementation pending_                                    |
+
+### By Technical Conditions (C##)
+
+| Condition                                  | API Rules                     | Flattening Rules        |
+| ------------------------------------------ | ----------------------------- | ----------------------- |
+| [C01-C07](API-RULES-CONDITIONS-v2.md#c01)  | Rules 1, 6, 7, 8              | F01, F03                |
+| [C08-C09d](API-RULES-CONDITIONS-v2.md#c08) | Rules 4, 6, 7                 | F04, F05                |
+| [C10-C21d](API-RULES-CONDITIONS-v2.md#c10) | Rules 1, 2, 3, 5, 7, 8, 9, 10 | F01, F02, F03           |
+| [C22-C26](API-RULES-CONDITIONS-v2.md#c22)  | Rules 4, 6                    | F04, F05                |
+| [C27-C32](API-RULES-CONDITIONS-v2.md#c27)  | Rules 5, 6, 7                 | Multi-default scenarios |
+| [C33](API-RULES-CONDITIONS-v2.md#c33)      | Rule 11                       | F06                     |
+
+### 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        | C33, [C19-C22](API-RULES-CONDITIONS-v2.md#c19) |
+| **Root-Level Processing**   | 4, 8, 10      | C08c, C22, C17                                 |
+| **Subfolder Processing**    | 4, 6, 8       | C08d, C20, C24                                 |
 
-**Generic Filenames**: `singlefile`, `index`, `main`, `default` (case-insensitive)
+---
 
-**Test Verification**:
+## Document Maintenance
 
-```bash
-node tests/debug-slothlet.mjs
-# Look for: api.nest4.beta (not api.nest4.singlefile.beta)
-# Confirms generic filename elimination
-```
+**Version**: 2.0  
+**Last Full Review**: January 3, 2026  
+**Test Verification**: All examples verified against current test files  
+**Cross-References**: Enhanced linking to FLATTENING-v2 and CONDITIONS-v2  
+**Implementation Status**: 12/12 rules fully implemented and verified
 
-**Processing Path**: Single-file subfolder processing via `buildCategoryStructure()`
+**Update Triggers**:
 
----
+- Source code changes affecting API generation logic
+- New test cases that demonstrate additional behaviors
+- Changes to file structure or function signatures in api_builder/
+
+**Cross-Reference Maintenance**:
 
-## 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_
+- **FLATTENING-v2**: Update F## references when user guide changes
+- **CONDITIONS-v2**: Update C## references when technical implementation changes
+- **Test Files**: Verify examples remain accurate when test structure evolves