ChilliCream · michaelstaib · Mar 30, 2026 · Mar 29, 2026 · Mar 29, 2026 · Mar 29, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,238 +1,86 @@
 # AGENTS.md - OpenAI Codex Configuration
 
-This file provides guidance to OpenAI Codex and other AI coding agents when working with this repository.
+This file provides guidance to OpenAI Codex and other coding agents when working with this repository.
 
-## Project Summary
+## Build
 
-**ChilliCream GraphQL Platform** - A comprehensive GraphQL ecosystem for .NET
+### Website
 
-| Product         | Description                                            |
-| --------------- | ------------------------------------------------------ |
-| Hot Chocolate   | GraphQL server framework                               |
-| Strawberry Shake| Type-safe GraphQL client                               |
-| Green Donut     | Data fetching primitives (DataLoader, pagination, etc.)|
-| Nitro           | GraphQL IDE                                            |
-
-## Setup Instructions
-
-### Using Devcontainer (Recommended)
-
-This repository includes a devcontainer (`.devcontainer/`) with everything pre-installed:
-
-- .NET SDKs 6, 7, 8, 9, 10
-- Node.js LTS + Yarn
-- GitHub CLI + Azure CLI
-- Docker-in-docker support
-
-The devcontainer automatically runs `init.sh` on creation - no manual setup needed.
-
-### Manual Setup
-
-If not using devcontainer, initialize first:
+Use `yarn` instead of `npm`.
 
 ```bash
-./init.sh
+cd website
+yarn
 ```
 
-This restores website packages (yarn) and .NET packages.
-
-### Build
-
-```bash
-./build.sh compile
-```
+### C# Source Code
 
-### Test
+Build full solution:
 
 ```bash
-./build.sh test
+dotnet build src/All.slnx
 ```
 
-### Single Project Build
+Build or test a subset directly (each area has its own solution file):
 
 ```bash
-dotnet build src/HotChocolate/Core/src/Types/HotChocolate.Types.csproj
-```
-
-## Repository Layout
-
-```text
-src/All.slnx                   # Master solution (244 projects)
-
-src/HotChocolate/              # GraphQL Server
-  Core/
-    Abstractions/              # Interfaces, contracts
-    Execution/                 # Query execution
-    Types/                     # Type system
-    Validation/                # Query validation
-    Subscriptions/             # Real-time updates
-  AspNetCore/                  # HTTP integration
-  Language/                    # Parser, syntax tree
-  Fusion/                      # Distributed GraphQL
-  Data/                        # Database integrations
-
-src/GreenDonut/                # Data fetching primitives
-src/StrawberryShake/           # GraphQL client
-src/CookieCrumble/             # Snapshot testing
-
-website/                       # Documentation (Next.js)
-templates/                     # Project templates
-.build/                        # Build scripts (Nuke)
+dotnet test src/HotChocolate/Fusion
 ```
 
-## Tech Stack
-
-| Component | Technology      |
-| --------- | --------------- |
-| Runtime   | .NET 8/9/10     |
-| SDK       | 10.0.102        |
-| Build     | Nuke.Build      |
-| Tests     | xUnit           |
-| Snapshots | CookieCrumble   |
-| Docs      | Next.js + React |
-
-## Coding Standards
+## Orchestration
 
-### C# Conventions
+- You are the orchestrator, not the worker.
+- Keep the main context window focused on decisions.
+- Do not do work yourself that a subagent could do.
+- Context-window discipline: when instructed to "let it cook" or "don't inspect", trust the subagent and do not re-read its output.
+- For non-trivial work, minimum team composition is lead developer plus devil's advocate.
 
-- File-scoped namespaces: `namespace HotChocolate.Types;`
-- 4-space indentation
-- Use records for immutable types
-- Expression-bodied members preferred
-- No trailing whitespace
+## Verification
 
-### Naming Conventions
+- "Done" means the code compiles, tests pass, and results are verified by running relevant tests.
+- Never mark work complete without proving it works.
+- During iteration, use `--filter` and avoid running the full suite unnecessarily.
 
-- Projects: `HotChocolate.{Feature}`
-- Tests: `HotChocolate.{Feature}.Tests`
-- Interfaces: `I{Name}` prefix
-- Async methods: `{Name}Async` suffix
+## Core Principles
 
