@cldmv/slothlet 3.2.3 → 3.3.2

package/AGENT-USAGE.md

@@ -1,736 +0,0 @@
-# AGENT-USAGE.md: Building Slothlet API Folders
-
-> **Critical**: This guide prevents AI agents from making architectural mistakes when building Slothlet API modules.
-
-## 📋 Related Documentation
-
-- **[`docs/API-RULES.md`](docs/API-RULES.md)** - All 13 API transformation rules with verified test examples
-- **[`README.md`](README.md)** - Complete project overview and usage examples
-- **[`api_tests/*/README.md`](api_tests/)** - Live examples demonstrating each pattern below
-
----
-
-## 🚫 NEVER DO: Cross-Module Imports
-
-**The #1 mistake AI agents make with Slothlet**: Importing API files from each other.
-
-```js
-// ❌ WRONG - Do NOT import API modules from each other
-import { math } from "./math/math.mjs"; // BREAKS SLOTHLET
-import { config } from "../config.mjs"; // BREAKS SLOTHLET
-import { util } from "./util/util.mjs"; // BREAKS SLOTHLET
-```
-
-**Why this breaks Slothlet**:
-
-- Slothlet builds API structure dynamically at runtime
-- Cross-imports create circular dependencies
-- Breaks lazy loading and context isolation
-- Defeats the purpose of the module loading framework
-
-## ✅ CORRECT: Use Slothlet's Live-Binding System
-
-```js
-// ✅ CORRECT - Import from Slothlet runtime for cross-module access
-import { self, context } from "@cldmv/slothlet/runtime";
-
-export const myModule = {
-	async processData(input) {
-		// Access other API modules via `self` (live binding - always current)
-		const mathResult = self.math.add(2, 3);
-		const configValue = self.config.get("setting");
-		// context holds the current request/call context
-		console.log(`Caller: ${context.userId}`);
-		return `Processed: ${input}, Math: ${mathResult}`;
-	}
-};
-```
-
----
-
-## 🏗️ API Module Patterns
-
-### Pattern 1: Simple Object Export (Most Common)
-
-**File**: `math/math.mjs` → **API**: `api.math.add()`, `api.math.multiply()`
-
-```js
-export const math = {
-	add(a, b) { return a + b; },
-	multiply(a, b) { return a * b; }
-};
-```
-
-**Result**: Filename matches folder (`math/math.mjs`) → Auto-flattening → `api.math.add()` (not `api.math.math.add()`)
-
-> 📖 See [API-RULES.md Rule 1](docs/API-RULES.md) for flattening details.
-
-### Pattern 2: Multiple Files in Folder
-
-**Files**: `multi/alpha.mjs`, `multi/beta.mjs` → **API**: `api.multi.alpha.hello()`, `api.multi.beta.world()`
-
-```js
-// File: multi/alpha.mjs
-export const alpha = { hello() { return "alpha hello"; } };
-
-// File: multi/beta.mjs
-export const beta = { world() { return "beta world"; } };
-```
-
-**Result**: Different filenames from folder → No flattening → Nested structure preserved.
-
-### Pattern 3: Default Function Export
-
-**File**: `funcmod/funcmod.mjs` → **API**: `api.funcmod(name)`
-
-```js
-export default function funcmod(name) {
-	return `Hello, ${name}!`;
-}
-```
-
-**Result**: Filename matches folder + default export → Function flattened to `api.funcmod()`.
-
-### Pattern 4: Root-Level API Functions
-
-**File**: `root-function.mjs` → **API**: `api(name)` + `api.rootFunctionShout()`
-
-```js
-export default function greet(name) {
-	return `Hello, ${name}!`;
-}
-
-export function rootFunctionShout(message) {
-	return message.toUpperCase();
-}
-```
-
-**Result**: Root file with default export → `api()` callable + named exports as top-level `api.methodName()`.
-
-### Pattern 5: AddApi Special File Pattern (Rule 11)
-
-Files named `addapi.mjs` always flatten regardless of `autoFlatten` setting:
-
-```js
-// File: plugins/addapi.mjs
-export function initializePlugin() { return "Plugin initialized"; }
-export function cleanup() { return "Plugin cleaned up"; }
-```
-
-```js
-await api.slothlet.api.add("plugins", "./plugins-folder");
-api.plugins.initializePlugin(); // ✅ Direct extension - no intermediate namespace
-```
-
-> 📖 See [API-RULES.md Rule 11](docs/API-RULES.md) for addApi flattening details.
-
----
-
-## 🔄 Operating Modes
-
-Slothlet supports two loading modes set via `mode:` in the config:
-
-### Eager Mode (default)
-
-All modules are loaded synchronously at `await slothlet(...)`. The API is fully populated before `slothlet()` resolves.
-
-```js
-const api = await slothlet({ dir: "./api" }); // mode: "eager" is default
-// All api.* properties are immediately available
-```
-
-### Lazy Mode
-
-Modules are loaded on first access via transparent proxy. `slothlet()` resolves immediately without loading any files.
-
-```js
-const api = await slothlet({
-	dir: "./api",
-	mode: "lazy"
-});
-// api.math is a proxy - file not loaded yet
-const result = api.math.add(2, 3); // First access triggers load
-```
-
-#### Background Materialization
-
-Enable `backgroundMaterialize: true` to pre-load all modules in the background immediately after init (still non-blocking):
-
-```js
-const api = await slothlet({
-	dir: "./api",
-	mode: "lazy",
-	backgroundMaterialize: true
-});
-
-// Subscribe to completion event
-api.slothlet.lifecycle.on("materialized:complete", (data) => {
-	console.log(`${data.total} modules materialized`);
-});
-
-// Or await all modules to be ready
-await api.slothlet.materialize.wait();
-
-// Or check current progress
-const stats = api.slothlet.materialize.get();
-// { total, materialized, remaining, percentage }
-```
-
-**Important**: Lazy mode hot reload intentionally restores modules to an unmaterialized state on reload (references are not preserved). Eager mode preserves existing references by merging into the live wrapper.
-
----
-
-## 🎣 Hook System
-
-Hooks intercept API function calls. They work across all modes. See [`docs/HOOKS.md`](docs/HOOKS.md) for the full reference.
-
-### Hook Configuration
-
-```js
-// Simple enable (default pattern "**")
-const api = await slothlet({ dir: "./api", hook: true });
-
-// Enable with default pattern filter
-const api = await slothlet({ dir: "./api", hook: "database.*" });
-
-// Full configuration
-const api = await slothlet({
-	dir: "./api",
-	hook: {
-		enabled: true,
-		pattern: "**",
-		suppressErrors: false // true = errors suppressed (returns undefined instead of throwing)
-	}
-});
-```
-
-### Hook Types
-
-- **`before`** - Executes before the function. Can modify arguments or short-circuit. **Must be synchronous.**
-- **`after`** - Executes after successful completion. Can transform the return value.
-- **`always`** - Read-only observer. Always executes (even on short-circuit). Return value ignored.
-- **`error`** - Executes only when an error occurs. Receives error with source tracking.
-
-### Basic Hook Usage
-
-The `hook.on(typePattern, handler, options)` signature uses `"type:pattern"` as the first argument:
-
-```js
-// Before hook - modify arguments
-api.slothlet.hook.on(
-	"before:math.add",
-	({ path, args, ctx }) => {
-		return [args[0] * 2, args[1] * 2]; // Return array to replace arguments
-		// Return any non-array non-undefined value to short-circuit (skip function)
-		// Return undefined to continue with original args
-	},
-	{ id: "double-args", priority: 100 }
-);
-
-// After hook - transform result
-api.slothlet.hook.on(
-	"after:math.*",
-	({ path, args, result, ctx }) => {
-		return result * 10; // Return value to replace result; undefined = no change
-	},
-	{ id: "scale-result" }
-);
-
-// Always hook - observe (read-only)
-api.slothlet.hook.on(
-	"always:**",
-	({ path, result, hasError, errors }) => {
-		if (hasError) console.error(`${path} failed:`, errors);
-		else console.log(`${path} returned:`, result);
-		// Return value is ignored
-	},
-	{ id: "logger" }
-);
-
-// Error hook - monitor failures
-api.slothlet.hook.on(
-	"error:**",
-	({ path, error, source }) => {
-		// source.type: "before" | "after" | "always" | "function"
-		console.error(`Error in ${path} (from ${source.type}):`, error.message);
-	},
-	{ id: "error-monitor" }
-);
-```
-
-### Pattern Matching
-
-| Syntax | Description | Example |
-|---|---|---|
-| `exact.path` | Exact match | `"before:math.add"` |
-| `namespace.*` | All functions in namespace | `"after:math.*"` |
-| `*.funcName` | Function name across namespaces | `"always:*.add"` |
-| `**` | All functions | `"error:**"` |
-| `{a,b}` | Brace expansion | `"before:{math,utils}.*"` |
-| `!pattern` | Negation | `"before:!internal.*"` |
-
-### Hook Subsets
-
-Each hook type has three ordered execution phases:
-
-| Subset | Order | Typical use |
-|---|---|---|
-| `"before"` | First | Auth checks, security validation |
-| `"primary"` | Middle (default) | Main hook logic |
-| `"after"` | Last | Audit trails, cleanup |
-
-```js
-api.slothlet.hook.on(
-	"before:protected.*",
-	({ ctx }) => { if (!ctx.user) throw new Error("Unauthorized"); },
-	{ id: "auth", subset: "before", priority: 2000 }
-);
-```
-
-### Hook Management
-
-```js
-// Remove by ID
-api.slothlet.hook.remove({ id: "my-hook" });
-api.slothlet.hook.off("my-hook"); // alias for remove
-
-// Remove by filter
-api.slothlet.hook.remove({ type: "before", pattern: "math.*" });
-
-// Remove all
-api.slothlet.hook.clear();
-
-// List hooks
-const all = api.slothlet.hook.list();
-const active = api.slothlet.hook.list({ enabled: true });
-
-// Enable / disable without unregistering
-api.slothlet.hook.disable();         // disable all
-api.slothlet.hook.disable({ pattern: "math.*" });
-api.slothlet.hook.enable();          // re-enable all
-api.slothlet.hook.enable({ type: "before" });
-```
-
----
-
-## 🔄 Per-Request Context
-
-Execute functions with temporary merged context using `api.slothlet.context`:
-
-```js
-const api = await slothlet({
-	dir: "./api",
-	context: { appName: "MyApp", version: "3.0" }
-});
-
-// run() - execute a function inside a scoped context
-await api.slothlet.context.run({ userId: "alice", role: "admin" }, async () => {
-	// Inside this scope: context = { appName, version, userId, role }
-	await api.database.query();
-	await api.audit.log();
-});
-
-// scope() - return a new API object with merged context
-const scopedApi = api.slothlet.context.scope({ userId: "bob" });
-await scopedApi.database.query(); // context includes userId: "bob"
-```
-
-### Deep Merge Strategy
-
-```js
-// Default: shallow merge (top-level properties replaced)
-await api.slothlet.context.run({ newProp: "value" }, handler);
-
-// Deep merge: nested objects recursively merged
-await api.slothlet.context.run(
-	{ nested: { prop: "value" } },
-	handler,
-	{ mergeStrategy: "deep" }
-);
-```
-
-### Automatic EventEmitter Context Propagation
-
-Context propagates automatically through EventEmitter callbacks:
-
-```js
-import net from "net";
-import { context } from "@cldmv/slothlet/runtime";
-
-export const server = {
-	async start() {
-		const tcpServer = net.createServer((socket) => {
-			// Context automatically available in connection handler
-			console.log(`User ${context.userId} connected`);
-
-			socket.on("data", (data) => {
-				// Context preserved in nested event callbacks
-				console.log(`Data from ${context.userId}: ${data}`);
-			});
-		});
-		tcpServer.listen(3000);
-	}
-};
-```
-
-Works with: TCP servers, HTTP servers, custom EventEmitters, unlimited nested callbacks.
-
-> 📖 See [`docs/CONTEXT-PROPAGATION.md`](docs/CONTEXT-PROPAGATION.md) for full documentation.
-
----
-
-## 🏷️ Metadata System
-
-Tag API paths with metadata for authorization, auditing, and security. See [`docs/METADATA.md`](docs/METADATA.md) for the full reference.
-
-```js
-// Set metadata when loading (via api.slothlet.api.add)
-await api.slothlet.api.add("plugins/trusted", "./trusted-dir", {
-	metadata: { trusted: true, securityLevel: "high" }
-});
-
-// Set metadata at runtime
-api.slothlet.metadata.set("plugins.trusted.someFunc", { version: 2 });
-api.slothlet.metadata.setGlobal({ environment: "production" });
-api.slothlet.metadata.setFor("plugins/trusted", { owner: "core-team" });
-
-// Read metadata inside a module
-import { self } from "@cldmv/slothlet/runtime";
-
-export const secureOperation = {
-	async execute() {
-		// Access metadata via api.slothlet.metadata from within a module via self
-		// Or read it externally:
-		// const meta = api.slothlet.metadata.get("plugins.trusted.execute");
-		return "Authorized execution";
-	}
-};
-```
-
----
-
-## 🌍 Environment Snapshot (v3.1+)
-
-Slothlet captures a **frozen snapshot of `process.env` at init time** and exposes it at `api.slothlet.env`. The snapshot is deeply read-only — mutating `process.env` after init does not affect `api.slothlet.env`.
-
-```js
-const api = await slothlet({
-	dir: "./api",
-	env: true,
-	// env: { include: ["NODE_ENV", "DATABASE_URL", "PORT"] }  // allowlist
-});
-
-// Access inside any module:
-import { self } from "@cldmv/slothlet/runtime";
-
-export const getConfig = () => ({
-	mode: self.slothlet.env.NODE_ENV,
-	dbUrl: self.slothlet.env.DATABASE_URL
-});
-```
-
-**Key behaviors:**
-- `env: true` → all `process.env` variables are captured
-- `env: { include: [...] }` → only the listed keys are captured (recommended for security)
-- `api.slothlet.env` is a frozen object — writes throw in strict mode
-- Snapshot is taken at init time — late `process.env` mutations are NOT reflected
-
----
-
-## 🔁 Hot Reload / Dynamic API Management
-
-```js
-// Add new modules at runtime
-await api.slothlet.api.add("newModule", "./new-module-path");
-await api.slothlet.api.add("plugins", "./plugins", { collision: "merge" });
-
-// Remove modules by path
-await api.slothlet.api.remove("oldModule");
-
-// Reload all modules
-await api.slothlet.reload();
-
-// Reload specific API path
-await api.slothlet.api.reload("database.*");
-await api.slothlet.api.reload("plugins.auth");
-```
-
-> **Lazy mode reload behavior**: In lazy mode, reload restores modules to an unmaterialized proxy state - existing references to lazy wrappers are intentionally not preserved. Eager mode merges new module exports into the existing live wrapper, preserving references.
-
-> 📖 See [`docs/RELOAD.md`](docs/RELOAD.md) for reload system documentation.
-
----
-
-## ⚡ Lifecycle Events
-
-Subscribe to internal API events via `api.slothlet.lifecycle`:
-
-```js
-// Available events
-api.slothlet.lifecycle.on("materialized:complete", (data) => {
-	console.log(`${data.total} modules materialized`);
-});
-
-api.slothlet.lifecycle.on("impl:changed", (data) => {
-	console.log(`Module at ${data.apiPath} was reloaded`);
-});
-
-// Unsubscribe
-const handler = (data) => console.log(data);
-api.slothlet.lifecycle.on("materialized:complete", handler);
-api.slothlet.lifecycle.off("materialized:complete", handler);
-```
-
-**Available events**: `"materialized:complete"`, `"impl:created"`, `"impl:changed"`, `"impl:removed"`
-
----
-
-## 🔀 API Path Versioning (v3.2+)
-
-Mount multiple versions of the same logical path and dispatch to the correct version automatically based on the caller's version metadata.
-
-### Setup
-
-```js
-const api = await slothlet({
-	dir: "./api",
-	versionDispatcher: "version"  // use caller's versionMetadata.version field
-	// versionDispatcher: (allVersions, caller) => { ... }  // custom function
-});
-
-// Register versioned modules — 4th argument is versionConfig
-await api.slothlet.api.add("auth", "./api/v1", {}, { version: "v1", default: true });
-await api.slothlet.api.add("auth", "./api/v2", {}, { version: "v2" });
-```
-
-### Access Patterns
-
-```js
-// Dispatcher — routes via discriminator (use this in most cases)
-api.auth.login(user, pass)        // → routes to v1 or v2 based on caller metadata
-
-// Direct versioned access — bypasses dispatcher entirely
-api.v1.auth.login(user, pass)     // → always v1
-api.v2.auth.login(user, pass)     // → always v2
-```
-
-### Attaching Version Metadata to a Caller
-
-```js
-// Register a module WITH a version tag so the discriminator can use it
-await api.slothlet.api.add("services/payments", "./payments", {}, {
-	version: "v2",
-	metadata: { stable: true }    // versionConfig.metadata — stored in VersionManager only
-});
-
-// options.metadata (3rd arg)     → regular Metadata system (metadata.caller() etc.)
-// versionConfig.metadata (4th arg) → version-system only, used by the discriminator
-```
-
-### Runtime Version Management
-
-```js
-// List registered versions for a path
-api.slothlet.versioning.list("auth");
-// → { versions: { v1: { ... }, v2: { ... } }, default: "v2" }
-
-// Change the default dispatcher fallback
-api.slothlet.versioning.setDefault("auth", "v1");
-
-// Unregister a version (removes api.v1.auth; dispatcher updates automatically)
-await api.slothlet.versioning.unregister("auth", "v1");
-
-// Read version metadata stored at registration
-api.slothlet.versioning.getVersionMetadata(moduleID);
-```
-
-> 📖 See [`docs/VERSIONING.md`](docs/VERSIONING.md) for full documentation.
-
----
-
-## 📁 File Organization Best Practices
-
-### ✅ Clean Folder Structure
-
-```text
-api/
-├── config.mjs              → api.config.*
-├── math/
-│   └── math.mjs            → api.math.* (flattened - filename matches folder)
-├── util/
-│   ├── util.mjs            → api.util.* (flattened methods)
-│   ├── extract.mjs         → api.util.extract.*
-│   └── controller.mjs      → api.util.controller.*
-├── nested/
-│   └── date/
-│       └── date.mjs        → api.nested.date.*
-└── multi/
-    ├── alpha.mjs           → api.multi.alpha.*
-    └── beta.mjs            → api.multi.beta.*
-```
-
-### ✅ Naming Conventions
-
-- **Filename matches folder** → Auto-flattening (`math/math.mjs` → `api.math.*`)
-- **Different filename** → Nested structure preserved
-- **Dash-separated names** → camelCase API (`auto-ip.mjs` → `api.autoIP`)
-- **Function name preferred** → Original capitalization kept over sanitized form
-  (see [Rule 9](docs/API-RULES.md))
-
----
-
-## 🚨 Common AI Agent Mistakes
-
-### ❌ Mistake 1: Cross-Module Imports
-
-```js
-// ❌ WRONG
-import { config } from "./config.mjs";
-// ✅ CORRECT
-import { self } from "@cldmv/slothlet/runtime";
-// then: self.config.get(...)
-```
-
-### ❌ Mistake 2: Using V2 API Surface
-
-```js
-// ❌ WRONG (v2 API - does not exist in v3)
-await api.addApi("plugins", "./dir");
-await api.reloadApi("math.*");
-api.hooks.on("validate", "before", handler, { pattern: "math.*" });
-await api.run({ userId: "alice" }, fn);
-
-// ✅ CORRECT (v3 API)
-await api.slothlet.api.add("plugins", "./dir");
-await api.slothlet.api.reload("math.*");
-api.slothlet.hook.on("before:math.*", handler);
-await api.slothlet.context.run({ userId: "alice" }, fn);
-```
-
-### ❌ Mistake 3: Wrong Hook Config Key
-
-```js
-// ❌ WRONG
-const api = await slothlet({ dir: "./api", hooks: true }); // "hooks" plural
-
-// ✅ CORRECT
-const api = await slothlet({ dir: "./api", hook: true }); // "hook" singular
-```
-
-### ❌ Mistake 4: Breaking Auto-Flattening
-
-```js
-// File: math/calculator.mjs (different name from folder)
-export const math = { /* methods */ };
-// Result: api.math.calculator.math.* ← extra nesting, not flattened
-
-// ✅ CORRECT: File math/math.mjs
-export const math = { /* methods */ };
-// Result: api.math.* ← flattened
-```
-
-### ❌ Mistake 5: Using lifecycle.subscribe / lifecycle.emit
-
-```js
-// ❌ WRONG - subscribe/emit are internal
-api.slothlet.lifecycle.subscribe("materialized:complete", handler);
-api.slothlet.lifecycle.emit("impl:changed", data);
-
-// ✅ CORRECT - public surface is on/off only
-api.slothlet.lifecycle.on("materialized:complete", handler);
-api.slothlet.lifecycle.off("materialized:complete", handler);
-```
-
-### ❌ Mistake 6: Assuming `api.v1.auth` Goes Through the Dispatcher
-
-```js
-// ❌ WRONG — direct versioned path bypasses the discriminator entirely
-api.v1.auth.login(user, pass);   // always v1, no routing logic
-
-// ✅ CORRECT — use the logical dispatcher path for dynamic routing
-api.auth.login(user, pass);      // routes based on caller version metadata
-```
-
-### ❌ Mistake 7: Wrong Config Key for Versioning
-
-```js
-// ❌ WRONG
-const api = await slothlet({ dir: "./api", versionResolver: "version" });
-
-// ✅ CORRECT
-const api = await slothlet({ dir: "./api", versionDispatcher: "version" });
-```
-
-### ❌ Mistake 8: Conflating versionConfig.metadata with options.metadata
-
-```js
-// ❌ WRONG — puts version tag in the regular Metadata system instead of VersionManager
-await api.slothlet.api.add("auth", "./v2", { metadata: { version: "v2" } });
-
-// ✅ CORRECT
-// options.metadata (3rd arg)       → regular Metadata system (metadata.caller() etc.)
-// versionConfig.metadata (4th arg) → VersionManager only, used by the discriminator
-await api.slothlet.api.add("auth", "./v2",
-	{ metadata: { role: "core" } },
-	{ version: "v2", metadata: { stable: true } }
-);
-```
-
----
-
-## ✅ AI Agent Checklist
-
-- [ ] **No cross-module imports** - use `self` from `@cldmv/slothlet/runtime` instead
-- [ ] **Match filename to folder** for cleaner APIs (auto-flattening)
-- [ ] **Hook config key is `hook:` (singular)**, not `hooks:`
-- [ ] **Hook API** is `api.slothlet.hook.*`, not `api.hooks.*`
-- [ ] **Context API** is `api.slothlet.context.run/scope()`, not `api.run/scope()`
-- [ ] **Reload/add/remove** is `api.slothlet.api.add/remove/reload()`, not `api.addApi()` etc.
-- [ ] **Lifecycle** uses `api.slothlet.lifecycle.on/off()` only
-- [ ] **Lazy mode**: if using background materialization, use `api.slothlet.materialize.wait()` before accessing the API
-- [ ] **Hook subsets**: auth/security → `subset: "before"`, main logic → `"primary"`, audit → `"after"`
-- [ ] **Versioning config key is `versionDispatcher:`**, not `versionResolver:` or `versionDiscriminator:`
-- [ ] **Use `api.auth` (dispatcher path) for dynamic routing**, not `api.v1.auth` (direct path bypasses discriminator)
-- [ ] **`versionConfig.metadata` (4th arg)** and **`options.metadata` (3rd arg)** are separate systems — don't conflate them
-- [ ] **Double quotes everywhere** - follow Slothlet coding standards
-
----
-
-## 📚 Reference Examples
-
-- **Auto-flattening**: `api_tests/api_test/math/math.mjs`
-- **Multi-file folders**: `api_tests/api_test/multi/`
-- **Cross-module calls**: `api_tests/api_test_mixed/`
-- **Root-level APIs**: `api_tests/api_test/root-function.mjs`
-- **Nested structures**: `api_tests/api_test/nested/date/`
-
----
-
-## 📖 Essential Documentation
-
-### Core Architecture
-
-- **[`docs/API-RULES.md`](docs/API-RULES.md)** - All 13 API transformation rules
-- **[`docs/API-RULES/API-RULES-CONDITIONS.md`](docs/API-RULES/API-RULES-CONDITIONS.md)** - All C01–C34 conditional logic
-- **[`docs/API-RULES/API-FLATTENING.md`](docs/API-RULES/API-FLATTENING.md)** - Flattening rules F01–F08
-
-### Configuration & Features
-
-- **[`docs/CONFIGURATION.md`](docs/CONFIGURATION.md)** - All config options
-- **[`docs/HOOKS.md`](docs/HOOKS.md)** - Hook system (types, subsets, patterns, management)
-- **[`docs/METADATA.md`](docs/METADATA.md)** - Metadata system
-- **[`docs/CONTEXT-PROPAGATION.md`](docs/CONTEXT-PROPAGATION.md)** - Per-request context and EventEmitter propagation
-- **[`docs/RELOAD.md`](docs/RELOAD.md)** - Hot reload and dynamic API management
-- **[`docs/LIFECYCLE.md`](docs/LIFECYCLE.md)** - Lazy mode, materialization, and lifecycle events
-- **[`docs/SANITIZATION.md`](docs/SANITIZATION.md)** - Property name sanitization rules
-- **[`docs/I18N.md`](docs/I18N.md)** - Internationalization and language support
-- **[`docs/PERFORMANCE.md`](docs/PERFORMANCE.md)** - Performance characteristics and benchmarks
-
-### Critical Reading Order for AI Agents
-
-1. **This file** - Prevents architectural mistakes
-2. **[`README.md`](README.md)** - Project overview and quickstart
-3. **[`docs/API-RULES.md`](docs/API-RULES.md)** - API transformation rules
-4. **[`docs/HOOKS.md`](docs/HOOKS.md)** - Hook system (if needed)
-5. **[`docs/METADATA.md`](docs/METADATA.md)** - Metadata system (if needed)
-6. **[`api_tests/api_test/README.md`](api_tests/api_test/README.md)** - Live examples