Better agents file

AGENTS.md

@@ -0,0 +1,93 @@
+
+# SharpLib and general coding guidelines
+
+## 1. CORE PHILOSOPHY
+
+* **Leaky Abstractions:** All abstractions are always leaky.  Do not hide complexity. Expose failure modes, costs, and "why" parameters.
+* **Visual Cost:** "Expensive things must look expensive." No hidden RPCs. Use explicit Message structs and `Send` methods.
+* **Fast & Introspectable:** Code must be highly performant (hot-path aware) but deeply debuggable (`log`, `DebugOld`, `reason` strings).
+
+## 2. NAMING & SEMANTICS
+
+* **Leaf Libraries:** Core libs (`io`, `imm`, `net`, `log`) are 2-5 chars. **NEVER** use `using` for them. Always type the prefix (e.g., `imm.Process`).
+* **No Redundancy:**
+  * **No "Get":** `Player()` not `GetPlayer()`.
+  * **No Echo:** `Send(msg)` not `SendMsg(msg)`.
+  * **No "I" Prefix:** Interfaces are `Renderer`, not `IRenderer`.
+* **Architecture:** Slow/Pausable Realtime. Entity Component System (Pub/Sub).
+
+## 3. LOGGING (`log` static class)
+
+* **Constraint:** **NO** `Console.WriteLine`, `Debug.WriteLine`, or `ILogger`.
+* **Mechanism:** The logging system is very fast. It only queues the log on the main thread.  It collects the caller debug info, and uses the directory name of the file for a default category (this can be overridden)
+* **Functional Tracing:**
+  * `var x = log.info( $"Got {log.var(Calc())} from the calculation" );` // This both logs the info and prints what happened
+* **Standard:** `log.info`, `log.debug`, `log.warn`, `log.error`.
+* **Finer grained:** `log.trace`, `log.high`
+* Use log.exception( ex, $"[what was trying to be done]" );
+* **Introspection:** `log.logProps(obj, "Header")` and `log.exception(ex, "Context")`.
+* put important info as far to the left as possible, even at the cost of poor wording
+
+## 4. IMMUTABLE STATE (`io`, `imm`)
+
+* **Rule:** Objects inheriting `Versioned<T>`, `Recorded<T>`, `Timed<T>` are **IMMUTABLE**.
+* **Change Pipeline:** MUST use `Process`.
+  * **Ref Helper (Preferred):** `imm.Process(ref _state, s => s with { X = 1 }, "Reason");`
+  * **Instance:** `_state = _state.Process(s => s with { X = 1 }, "Reason");`
+* **The "Hole Punch":** Always propagate a `string reason` parameter in your methods to feed the `Process` log.
+* **History:** `obj.DebugOld` is for **DEBUG ONLY**. Do not base game logic on it.
+
+## 5. Visual Cost
+
+* Unless something is a function call, it should look like a function call.  For example RPCs are bad, sending a message is good.  
+* **No RPCs:** Do not make network calls look like functions.
+* **Pattern:** Construct Struct -> Send.
+  * *Bad:* `proxy.Move(x,y)`
+  * *Good:* `Net.Send(new MoveMsg(x,y))`
+
+## FEW-SHOT EXAMPLES (Strictly Imitate)
+
+```csharp
+// 1. NAMING & LOGGING
+// Explicit 'log' usage, no 'Get', no 'Console'
+public void Init() 
+{
+  log.startup( "log/current_project.log" );
+
+  var waitTime = 1.0f;
+
+  log.info( $"Waiting for {waitTime}" );
+
+  try
+  {
+    obj.SomeOperation();
+   }
+   catch( Exception ex )
+    {
+       log.exception( ex, $"" );
+    }
+    
+    // 2. IMMUTABLE PROCESS
+    // Reason "Init" passed down. Ref pattern used.
+    imm.Process(ref _state, s => s with { Ready = true }, "Init");
+}
+
+// 3. LOGIC FLOW
+public void Update(float dt)
+{
+    // 'Player()' not 'GetPlayer()'
+    var p = Player();
+    
+    // Visual Cost: Explicit allocation of message struct
+    if (p.Active)
+    {
+        Net.Send(new HeartbeatMsg(dt));
+    }
+}
+
+// 5. INTROSPECTION API
+// "Punching a hole" with the reason parameter
+public void Equip(Item i, string reason = "Equip")
+{
+   imm.Process( ref inv, s => s.Add(i), reason);
+}

BADAGENTSBAD.BAD

@@ -0,0 +1,103 @@
+# SharpLib - Core Library Reference
+
+SharpLib is a comprehensive C# utility library providing essential functionality for .NET applications. It offers a wide range of utilities, mathematical operations, and helper classes to streamline development.
+
+## Core Components
+
+### Math & Geometry
+- **Vector2/3/4**: Vector mathematics with extensive operations
+- **Matrix**: 4x4 matrix operations for transformations
+- **Quaternion**: Quaternion math for 3D rotations
+- **BoundingBox/BoundingSphere**: Collision detection primitives
+- **Ray/Plane**: Geometric raycasting and plane operations
+- **Color**: Color manipulation with multiple formats (RGBA, HSV, etc.)
+- **MathUtil**: Mathematical helper functions and constants
+- **Angle**: Angle handling utilities
+
+### Data Structures & Collections
+- **Immutable collections**: Immutable List, FSM (Finite State Machine), Versioned, Recorded, Timed objects
+- **Pod**: Plain Old Data structures
+- **LinqExtensions**: Extended LINQ functionality
+- **RandomEx**: Enhanced random number generation
+- **Guid**: GUID utilities
+
+### Utilities & Helpers
+- **StringEx**: String manipulation extensions
+- **Debug**: Debugging utilities
+- **Exec**: Process execution helpers
+- **Utilities**: General utility functions
+- **Token**: Token handling utilities
+- **Id**: ID generation utilities
+
+### Reflection & Metadata
+- **Reflection utilities**: Runtime type inspection and manipulation
+- **Attributes**: Custom attributes for data handling
+
+### System Integration
+- **Logging**: Logging infrastructure with structured logging, source location tracking, and multiple log levels
+- **Time/Timer/Clock**: Time management utilities
+- **Resources**: Resource management helpers with lazy loading and caching
+- **Interop**: Platform interop capabilities
+- **Config**: Configuration management with XML serialization and template creation
+- **Immutable**: Immutable collections with versioning (Versioned), recording (Recorded), and timing (Timed) capabilities
+
+## Key Features
+
+- **Cross-platform compatibility**: Targets .NET 9.0 and 10.0
+- **Unsafe code support**: For performance-critical operations
+- **Extensive documentation**: Well-documented APIs with examples
+- **Type safety**: Strong typing throughout the library
+- **Performance focused**: Optimized for speed and memory usage
+
+## Usage Examples
+
+```csharp
+// Vector math
+var vector = new Vector3(1, 2, 3);
+var normalized = vector.Normalized();
+
+// Color manipulation
+var color = Color.FromRgb(255, 128, 0);
+var hsv = color.ToHsv();
+
+// Bitwise operations
+if (bit.On(flags, MyEnum.Flag1))
+{
+    // Handle flag
+}
+
+// Random generation
+var random = new RandomEx();
+var value = random.NextDouble();
+
+// Logging with source location tracking
+log.Info("Application started", cat: "app");
+log.Var("User ID", userId);
+log.Operations(() => {
+    // Some operation
+});
+
+// Configuration loading
+var config = cfg.load<MyConfig>("config.xml");
+
+// Resource management
+var texture = res.Mgr.Lookup<Texture2D>("assets/texture.png");
+
+// Immutable collections
+var list = new List<int>(new[] { 1, 2, 3 });
+var newList = list.Add(4);
+```
+
+## Target Frameworks
+
+- .NET 9.0
+- .NET 10.0
+
+## Dependencies
+
+- Microsoft.CodeAnalysis.CSharp
+- Optional (for functional programming patterns)
+- System.Collections.Immutable
+- System.ValueTuple
+- Microsoft.Diagnostics.NETCore.Client
+- Microsoft.Diagnostics.Tracing.TraceEvent