-### File Organization
+- Simplicity first: make every change as simple as possible and keep impact minimal.
+- No lazy fixes: find root causes and avoid temporary patches.
+- Minimal impact: touch only what is necessary and avoid regressions.
 
-- One type per file (generally)
-- Test files mirror source structure
-- Snapshots in `__snapshots__/` folders
+## Code Quality
 
-## Testing Guidelines
+### C# / .NET
 
-### Running Tests
+- Always use curly braces for loops and conditionals.
+- Use file-scoped namespaces and 4-space indentation.
+- Use test naming format: `Method_Should_Outcome_When_Condition`.
+- Do not write vacuous assertions (`Assert.NotNull` alone is not a complete test).
+- If a test requires excessive stubs and reflection, use a more appropriate test tier.
 
-```bash
-# All tests
-./build.sh test
-
-# Specific project
-dotnet test src/HotChocolate/Core/test/Types.Tests/
+### Testing
 
-# Specific test
-dotnet test --filter "FullyQualifiedName~MyTestName"
-```
+- Prefer snapshot tests over manual `Assert` calls using CookieCrumble.
+- Use CookieCrumble native snapshot support for `IExecutionResult`, `GraphQLHttpResponse`, and related core types.
+- For small snapshots, prefer inline snapshots (`MatchInlineSnapshot`).
+- For tests with multiple assertions, use markdown snapshots (`MatchMarkdownSnapshot`).
+- For snapshot updates, use `__mismatch__/` and understand ordering issues before updating snapshots.
+- Filter tests during iteration and avoid full-suite runs unless necessary.
+- Use real databases in integration tests instead of mocks unless explicitly instructed otherwise.
 
-### Snapshot Testing
+## Performance
 
-- Uses CookieCrumble library
-- Snapshots stored in `__snapshots__/`
-- Update snapshots by deleting old file and re-running test
+### C# / .NET
 
-### Test Structure
+This is framework code. Performance matters; optimize for low allocations on hot paths.
 
-```csharp
-[Fact]
-public async Task MyFeature_Should_WorkCorrectly()
-{
-    // Arrange
-    var schema = await new ServiceCollection()
-        .AddGraphQL()
-        .AddQueryType<Query>()
-        .BuildSchemaAsync();
+- Use `ChunkedArrayWriter` or `PooledArrayWriter` when an in-memory `IBufferWriter<byte>` is required.
 
-    // Act
-    var result = await schema.ExecuteAsync("{ field }");
-
-    // Assert
-    result.MatchSnapshot();
-}
-```
+## Tools
 
-## Key Abstractions
+### C# / .NET
 
-### GraphQL Types
+Use `dotnet` CLI to search NuGet packages, for example:
 
