docs: add README

README.md

@@ -0,0 +1,36 @@
+
+
+# csnative CoreLib
+
+**csnative** is a custom implementation of the .NET Core Library (`CoreLib`) designed for the `csnative` runtime and compiler environment. It provides a minimal, foundational subset of the `System.*` namespaces required to boot and execute C# applications in a native or LLVM-based execution model.
+
+## Overview
+This library replaces the standard `mscorlib` / `System.Runtime` when targeting the `csnative` environment. It focuses on essential runtime types, low-level memory operations, exception handling, and collection interfaces. The codebase is structured to integrate tightly with unmanaged backends, utilizing `extern` method declarations and LLVM-style intrinsics for performance-critical operations.
+
+## Key Components
+- **Delegates & Generics:** `Action<T>`, `Func<T>`, `Predicate<T>`, `Comparison<T>`, `Converter<T>`, and `AsyncCallback`.
+- **Exceptions:** Core exception hierarchy including `ArgumentException`, `ArgumentNullException`, `ArgumentOutOfRangeException`, `ArithmeticException`, `AppDomainUnloadedException`, and `ApplicationException`.
+- **Attributes & Metadata:** `Attribute`, `AttributeTargets`, `AttributeUsageAttribute`, and `CLSCompliantAttribute`.
+- **Type Conversion & Memory:** `Boolean`, `BitConverter` (endian-aware byte conversion), `Buffer` (low-level memory copying and indexing), and `ArraySegment<T>`.
+- **Collections & Interfaces:** Generic collection interfaces (`ICollection<T>`, `IDictionary<TKey, TValue>`, `IEnumerator<T>`, `IReadOnlyCollection<T>`, `IComparer<T>`) and legacy `DictionaryEntry` / `Comparer`.
+- **Runtime & Assembly Loading:** `AppDomain`, `Activator`, and assembly loading stubs designed for custom runtime integration.
+
+## Installation & Build
+This project is not a standalone application or NuGet package. It is intended to be compiled as part of the `csnative` toolchain.
+
+1. **Prerequisites:** Ensure the `csnative` compiler and build environment are set up on your system.
+2. **Building:** Use the repository's primary build system (typically MSBuild, CMake, or custom scripts provided alongside the compiler) to compile the `CoreLib` project.
+3. **Integration:** The compiled library output is linked directly into the `csnative` runtime image or referenced during the compilation of target C# applications.
+
+## Usage
+- **Targeting:** Configure your C# compiler to use this `CoreLib` as the base reference library instead of the standard .NET Framework or .NET Core libraries.
+- **Runtime Dependencies:** Many methods in this library are declared as `extern` or rely on unmanaged/LLVM intrinsics (e.g., `Buffer.llvm_memcpy_*`). Ensure your execution environment provides the corresponding native stubs.
+- **Development:** This is a minimal core implementation. Several methods are intentionally stubbed with `NotImplementedException` and should be extended based on the specific capabilities of your target runtime.
+
+## License
+This repository contains source files licensed under the **Apache License 2.0** and the **MIT License**, as indicated by the headers in individual files. Please review the respective licenses for detailed terms.
+
+## Notes
+- Designed for low-level, research, or custom runtime development.
+- Not compatible with standard .NET runtimes (CLR/.NET Core) due to custom `extern` bindings and minimal type coverage.
+- Contributions and runtime-specific implementations are welcome.