@teqfw/di 2.5.0 → 2.6.0

package/README.md

@@ -3,199 +3,389 @@
 ![npms.io](https://img.shields.io/npm/dm/@teqfw/di)
 ![jsdelivr](https://img.shields.io/jsdelivr/npm/hm/@teqfw/di)
 
-**Runtime dependency linker for JavaScript applications designed for development with LLM agents.**
+**Enterprise-scale dependency architecture for pure JavaScript.**
 
-`@teqfw/di` is the core infrastructure of the **Tequila Framework (TeqFW)** — an architectural approach for building web applications in which **humans design system architecture and specifications, while LLM agents generate and maintain the implementation.**
+`@teqfw/di` replaces fragile file-path-based wiring with namespace-based component contracts and deterministic runtime linking, so large JavaScript codebases remain understandable to humans and reconstructible by coding agents.
 
-Instead of wiring modules through static imports, TeqFW applications declare **explicit dependency contracts**, and the container performs **deterministic runtime linking**.
+It is built for pure JavaScript ES modules.
 
-The result is an application architecture that is easier to:
+No TypeScript metadata.
+No decorators.
+No reflection.
+No framework-managed injection.
+No transpilation requirement.
 
-- analyze
-- generate
-- refactor
-- extend
+The package uses dependency injection techniques, but its main purpose is architectural governance, not constructor convenience.
 
-— both for **human developers and AI agents**.
+## Why JavaScript Dependency Wiring Breaks at Scale
 
-## The Shift in Software Development
+JavaScript applications usually express dependencies through static imports:
 
-Large language models are becoming a permanent part of the development process.
+```javascript
+import Repository from "../repository/UserRepository.js";
+```
 
-However, most software architectures were designed for **human-written code**, not for **code generated and maintained by AI agents**.
+This looks simple.
 
-Typical JavaScript applications rely on:
+But this line says two different things at once:
 
-- static imports
-- implicit dependency graphs
-- tight coupling to file structure
-- constructor-based dependency inference
+1. what the module needs;
+2. where that dependency is physically located.
 
-These patterns work well for humans but are difficult for automated agents to reason about reliably.
+That coupling is acceptable in small codebases.
 
-**TeqFW proposes a different architecture.**
+It becomes a structural problem when the application grows.
 
-Modules declare **explicit dependency contracts**, and a runtime container resolves those contracts deterministically.
+As modules multiply, dependency intent becomes scattered across:
 
-This transforms the dependency graph into something that can be **analyzed, generated and modified programmatically.**
+- file paths;
+- package specifiers;
+- framework conventions;
+- bundler configuration;
+- generated code;
+- decorators;
+- local composition logic.
 
-## What This Library Provides
+The architecture becomes harder to supervise because the real dependency graph is embedded inside implementation details.
 
-`@teqfw/di` implements the runtime container that enables this architecture.
+A developer no longer sees a component dependency model.
 
-It provides:
+The developer sees a filesystem.
 
-- deterministic runtime linking of ES modules
-- explicit dependency contracts (**CDC — Canonical Dependency Codes**)
-- module dependency descriptors (`__deps__`)
-- namespace-based module resolution
-- runtime lifecycle management
-- wrapper-based behavioral extensions
+## Why AI-Assisted Development Makes This More Important
 
-The container acts as a **runtime linker for JavaScript applications**.
+Coding agents change the practical scale of JavaScript development.
 
-## Designed for Development with LLM Agents
+One developer working with agents can now create and maintain systems whose size was previously more typical for enterprise teams.
 
-When software is generated or maintained by LLM agents, several structural problems appear.
+The bottleneck is no longer only code generation.
 
-| Problem          | Traditional Architecture | TeqFW Approach     |
-| ---------------- | ------------------------ | ------------------ |
-| Dependencies     | implicit imports         | explicit contracts |
-| Dependency graph | implicit                 | deterministic      |
-| Refactoring      | fragile                  | stable             |
-| Testing          | manual wiring            | container driven   |
-| AI compatibility | accidental               | intentional        |
+The bottleneck is architectural control.
 
-TeqFW structures the application so that **LLM agents can reliably understand and modify the system.**
+Agents can generate files quickly. They can modify many modules in one iteration. They can refactor local code. But if the dependency structure is hidden inside file paths and framework conventions, both the agent and the human supervisor must reconstruct architectural intent indirectly.
 
-## Agent-Driven Implementation
+That does not scale well.
 
-Starting from version **2.0.0**, the source code of this library is **written primarily by Codex agents**.
+Large AI-assisted JavaScript systems need dependency structure that is:
 
-The development workflow follows **specification-driven development**:
+- explicit;
+- stable;
+- reviewable;
+- machine-readable;
+- independent from local file layout;
+- deterministic at runtime.
 
-1. The human architect defines **product specifications**
-2. LLM agents generate the implementation
-3. The generated code is reviewed and integrated
+This is the problem `@teqfw/di` addresses.
 
-This workflow follows the **ADSM methodology (Agent-Driven Software Management)** developed by **Alex Gusev**.
+## The Enterprise Shift: From Files to Components
 
-Earlier versions of the library (<2.0.0) were written manually.
-The current version demonstrates how software can be developed using **human-defined architecture and AI-generated code**.
+Enterprise ecosystems such as Java and C# have long used namespaces, dependency inversion, IoC containers, component identifiers, explicit contracts, and runtime composition to keep large systems manageable.
 
-## Learn the Architecture (Interactive Onboarding)
+`@teqfw/di` brings that model of thinking to pure JavaScript.
+
+Instead of making a module depend on a file path:
+
+```javascript
+import Repository from "../repository/UserRepository.js";
+```
 
-Understanding this architecture can take time.
+the module declares a dependency on a component:
 
-To make onboarding easier, an **interactive AI assistant** [is available](https://fly.wiredgeese.com/flancer/gpt/teqfw/guide/di/).
+```javascript
+export const __deps__ = {
+  repository: "App_User_Repository$",
+};
+```
 
-The assistant can explain:
+This declaration says:
 
-- how the container works
-- what Canonical Dependency Codes are
-- how modules declare dependencies
-- how runtime linking works
-- how to integrate the library in real applications
+> This module needs the `App_User_Repository` component.
 
-The assistant acts as **interactive documentation** for the project.
+It does not say where the source file is located.
 
-Custom onboarding assistants like this can also be created **as a service** for other projects and libraries.
+The physical module location is resolved later by the container through configured namespace roots.
 
-## Agent Interface (Documentation for LLM Agents)
+This is the central shift:
 
-This package includes **agent interface documentation** intended for LLM agents that use the library as an npm dependency.
+```text
+from file paths
+to component addresses
 
-These documents are distributed inside the package in:
+from local imports
+to explicit dependency contracts
 
-```txt
-./ai/
+from scattered wiring
+to deterministic runtime composition
 ```
 
-The files in this directory describe the **public interface of the package in an agent-friendly form**.
+## What @teqfw/di Is
+
+`@teqfw/di` is a runtime composition layer for pure JavaScript ES modules.
 
-They explain:
+It provides:
 
-- the container API
-- dependency descriptors (`__deps__`)
-- Canonical Dependency Codes (CDC)
-- dependency resolution behavior
-- integration patterns
+- namespace-based component addressing;
+- Canonical Dependency Codes;
+- source-attached dependency declarations through `__deps__`;
+- deterministic runtime linking;
+- namespace root mapping for Node.js and browser environments;
+- lifecycle control for singleton and new-instance dependencies;
+- explicit replacement in test mode;
+- wrapper-based extension points;
+- immutable linked objects.
 
-Human developers typically read the README and source code, while **LLM agents can rely on the documentation in `./ai/`.**
+The ES module system remains the underlying loading mechanism.
 
-## Tequila Framework Philosophy
+The package does not replace ESM.
 
-`@teqfw/di` is the core building block of the **Tequila Framework (TeqFW)** ecosystem.
+It replaces application-level dependency wiring through static imports.
 
-TeqFW is based on several architectural principles:
+## Product Goal
 
-- runtime late binding between components
-- namespace-based module organization
-- modular monolith architecture
-- pure JavaScript without compilation
-- system structures optimized for collaboration with LLM agents
+The goal of `@teqfw/di` is to make enterprise-scale dependency architecture practical in pure JavaScript.
 
-Full philosophy:
+The package gives JavaScript applications a dependency model that is:
 
-`PHILOSOPHY.md`
+- based on stable namespace-based component addresses;
+- explicit in source artifacts;
+- deterministic under finalized runtime configuration;
+- usable across browser and Node.js environments;
+- readable by humans;
+- reconstructible by coding agents;
+- independent from TypeScript metadata, decorators, reflection, and framework-managed injection.
 
-## Installation
+The intended result is architectural supervision.
 
-```bash
-npm install @teqfw/di
+A developer should be able to see what a component needs without tracing import paths across the filesystem.
+
+An agent should be able to modify code without silently destroying the dependency structure.
+
+A runtime should be able to link components through explicit contracts rather than inference.
+
+## Core Model
+
+The model follows this chain:
+
+```text
+Namespace
+  -> Component Address
+  -> CDC
+  -> __deps__
+  -> Namespace Root
+  -> Runtime Linker
+  -> Linked Object
 ```
 
-## Quick Example
+A **namespace** defines a stable application-level addressing space.
+
+A **component address** identifies a component inside that namespace.
+
+A **CDC** — Canonical Dependency Code — encodes the component address and linking semantics.
+
+A module declares its dependencies through `__deps__`.
 
-### Define modules
+A **namespace root** maps a namespace prefix to a concrete runtime module location.
 
-`src/App/Child.mjs`
+The container resolves CDC values under finalized configuration, imports the required ES modules, links declared dependencies, and returns linked objects.
+
+The linking happens at runtime, but it is not heuristic. The container does not infer dependencies from behavior, constructor signatures, decorators, reflection, or naming guesses.
+
+For identical dependency declarations, CDC values, namespace roots, module exports, lifecycle rules, and finalized container configuration, the container must produce the same linked result or the same failure.
+
+## Example: File-Oriented vs Component-Oriented Wiring
+
+Traditional JavaScript wiring:
 
 ```javascript
-export default function App_Child() {
-  return { name: "child" };
-}
+import Repository from "../repository/UserRepository.js";
 ```
 
-`src/App/Helper/Cast.mjs`
+This is file-oriented.
+
+The module depends on a concrete module specifier.
+
+With `@teqfw/di`:
 
 ```javascript
-export default function App_Helper_Cast() {
-  return function cast(value) {
-    return String(value);
-  };
-}
+export const __deps__ = {
+  repository: "App_User_Repository$",
+};
 ```
 
-`src/App/Root.mjs`
+This is component-oriented.
+
+The module depends on a logical component address.
+
+The difference is not just technical.
+
+It changes the source of architectural truth.
+
+## Why It Matters for Coding Agents
+
+In agent-assisted development, dependency declarations become part of the shared cognitive field between the human developer, the coding agent, and the runtime system.
+
+A module can expose its dependency intent as data:
 
 ```javascript
 export const __deps__ = {
-  cast: "App_Helper_Cast$",
+  repository: "App_User_Repository$",
+  logger: "App_Logger$",
+  config: "App_Config$",
 };
+```
+
+This structure is easy for agents to generate.
+
+It is easy for humans to review.
+
+It is deterministic for the container to execute.
+
+Agent readability is not a separate feature. It is a consequence of explicit namespace-based dependency structure.
+
+## Why It Matters for Browser and Node.js
+
+Browser and Node.js environments both support ES modules, but they do not provide one shared application-level dependency wiring model.
 
-export default class RuntimeWrapper {
-  constructor() {
-    return {
-      mode: "runtime-wrapper",
-    };
-  }
+Static imports usually depend on:
+
+- file layout;
+- package layout;
+- URL layout;
+- bundler behavior;
+- runtime-specific module resolution.
+
+`@teqfw/di` moves dependency intent away from those concrete specifiers.
+
+The same source module can declare:
+
+```javascript
+export const __deps__ = {
+  repository: "App_User_Repository$",
+};
+```
+
+In Node.js, `App_` may point to a filesystem directory.
+
+In a browser, `App_` may point to a URL base.
+
+The dependency declaration remains stable.
+
+Only the namespace root changes.
+
+## Who It Is For
+
+`@teqfw/di` is designed primarily for:
+
+- solo developers and small teams building long-lived web applications;
+- developers using coding agents as active implementation and maintenance participants;
+- modular monolith applications;
+- isomorphic JavaScript systems that share code between browser and server;
+- pure JavaScript + JSDoc codebases;
+- projects where explicit dependency structure is more important than minimal local ceremony;
+- applications expected to grow beyond prototype size.
+
+It is especially relevant when one human remains responsible for architectural supervision while agents participate in code generation, maintenance, and refactoring.
+
+## When It Is Not the Best Fit
+
+`@teqfw/di` is usually not the best fit when:
+
+- the project is a short-lived prototype;
+- the application is small enough for direct imports to remain clear;
+- the team is fully committed to a decorator-driven TypeScript framework;
+- framework conventions are more important than explicit dependency contracts;
+- minimal local ceremony is more valuable than architectural traceability;
+- runtime linking is not acceptable for the project’s deployment model.
+
+This package is a deliberate architectural tradeoff.
+
+It favors explicit structure over local simplicity.
+
+## How It Fits in JavaScript
+
+This approach is unusual in mainstream JavaScript.
+
+Most JavaScript and TypeScript projects express application dependency structure through some mix of:
+
+- static imports;
+- file paths;
+- package specifiers;
+- framework conventions;
+- TypeScript-first source architecture;
+- decorators or metadata-driven injection;
+- framework-managed DI;
+- bundler-controlled module graphs.
+
+`@teqfw/di` makes a different tradeoff.
+
+It favors namespace-based component addresses and explicit runtime contracts over hidden or inferred wiring.
+
+TypeScript has had a major influence on the JavaScript ecosystem, and that influence has been broadly positive. At the same time, TeqFW targets a different design space:
+
+- pure JavaScript + JSDoc;
+- no transpilation requirement;
+- isomorphic runtime behavior;
+- namespace-based addressing;
+- explicit dependency declarations;
+- source artifacts readable by humans and agents.
+
+This is not presented as the only correct way to structure JavaScript.
+
+It is a focused alternative for projects that need stronger runtime explicitness and machine-reconstructible structure.
+
+## Comparison
+
+| Concern                    | Common JS/TS Approach                                 | `@teqfw/di`                             |
+| -------------------------- | ----------------------------------------------------- | --------------------------------------- |
+| Dependency expression      | Static imports, decorators, framework wiring          | `__deps__` declarations with CDC values |
+| Addressing model           | File-based, package-based, or framework-defined       | Namespace-based component addressing    |
+| Resolution model           | Static, implicit, framework-driven, or bundler-driven | Deterministic runtime linking           |
+| Structural source of truth | Spread across code, metadata, config, and conventions | Source-attached dependency contracts    |
+| Cross-environment wiring   | Bundlers, adapters, duplicated specifiers             | Namespace roots                         |
+| Best fit                   | Framework-led or TypeScript-first applications        | Pure JavaScript + JSDoc modular systems |
+| Agent readability          | Mixed and often indirect                              | Explicit and reconstructible            |
+| Architectural mindset      | Local module graph                                    | Enterprise-scale component composition  |
+
+## Installation
+
+```bash
+npm install @teqfw/di
+```
+
+## Quick Start
+
+Define one repository module and one service module that declares the repository as an explicit dependency.
+
+`src/App/User/Repository.mjs`
+
+```javascript
+export default function Repository() {
+  return {
+    async findNameById(id) {
+      return `User ${id}`;
+    },
+  };
 }
+```
+
+`src/App/User/Service.mjs`
 
-export class Factory {
-  constructor({ cast }) {
-    this.configure = function (params = {}) {
-      return {
-        name: "factory",
-        cast,
-        params,
-      };
-    };
-  }
+```javascript
+export default function Service({ repository }) {
+  return {
+    async getProfile(id) {
+      const name = await repository.findNameById(id);
+      return { id, name };
+    },
+  };
 }
+
+export const __deps__ = {
+  repository: "App_User_Repository$",
+};
 ```
 
-### Configure container
+Configure the container and request the dependency:
 
 ```javascript
 import path from "node:path";
@@ -206,151 +396,164 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 const container = new Container();
-
 container.addNamespaceRoot("App_", path.resolve(__dirname, "./src/App"), ".mjs");
 
-const factory = await container.get("App_Root__Factory$");
+const service = await container.get("App_User_Service$");
+
+const profile = await service.getProfile(42);
+
+console.log(profile);
+```
+
+Output:
+
+```javascript
+{ id: 42, name: "User 42" }
+```
+
+In this flow the container:
+
+- parses the dependency request;
+- resolves `App_` through the registered namespace root;
+- translates `App_User_Repository$` into a concrete ES module location;
+- imports the module;
+- reads `__deps__` for the selected export;
+- recursively links dependencies;
+- returns a frozen linked object.
+
+## Core Concepts
+
+### Namespace
+
+A namespace defines a stable addressing space for application components.
+
+In TeqFW, a dependency address such as:
+
+```text
+App_User_Repository$
+```
+
+uses `App_` as a namespace prefix.
+
+The namespace makes the dependency address independent from local file paths and runtime-specific module specifiers.
+
+### Component Address
 
-console.log(factory.configure().mode);
+A component address identifies an application component inside a namespace.
+
+For example:
+
+```text
+App_User_Repository
+```
+
+identifies the `Repository` component inside the `App_` namespace.
+
+The component address is logical.
+
+It is not itself a file path or URL.
+
+### CDC
+
+A **Canonical Dependency Code** is the string contract used to request a dependency.
+
+General form:
+
+```text
+[PlatformPrefix]ModuleName[__ExportName][LifecycleAndWrappers]
 ```
 
-The container:
+Examples:
+
+```text
+App_User_Repository$
+App_User_Repository__Factory$$
+node:fs
+npm:lodash
+```
+
+Where:
+
+- `App_User_Repository` is the namespace-based component address;
+- `__Factory` selects a named export;
+- `$` means singleton lifecycle;
+- `$$` means new instance lifecycle;
+- `node:` and `npm:` address platform-specific modules.
 
-- loads modules
-- resolves dependency contracts
-- constructs the object graph
-- returns **frozen linked objects**
+### `__deps__`
 
-## Dependency Contracts (`__deps__`)
+`__deps__` is a source-attached dependency declaration.
 
-Modules declare dependencies using a static export descriptor.
+For a single-export module, dependencies can be declared in shorthand form:
 
 ```javascript
 export const __deps__ = {
-  default: {
-    localName: "Dependency_CDC",
-  },
-  Factory: {
-    localName: "Dependency_CDC",
-  },
+  localName: "Dependency_CDC",
 };
 ```
 
 Rules:
 
-- the canonical form is hierarchical and keyed by export name
-- each export entry maps constructor argument names to CDC dependency identifiers
-- if `__deps__` is absent — module has no dependencies
-- a flat `__deps__` object is a shorthand allowed only for limited single-export cases
-- dependencies are resolved recursively
+- the canonical form is hierarchical and keyed by export name;
+- each export entry maps constructor argument names to CDC strings;
+- if `__deps__` is absent, the export has no declared dependencies;
+- a flat `__deps__` object is shorthand for limited single-export cases.
 
-Canonical example:
+Canonical export-scoped form:
 
 ```javascript
 export const __deps__ = {
   default: {
-    cast: "Fl32_Web_Helper_Cast$",
+    localName: "Dependency_CDC",
   },
   Factory: {
-    cast: "Fl32_Web_Helper_Cast$",
+    localName: "Dependency_CDC",
   },
 };
-
-export default class RuntimeWrapper {
-  constructor() {
-    return {
-      mode: "runtime-wrapper",
-    };
-  }
-}
-
-export class Factory {
-  constructor({ cast }) {
-    this.configure = function (params = {}) {
-      // DI-managed component
-    };
-  }
-}
 ```
 
-In this pattern:
-
-- the default export is the runtime wrapper or module shell
-- the named `Factory` export is the DI-managed component
-- `__deps__` applies to the export selected by the CDC, such as `App_Module__Factory$`
+### Namespace Root
 
-Shorthand example for a single-export module:
+A namespace root maps a namespace prefix to a module-specifier base:
 
 ```javascript
-export const __deps__ = {
-  cast: "Fl32_Web_Helper_Cast$",
-};
-
-export default class RuntimeWrapper {
-  constructor() {
-    return {
-      mode: "runtime-wrapper",
-    };
-  }
-}
+container.addNamespaceRoot("App_", "/abs/path/to/src/App", ".mjs");
 ```
 
-Empty descriptor example:
+This lets the container translate logical module names such as `App_User_Repository$` into concrete ES module files or URL-based module specifiers.
+
+In Node.js, that often means filesystem-backed module roots:
 
 ```javascript
-export default class App_Empty {
-  constructor() {
-    this.ready = function () {
-      return true;
-    };
-  }
-}
+container.addNamespaceRoot("App_", "/project/src/App", ".mjs");
 ```
 
-In this pattern:
-
-- the module has no declared dependencies
-- `__deps__` is omitted entirely
-- the empty form is valid and intentionally explicit through omission
-
-## Canonical Dependency Codes (CDC)
-
-CDC identifiers describe **how dependencies should be resolved**.
+In a browser-oriented or isomorphic application, it can also mean URL-backed roots:
 
-General form:
-
-```txt
-[PlatformPrefix]ModuleName[__ExportName][LifecycleAndWrappers]
+```javascript
+container.addNamespaceRoot("App_", "https://cdn.example.com/app", ".mjs");
+container.addNamespaceRoot("Web_", "//cdn.example.com/web", ".mjs");
 ```
 
-Examples:
+This keeps dependency addressing stable while allowing the same logical naming model to work across shared application code, browser-facing modules, and different runtime environments.
 
-```txt
-App_Service
-App_Service$
-App_Service__build$$
-App_Service$$_wrapLog_wrapTrace
-node:fs
-npm:@humanfs/core
-node:worker_threads
-npm:lodash
-```
+### Runtime Linking
 
-Where:
+Runtime linking is the process of resolving CDC values under finalized container configuration, importing the corresponding ES modules, injecting declared dependencies, and returning linked objects.
 
-- `node:` platform prefix for Node.js built-in modules
-- `npm:` platform prefix for npm packages
-- `$` singleton lifecycle
-- `$$` new instance lifecycle
-- wrappers modify runtime behavior
+The mechanism is dynamic because it runs at runtime.
+
+The mechanism is deterministic because dependencies are declared explicitly and resolved through fixed namespace roots and configuration.
 
 ## Public API
 
+Create a container:
+
 ```javascript
 const container = new Container();
 ```
 
-Configuration methods (before first `get`):
+Configure it before the first `get(...)`:
 
 - `setParser(parser)`
 - `addNamespaceRoot(prefix, target, defaultExt)`
@@ -360,55 +563,26 @@ Configuration methods (before first `get`):
 - `enableTestMode()`
 - `register(cdc, mock)`
 
-Dependency resolution:
+Resolve dependencies:
 
 ```javascript
 await container.get(cdc);
 ```
 
-Behavior:
-
-- deterministic linking
-- fail-fast resolution pipeline
-- immutable returned objects
-- container enters failed state on fatal errors
-
-## Wrappers
-
-Wrappers allow cross-cutting behavior to be applied declaratively.
-
-Example CDC:
-
-```txt
-App_Service$$_log_trace
-```
-
-Wrappers can implement:
+The container is builder-configurable until the first `get(...)`.
 
-- logging
-- metrics
-- tracing
-- security checks
-- behavioral instrumentation
-
-This acts as a lightweight **DI-level AOP mechanism.**
-
-Platform-specific examples:
-
-```txt
-node:worker_threads
-npm:@humanfs/core
-```
+After that point configuration is locked.
 
 ## Test Mode
 
+Test mode allows registered mocks to be resolved before module instantiation:
+
 ```javascript
 container.enableTestMode();
-
 container.register("App_Service$", mockService);
 ```
 
-Mocks are resolved before module instantiation.
+This keeps replacement explicit and local to container configuration.
 
 ## Browser Usage
 
@@ -420,24 +594,36 @@ Mocks are resolved before module instantiation.
 </script>
 ```
 
-## Documentation
+## Documentation for Agents
+
+This package includes a machine-oriented package interface under `./ai/`.
+
+Those files are intended for system prompts, examples, and agent consumption. They describe:
+
+- container usage;
+- dependency descriptors;
+- CDC behavior;
+- integration patterns.
+
+The package ships both a human-facing README and a machine-oriented interface for agents that need to use it as a dependency.
+
+## Further Reading
 
-Detailed documentation lives in `ctx/`:
+- Usage guide: `ai/usage.md`
+- Container API notes: `ai/container.md`
+- Dependency descriptor concepts: `ai/concepts.md`
+- Dependency ID format: `ai/dependency-id.md`
+- Extension points: `ai/extensions.md`
+- Project philosophy and intended application domain: `PHILOSOPHY.md`
 
-- `ctx/docs/product/overview.md`
-- `ctx/docs/product/default-cdc-profile.md`
-- `ctx/docs/architecture/cdc-profile/default/grammar.md`
-- `ctx/docs/architecture/cdc-profile/default/transformation.md`
-- `ctx/docs/architecture/cdc-profile/default/validation.md`
-- `ctx/docs/code/components/container.md`
+## TeqFW Context
 
-## Author
+`@teqfw/di` is the core dependency-linking building block of the Tequila Framework.
 
-**Alex Gusev**
+TeqFW is aimed at building modular monolith web applications with a unified JavaScript codebase across browser and server runtimes. The method favors namespace-based component addressing, late binding, explicit contracts, pure JavaScript, and source artifacts that remain legible to both humans and LLM agents.
 
-Creator of:
+The broader TeqFW position is that AI-assisted development changes not only how code is written, but also what kind of structure a solo developer needs in order to supervise a growing application.
 
-- **Tequila Framework (TeqFW)**
-- **ADSM (Agent-Driven Software Management)**
+When JavaScript applications reach enterprise scale under human-agent development, file-path-based dependency wiring becomes too local and too implicit.
 
-The project explores how software architecture evolves when **LLM agents become active participants in the development process**.
+`@teqfw/di` is one concrete answer to that change: enterprise-scale dependency architecture for pure JavaScript.