-```csharp
-public class BookType : ObjectType<Book>
-{
-    protected override void Configure(IObjectTypeDescriptor<Book> descriptor)
-    {
-        descriptor.Field(b => b.Title).Type<NonNullType<StringType>>();
-    }
-}
-```
-
-### DataLoader
-
-```csharp
-public class BookByIdDataLoader : BatchDataLoader<int, Book>
-{
-    protected override async Task<IReadOnlyDictionary<int, Book>> LoadBatchAsync(
-        IReadOnlyList<int> keys, CancellationToken ct)
-    {
-        // Batch load implementation
-    }
-}
-```
-
-### Resolvers
-
-```csharp
-public class Query
-{
-    public Book GetBook([Service] IBookRepository repo, int id)
-        => repo.GetById(id);
-}
+```bash
+dotnet package search HotChocolate
 ```
-
-## Important Paths
-
-| Path                 | Purpose              |
-| -------------------- | -------------------- |
-| `src/All.slnx`       | Open this in IDE     |
-| `global.json`        | .NET SDK version     |
-| `.editorconfig`      | Code style rules     |
-| `.build/Build.csproj`| Build configuration  |
-| `website/`           | Documentation source |
-
-## Common Modifications
-
-### Add New Type Extension
-
-1. Create in `src/HotChocolate/Core/src/Types/Types/`
-2. Add tests in `src/HotChocolate/Core/test/Types.Tests/`
-3. Export from appropriate namespace
-
-### Add Database Integration
-
-1. Create project in `src/HotChocolate/Data/`
-2. Reference `HotChocolate.Execution`
-3. Implement `IQueryableExecutable` or similar
-
-### Modify Execution Pipeline
-
-1. Changes go in `src/HotChocolate/Core/src/Execution/`
-2. Middleware in `Processing/` directory
-3. Add tests covering the pipeline stage
-
-## Troubleshooting
-
-| Issue             | Solution                                   |
-| ----------------- | ------------------------------------------ |
-| Build fails       | Run `./init.sh` first                      |
-| Missing packages  | Run `./build.sh restore`                   |
-| Snapshot mismatch | Check `__snapshots__/` for expected output |
-| SDK not found     | Install .NET SDK 10.0.102                  |
-
-## Links
-
-- Documentation: `website/src/docs/`
-- Examples: `templates/`
-- Build scripts: `.build/`
diff --git a/src/All.slnx b/src/All.slnx
@@ -73,6 +73,7 @@
   </Folder>
   <Folder Name="/HotChocolate/Caching/" />
   <Folder Name="/HotChocolate/Caching/src/">
+    <Project Path="HotChocolate/Caching/src/Caching.Core/HotChocolate.Caching.Core.csproj" />
     <Project Path="HotChocolate/Caching/src/Caching.Memory/HotChocolate.Caching.Memory.csproj" />
     <Project Path="HotChocolate/Caching/src/Caching/HotChocolate.Caching.csproj" />
   </Folder>
@@ -213,6 +214,7 @@
     <Project Path="HotChocolate/Fusion/src/Fusion.Aspire/HotChocolate.Fusion.Aspire.csproj" />
     <Project Path="HotChocolate/Fusion/src/Fusion.AspNetCore/HotChocolate.Fusion.AspNetCore.csproj" />
     <Project Path="HotChocolate/Fusion/src/Fusion.Composition/HotChocolate.Fusion.Composition.csproj" />
+    <Project Path="HotChocolate/Fusion/src/Fusion.Caching/HotChocolate.Fusion.Caching.csproj" />
     <Project Path="HotChocolate/Fusion/src/Fusion.Diagnostics/HotChocolate.Fusion.Diagnostics.csproj" />
     <Project Path="HotChocolate/Fusion/src/Fusion.Execution.Types/HotChocolate.Fusion.Execution.Types.csproj" />
     <Project Path="HotChocolate/Fusion/src/Fusion.Connectors.InMemory/HotChocolate.Fusion.Connectors.InMemory.csproj" />
@@ -226,6 +228,7 @@
     <Project Path="HotChocolate/Fusion/test/Fusion.AspNetCore.Tests/HotChocolate.Fusion.AspNetCore.Tests.csproj" />
     <Project Path="HotChocolate/Fusion/test/Fusion.Composition.Tests/HotChocolate.Fusion.Composition.Tests.csproj" />
     <Project Path="HotChocolate/Fusion/test/Fusion.Connectors.InMemory.Tests/HotChocolate.Fusion.Connectors.InMemory.Tests.csproj" />
+    <Project Path="HotChocolate/Fusion/test/Fusion.Caching.Tests/HotChocolate.Fusion.Caching.Tests.csproj" />
     <Project Path="HotChocolate/Fusion/test/Fusion.Diagnostics.Tests/HotChocolate.Fusion.Diagnostics.Tests.csproj" />
     <Project Path="HotChocolate/Fusion/test/Fusion.EventSources.Tests/HotChocolate.Fusion.EventSources.Tests.csproj" />
     <Project Path="HotChocolate/Fusion/test/Fusion.Execution.Tests/HotChocolate.Fusion.Execution.Tests.csproj" />

diff --git a/src/HotChocolate/Caching/HotChocolate.Caching.slnx b/src/HotChocolate/Caching/HotChocolate.Caching.slnx
@@ -2,6 +2,9 @@
   <Folder Name="/src/">
     <Project Path="src/Caching/HotChocolate.Caching.csproj" />
   </Folder>
+  <Folder Name="/src/Caching.Core/">
+    <Project Path="src/Caching.Core/HotChocolate.Caching.Core.csproj" />
+  </Folder>
   <Folder Name="/src/Caching.Memory/">
     <Project Path="src/Caching.Memory/HotChocolate.Caching.Memory.csproj" />
   </Folder>