### Run Example Project

Source: https://github.com/epicgames/lore-dotnet/blob/main/README.md

Execute the example project to test the C# SDK. This command runs the default example project.

```bash
dotnet run --project examples/example/example.csproj
```

--------------------------------

### Run Online Examples

Source: https://github.com/epicgames/lore-dotnet/blob/main/examples/README.md

Execute the C# SDK examples in online mode against a local Lore server. This pushes revisions and clones repositories.

```bash
dotnet run --project examples/example -- lore://localhost
dotnet run --project examples/example-native -- lore://localhost
```

--------------------------------

### Start Local Lore Server

Source: https://github.com/epicgames/lore-dotnet/blob/main/examples/README.md

Start the Lore server in release mode with logging enabled. The output is piped to a log file.

```bash
RUST_LOG=info ./target/release/loreserver 2>&1 | tee /tmp/lore.log
```

--------------------------------

### Install Development Tooling

Source: https://github.com/epicgames/lore-dotnet/blob/main/README.md

Install the necessary development tooling for the project using uv pip.

```bash
uv pip install --group dev
```

--------------------------------

### Run Offline Examples

Source: https://github.com/epicgames/lore-dotnet/blob/main/examples/README.md

Execute the C# SDK examples in offline mode. This creates a local repository and commits files without any network operations.

```bash
dotnet run --project examples/example
dotnet run --project examples/example-native
```

--------------------------------

### Initialize LoreStoragePutItem

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/types-and-enums.md

Example of instantiating a LoreStoragePutItem for a write operation.

```csharp
var item = new LoreStoragePutItem
{
    Id = 1UL,
    Partition = new LorePartition(partitionBytes),
    Context = new LoreContext(contextBytes),
    Data = payloadBytes,
    RemoteWrite = false
};
```

--------------------------------

### Perform Global Setup

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/INDEX.md

Global configuration for logging and registering callbacks that persist across operations.

```csharp
Lore.LogConfigure(new LoreLogConfig { ... });   // Configure logging
var callback = Lore.GlobalCallback(tag, fn);   // Global callback
callback.Dispose();                             // Unregister
```

--------------------------------

### Pushing a Branch Example

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/operations-reference.md

Demonstrates how to initialize global arguments and execute a branch push operation.

```csharp
using var globalArgs = new LoreGlobalArgs 
{ 
    RepositoryPath = "/tmp/my-repo", 
    Offline = false 
};

var result = Lore.BranchPush(globalArgs, new LoreBranchPushArgs()).Wait();
Console.WriteLine("Push complete");
```

--------------------------------

### Initialize LoreAddress

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/types-and-enums.md

Example of creating a new LoreAddress instance.

```csharp
var address = new LoreAddress
{
    Hash = new LoreHash(hashBytes),
    Context = new LoreContext(contextBytes)
};
```

--------------------------------

### LoreHash Usage Example

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/types-and-enums.md

Demonstrates instantiation of a LoreHash and conversion to a hex string.

```csharp
var hashBytes = new byte[32] { /* 32 bytes */ };
var hash = new LoreHash(hashBytes);
Console.WriteLine(Convert.ToHexString(hash.Data));  // e.g., "a1b2c3d4..."
```

--------------------------------

### Create Repository Example

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/quick-start.md

Initialize a repository with logging configuration and global arguments. Ensure the repository path and URL are correctly specified.

```csharp
using LoreVcs;
using LoreVcs.Types;
using LoreVcs.Types.Args;
using LoreVcs.Types.Enums;

// Configure logging
Lore.LogConfigure(new LoreLogConfig 
{ 
    File = true, 
    FilePath = "./logs" 
});

// Create global arguments
using var globalArgs = new LoreGlobalArgs 
{ 
    RepositoryPath = "/path/to/repo",
    Offline = true 
};

// Create a new repository
using var repoArgs = new LoreRepositoryCreateArgs 
{ 
    RepositoryUrl = "my-repo" 
};

try
{
    int result = Lore.RepositoryCreate(globalArgs, repoArgs).Wait();
    Console.WriteLine($"Repository created: {result}");
}
catch (LoreError ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}
```

--------------------------------

### Install Development Dependencies and Run Build Scripts

Source: https://github.com/epicgames/lore-dotnet/blob/main/CONTRIBUTING.md

Install development dependencies using uv and execute build scripts for code generation. These commands are essential for preparing the project for packaging.

```shell
uv pip install --group dev
```

```shell
uv run python find_lorelib.py
```

```shell
uv run python generator/generate.py
```

```shell
uv run python generator/generate_runtime_json.py
```

--------------------------------

### Copy Local Server Configuration

Source: https://github.com/epicgames/lore-dotnet/blob/main/examples/README.md

Copy the example local configuration file for the Lore server.

```bash
cp lore-server/config/local.toml.example lore-server/config/local.toml
```

--------------------------------

### LoreContext Usage Example

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/types-and-enums.md

Demonstrates instantiation of a LoreContext.

```csharp
var contextBytes = new byte[16] { /* 16 bytes */ };
var context = new LoreContext(contextBytes);
```

--------------------------------

### Initialize LoreGlobalArgs

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/types-and-enums.md

Example of initializing the global arguments structure with a repository path and offline status.

```csharp
using var globalArgs = new LoreGlobalArgs
{
    RepositoryPath = "/home/user/projects/my-repo",
    Offline = false
};
```

--------------------------------

### Install CSharpier for Code Formatting

Source: https://github.com/epicgames/lore-dotnet/blob/main/CONTRIBUTING.md

Install the CSharpier code formatter globally for the project. This ensures consistent code style across all contributions.

```shell
dotnet new tool-manifest
```

```shell
dotnet tool install csharpier
```

--------------------------------

### LoreRevisionCommit Usage Example

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Demonstrates how to initialize commit arguments and execute the commit operation.

```csharp
using var commitArgs = new LoreRevisionCommitArgs { Message = "Initial commit" };
int result = LoreRevisionCommit(globalArgs, commitArgs, callback);
```

--------------------------------

### Initialize LoreHashArray

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/types-and-enums.md

Example of initializing a LoreHashArray with a collection of LoreHash objects.

```csharp
var hashes = new LoreHashArray(new[]
{
    new LoreHash(hash1),
    new LoreHash(hash2)
});
```

--------------------------------

### Configure Lore Logging

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/types-and-enums.md

Example of applying a logging configuration to the Lore system.

```csharp
Lore.LogConfigure(new LoreLogConfig
{
    File = true,
    FilePath = "/var/log/lore",
    Level = LoreLogLevel.DEBUG
});
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/epicgames/lore-dotnet/blob/main/README.md

Set up a Python virtual environment for managing project dependencies. Activate it before installing development tools.

```bash
uv venv .venv
source .venv/bin/activate
```

--------------------------------

### Configure LoreGlobalArgs for online and offline modes

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Examples of initializing global arguments for network-enabled or local-only repository operations.

```csharp
using var globalArgs = new LoreGlobalArgs
{
    RepositoryPath = "/home/user/myproject",
    Offline = false  // Allow network operations
};
```

```csharp
using var globalArgs = new LoreGlobalArgs
{
    RepositoryPath = "/home/user/myproject",
    Offline = true  // Only local operations
};
```

--------------------------------

### Manage LoreStore handle

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/types-and-enums.md

Example of obtaining a handle from an event and using it to close storage.

```csharp
ulong handleId = 0;
var events = Lore.StorageOpen(globalArgs, openArgs)
    .Callback((evt, ctx) =>
    {
        if (evt.Tag == LoreEventTag.STORAGE_OPENED)
        {
            handleId = evt.GetData<LoreStorageOpenedEventDataFFI>().HandleId;
        }
    })
    .Collect();

var closeArgs = new LoreStorageCloseArgs { Handle = new LoreStore(handleId) };
Lore.StorageClose(globalArgs, closeArgs).Wait();
```

--------------------------------

### Initialize Lore Operation

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/INDEX.md

The entry point for starting any operation within the Lore SDK.

```csharp
// All operations start here
var executor = Lore.OperationName(globalArgs, args);
```

--------------------------------

### Initialize temporary repository configuration

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Setup for a temporary repository path using a unique directory, typically used for isolated operations.

```csharp
string tempDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString());
Directory.CreateDirectory(tempDir);

using var globalArgs = new LoreGlobalArgs
{
    RepositoryPath = tempDir,
    Offline = true
};
var result = Lore.RepositoryCreate(globalArgs, repoArgs).Wait();
```

--------------------------------

### Install LoreVcs NuGet Package

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/quick-start.md

Add the LoreVcs dependency to a specific .NET project.

```bash
dotnet add package LoreVcs --project /path/to/project.csproj
```

--------------------------------

### Minimal Lore C# SDK Example

Source: https://github.com/epicgames/lore-dotnet/blob/main/README.md

Demonstrates basic usage of the Lore C# SDK's fluent API for checking repository status and logging.

```csharp
using LoreVcs;
using LoreVcs.Types;
using LoreVcs.Types.Args;
using LoreVcs.Types.Enums;
using LoreVcs.Types.Events;

var globalArgs = new LoreGlobalArgs { RepositoryPath = "/path/to/local/repository" };
var statusArgs = new LoreRepositoryStatusArgs { Staged = true, Scan = true };

Lore.LogConfigure(new LoreLogConfig { File = true, FilePath = "/path/to/log/directory", Level = LoreLogLevel.DEBUG });

Lore.RepositoryStatus(globalArgs, statusArgs)
    .Callback((evt, ctx) =>
    {
        if (evt.Tag == LoreEventTag.REPOSITORY_STATUS_FILE)
        {
            var statusEvent = evt.GetData<LoreRepositoryStatusFileEventDataFFI>();
            Console.WriteLine(statusEvent.Path);
        }
    })
    .Wait();
```

--------------------------------

### File Stage Arguments Structure and Usage

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Defines the structure for staging files and provides an example of its usage.

```csharp
public struct LoreFileStageArgs : IDisposable
{
    public string[] Paths { get; set; }
}
```

```csharp
using var stageArgs = new LoreFileStageArgs
{
    Paths = new[] { "src/main.cs", "src/utils.cs", "data/assets.bin" }
};
int result = Lore.FileStage(globalArgs, stageArgs).Wait();
```

--------------------------------

### Initialize in-memory storage

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Example usage of LoreStorageOpenArgs to create an in-memory storage instance and handle the resulting event.

```csharp
var openArgs = new LoreStorageOpenArgs { InMemory = true };
var events = Lore.StorageOpen(globalArgs, openArgs)
    .Callback((evt, ctx) =>
    {
        if (evt.Tag == LoreEventTag.STORAGE_OPENED)
        {
            var handleId = evt.GetData<LoreStorageOpenedEventDataFFI>().HandleId;
            // Use handleId with Put/Get operations
        }
    })
    .Collect();
```

--------------------------------

### Access LoreMetadata variants

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/types-and-enums.md

Example of switching on the metadata tag to access the correct property.

```csharp
var metadata = /* ... received from event ... */;
switch (metadata.Tag)
{
    case LoreMetadataType.ADDRESS:
        var addr = metadata.Address;
        break;
    case LoreMetadataType.NUMERIC:
        var num = metadata.Numeric;
        break;
    case LoreMetadataType.STRING:
        var str = metadata.String;
        break;
}
```

--------------------------------

### Add Lore C# SDK Package

Source: https://github.com/epicgames/lore-dotnet/blob/main/README.md

Installs the stable release of the Lore C# SDK package to your project.

```bash
dotnet add package LoreVcs --project /<path-to>/project.csproj
```

--------------------------------

### Clone Lore C# SDK Repository

Source: https://github.com/epicgames/lore-dotnet/blob/main/README.md

Clone the official Lore C# SDK repository to start development.

```bash
git clone https://github.com/EpicGames/lore-dotnet
```

--------------------------------

### Basic Repository Creation Pattern

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/README.md

Initializes a repository using global arguments and creation arguments.

```csharp
using var globalArgs = new LoreGlobalArgs { RepositoryPath = path };
using var args = new LoreRepositoryCreateArgs { RepositoryUrl = url };
int result = Lore.RepositoryCreate(globalArgs, args).Wait();
```

--------------------------------

### Create repository with async/await

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/quick-start.md

Demonstrates the standard asynchronous pattern for repository creation with error handling.

```csharp
async Task CreateRepositoryAsync(string path)
{
    using var globalArgs = new LoreGlobalArgs 
    { 
        RepositoryPath = path,
        Offline = true 
    };
    using var repoArgs = new LoreRepositoryCreateArgs { RepositoryUrl = "repo" };
    
    try
    {
        int result = await Lore.RepositoryCreate(globalArgs, repoArgs).WaitAsync();
        Console.WriteLine("Success");
    }
    catch (LoreError ex)
    {
        Console.WriteLine($"Error: {ex.Message}");
    }
}

// Call it
await CreateRepositoryAsync("/path/to/repo");
```

--------------------------------

### Initialize Repository with Lore.RepositoryCreate

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/operations-reference.md

Creates a new repository at the specified path. Requires a path that does not yet exist.

```csharp
public static LoreExecutor<LoreRepositoryCreateArgs> RepositoryCreate(
    in LoreGlobalArgs globalArgs,
    in LoreRepositoryCreateArgs args
)
```

```csharp
using var globalArgs = new LoreGlobalArgs { RepositoryPath = "/tmp/my-repo", Offline = true };
using var repoArgs = new LoreRepositoryCreateArgs { RepositoryUrl = "my-repo" };

try
{
    int result = Lore.RepositoryCreate(globalArgs, repoArgs).Wait();
    Console.WriteLine("Repository created successfully");
}
catch (LoreError ex)
{
    Console.WriteLine($"Failed: {ex.Message}");
}
```

--------------------------------

### Create temporary repositories for testing

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/quick-start.md

Initialize a repository in a temporary directory and ensure cleanup after test completion.

```csharp
string tempDir = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString());
Directory.CreateDirectory(tempDir);

using var globalArgs = new LoreGlobalArgs 
{ 
    RepositoryPath = tempDir,
    Offline = true 
};

using var repoArgs = new LoreRepositoryCreateArgs { RepositoryUrl = "test-repo" };
Lore.RepositoryCreate(globalArgs, repoArgs).Wait();

// Use repository for testing
Console.WriteLine($"Test repo at: {tempDir}");

// Cleanup
Directory.Delete(tempDir, recursive: true);
```

--------------------------------

### Create a Lore Repository

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Initializes a new repository using global arguments and a callback for event handling.

```csharp
public unsafe static int LoreRepositoryCreate(
    in LoreGlobalArgs globals,
    in LoreRepositoryCreateArgs args,
    LoreEventCallbackConfig callback
)
```

```csharp
using static LoreVcs.Interop.Native;

var globalArgs = new LoreGlobalArgs 
{ 
    RepositoryPath = "/path/to/repo", 
    Offline = true 
};
var repoArgs = new LoreRepositoryCreateArgs { RepositoryUrl = "my-repo" };

void EventHandler(LoreEventFFI loreEvent, ulong userContext)
{
    if (loreEvent.Tag == LoreEventTag.REPOSITORY_CREATE)
    {
        var data = loreEvent.GetData<LoreRepositoryCreateEventDataFFI>();
        Console.WriteLine($"Repository created: {data.Name}");
    }
}

var callback = new LoreEventCallbackConfig 
{
    Func = (delegate* unmanaged[Cdecl]<_LoreEvent*, ulong, void>)Marshal.GetFunctionPointerForDelegate(
        new LoreCallback(EventHandler)
    ),
    UserContext = 0
};

int result = LoreRepositoryCreate(globalArgs, repoArgs, callback);
if (result != 0)
{
    Console.WriteLine($"Repository creation failed with code {result}");
}
```

--------------------------------

### LoreStorageGetItemArray Class Definition

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/types-and-enums.md

Definition for the LoreStorageGetItemArray class, which manages an array of storage get items.

```csharp
public sealed class LoreStorageGetItemArray : IDisposable
{
    public LoreStorageGetItemArray(LoreStorageGetItem[] input)
    public void Dispose()
}
```

--------------------------------

### Revision Commit Arguments Structure and Usage

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Defines the structure for committing revisions and provides an example of its usage.

```csharp
public struct LoreRevisionCommitArgs : IDisposable
{
    public string Message { get; set; }
}
```

```csharp
using var commitArgs = new LoreRevisionCommitArgs
{
    Message = "Add new asset compression feature"
};
int result = Lore.RevisionCommit(globalArgs, commitArgs).Wait();
```

--------------------------------

### Manage Branches

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/quick-start.md

Demonstrates creating, listing, and switching between repository branches.

```csharp
// Create a branch
using var createBranchArgs = new LoreBranchCreateArgs { Name = "feature/new" };
Lore.BranchCreate(globalArgs, createBranchArgs).Wait();

// List branches
var events = Lore.BranchList(globalArgs, new LoreBranchListArgs()).Collect();
foreach (var ev in events.OfType<LoreBranchListEventData>())
{
    Console.WriteLine($"Branch: {ev.Name} ({ev.Location})");
}

// Switch to the branch
using var switchArgs = new LoreBranchSwitchArgs { Name = "feature/new" };
Lore.BranchSwitch(globalArgs, switchArgs).Wait();
```

--------------------------------

### LoreStorageOpenArgs

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Arguments for initializing a storage instance.

```APIDOC
## LoreStorageOpenArgs

### Description
Defines the configuration for opening a storage repository.

### Properties
- **RepositoryPath** (string) - Optional - Path to storage directory.
- **InMemory** (bool) - Optional - When true, creates an in-memory storage instance.
```

--------------------------------

### Lore.StorageOpen()

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/operations-reference.md

Opens or creates a storage instance for reading and writing data.

```APIDOC
## Lore.StorageOpen()

### Description
Opens or creates a storage instance for reading and writing data. Returns a handle ID required for subsequent storage operations.

### Signature
`public static LoreExecutor<LoreStorageOpenArgs> StorageOpen(in LoreGlobalArgs globalArgs, in LoreStorageOpenArgs args)`

### Parameters
- **args.InMemory** (bool) - Required - If true, creates an in-memory store (does not persist).
- **args.RepositoryPath** (string) - Optional - Path to persistent storage if InMemory is false.

### Events Emitted
- **STORAGE_OPENED** - Storage opened, includes handle ID.
- **LOG** - Open progress.
- **COMPLETE** - Operation complete (0 = success).
- **END** - Final event.
```

--------------------------------

### Lore.RepositoryCreate()

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/operations-reference.md

Initializes a new repository at the specified path.

```APIDOC
## Lore.RepositoryCreate()

### Description
Initializes a new repository at the path specified in globalArgs.RepositoryPath.

### Parameters
- **globalArgs** (LoreGlobalArgs) - Required - Must include a valid RepositoryPath that does not yet exist.
- **args.RepositoryUrl** (string) - Required - Identifier or remote URL for the repository.

### Throws
- LoreError if path already exists or creation fails.
```

--------------------------------

### LoreStorageOpen

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Opens or creates a storage instance.

```APIDOC
## LoreStorageOpen

### Description
Opens or creates a storage instance. Emits `STORAGE_OPENED` event with a handle ID.

### Signature
`public unsafe static int LoreStorageOpen(in LoreGlobalArgs globals, in LoreStorageOpenArgs args, LoreEventCallbackConfig callback)`
```

--------------------------------

### Initialize Logging

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Configure logging early in the application lifecycle to capture diagnostic information.

```csharp
class Program
{
    static void Main()
    {
        Lore.LogConfigure(new LoreLogConfig
        {
            File = true,
            FilePath = "./logs",
            Level = LoreLogLevel.INFO
        });
        
        // Now perform Lore operations
    }
}
```

--------------------------------

### Display SDK File Structure

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/INDEX.md

Visual representation of the documentation directory layout.

```text
/output/
├── INDEX.md (this file)
├── overview.md
├── quick-start.md
├── fluent-api.md
├── native-api.md
├── operations-reference.md
├── types-and-enums.md
├── configuration.md
├── error-handling.md
└── api-design-patterns.md
```

--------------------------------

### Create and Commit in Lore

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/quick-start.md

Initializes a repository, stages a file, and commits changes. Requires a configured LoreGlobalArgs instance.

```csharp
// Create repository
using var globalArgs = new LoreGlobalArgs 
{ 
    RepositoryPath = "./my-repo",
    Offline = true 
};

using var createArgs = new LoreRepositoryCreateArgs { RepositoryUrl = "my-repo" };
Lore.RepositoryCreate(globalArgs, createArgs).Wait();

// Create and stage a file
string filePath = "./my-repo/file.txt";
File.WriteAllText(filePath, "Hello, Lore!");

// Stage the file
using var stageArgs = new LoreFileStageArgs { Paths = new[] { "file.txt" } };
Lore.FileStage(globalArgs, stageArgs).Wait();

// Commit
using var commitArgs = new LoreRevisionCommitArgs { Message = "Initial commit" };
Lore.RevisionCommit(globalArgs, commitArgs).Wait();

Console.WriteLine("Commit complete");
```

--------------------------------

### Open storage instance

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/operations-reference.md

Initializes a storage instance and retrieves a handle ID from the STORAGE_OPENED event. Must call StorageClose before exiting.

```csharp
public static LoreExecutor<LoreStorageOpenArgs> StorageOpen(
    in LoreGlobalArgs globalArgs,
    in LoreStorageOpenArgs args
)
```

```csharp
ulong handleId = 0;
var events = Lore.StorageOpen(globalArgs, new LoreStorageOpenArgs { InMemory = true })
    .Callback((evt, ctx) =>
    {
        if (evt.Tag == LoreEventTag.STORAGE_OPENED)
        {
            handleId = evt.GetData<LoreStorageOpenedEventDataFFI>().HandleId;
        }
    })
    .Collect();

Console.WriteLine($"Storage opened with handle: {handleId}");
```

--------------------------------

### Handle Repository Path Existence

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/error-handling.md

Logic to verify if a repository path exists and create it if missing, or use the existing one.

```csharp
if (!Directory.Exists(globalArgs.RepositoryPath))
{
    Console.WriteLine("Repository path does not exist; creating...");
    Directory.CreateDirectory(globalArgs.RepositoryPath);
    Lore.RepositoryCreate(globalArgs, repoArgs).Wait();
}
else
{
    // Use existing repository
}
```

```csharp
if (Directory.Exists(globalArgs.RepositoryPath))
{
    // Use existing repository
    Lore.RepositoryStatus(globalArgs, statusArgs).Wait();
}
else
{
    // Create new repository
    Lore.RepositoryCreate(globalArgs, repoArgs).Wait();
}
```

--------------------------------

### Create a new branch with Lore.BranchCreate

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/operations-reference.md

Initializes a new branch using LoreBranchCreateArgs.

```csharp
public static LoreExecutor<LoreBranchCreateArgs> BranchCreate(
    in LoreGlobalArgs globalArgs,
    in LoreBranchCreateArgs args
)
```

```csharp
using var branchArgs = new LoreBranchCreateArgs { Name = "feature/new-feature" };
var result = Lore.BranchCreate(globalArgs, branchArgs).Wait();
```

--------------------------------

### Pack Runtime and Core SDK Projects

Source: https://github.com/epicgames/lore-dotnet/blob/main/CONTRIBUTING.md

Package the Lore Runtime and the main Lore SDK projects into release artifacts. This step is necessary before publishing or distributing the libraries.

```shell
dotnet pack -c Release LoreVcs.Runtime/LoreVcs.Runtime.csproj
```

```shell
dotnet pack -c Release LoreVcs/LoreVcs.csproj
```

--------------------------------

### LoreStorageOpen Function Signature

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Defines the signature for opening or creating a storage instance.

```csharp
public unsafe static int LoreStorageOpen(
    in LoreGlobalArgs globals,
    in LoreStorageOpenArgs args,
    LoreEventCallbackConfig callback
)
```

--------------------------------

### Manage Resources

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/INDEX.md

Use the using statement to ensure proper disposal of global and repository arguments.

```csharp
using var globalArgs = new LoreGlobalArgs { ... };
using var args = new LoreRepositoryCreateArgs { ... };
// Automatically disposed at end of block
```

--------------------------------

### Implement a Global Logging Callback

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/fluent-api.md

Demonstrates registering a global callback for log events and managing its lifecycle using IDisposable.

```csharp
using var logSubscription = Lore.GlobalCallback(LoreEventTag.LOG,
    (evt, ctx) =>
    {
        var logData = evt.GetData<LoreLogEventDataFFI>();
        Console.WriteLine($"[{logData.Level}] {logData.Message}");
    });

// Perform operations; log events are printed automatically
var result = Lore.RepositoryCreate(globalArgs, repoArgs).Wait();

// Unregister when exiting scope
```

--------------------------------

### Run Project with Runtime Identifier

Source: https://github.com/epicgames/lore-dotnet/blob/main/README.md

Executes the .NET project, specifying the runtime identifier on the command line.

```bash
dotnet run --project /<path-to>/project.csproj -r <runtime-identifier>
```

--------------------------------

### Handle Environment-Specific Configuration

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Retrieve configuration values from environment variables with fallback defaults.

```csharp
var repoPath = Environment.GetEnvironmentVariable("LORE_REPO_PATH") 
    ?? "./default-repo";
var offline = bool.TryParse(
    Environment.GetEnvironmentVariable("LORE_OFFLINE"), 
    out var o) ? o : false;

using var globalArgs = new LoreGlobalArgs
{
    RepositoryPath = repoPath,
    Offline = offline
};
```

--------------------------------

### Repository Creation Arguments Structure

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Defines the structure for repository creation operations.

```csharp
public struct LoreRepositoryCreateArgs : IDisposable
{
    public string RepositoryUrl { get; set; }
```

--------------------------------

### Async Operation Pattern

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/README.md

Executes repository creation asynchronously and handles potential LoreError exceptions.

```csharp
try
{
    int result = await Lore.RepositoryCreate(globalArgs, args).WaitAsync();
}
catch (LoreError ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}
```

--------------------------------

### Project Documentation Directory Structure

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/MANIFEST.md

Displays the file hierarchy of the generated documentation workspace.

```text
/workspace/home/output/
├── README.md ........................ Entry point and overview
├── MANIFEST.md ...................... This file (generation report)
├── INDEX.md ......................... Navigation hub and task index
├── overview.md ...................... Architecture and introduction
├── quick-start.md ................... Getting started guide
├── fluent-api.md .................... Main API reference
├── native-api.md .................... FFI reference
├── operations-reference.md .......... All operations
├── types-and-enums.md ............... Type system
├── configuration.md ................. Configuration options
├── error-handling.md ................ Error handling patterns
└── api-design-patterns.md ........... Design architecture
```

--------------------------------

### Generate C# Bindings

Source: https://github.com/epicgames/lore-dotnet/blob/main/README.md

Generate the C# bindings from the Lore C library. Ensure LORE_BUILD_PATH is set before running these commands.

```bash
uv run python find_lorelib.py
uv run python generator/generate.py
```

--------------------------------

### Set Lore Build Path (Pre-built)

Source: https://github.com/epicgames/lore-dotnet/blob/main/README.md

Set the LORE_BUILD_PATH environment variable to point to the download path of a pre-built Lore C library.

```bash
export LORE_BUILD_PATH="/<path-to>/lore/"
```

--------------------------------

### Clone Lore Repository

Source: https://github.com/epicgames/lore-dotnet/blob/main/examples/README.md

Clone the Lore repository from GitHub to build the server from source.

```bash
git clone https://github.com/EpicGames/lore.git
cd lore
cargo build --release
```

--------------------------------

### LoreLogConfigure

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Configures global logging settings such as file output and log level.

```APIDOC
## LoreLogConfigure

### Description
Configures global logging settings (file output, log level, etc.).

### Signature
`public unsafe static int LoreLogConfigure(LoreLogConfig config)`

### Parameters
- **config** (LoreLogConfig) - Required - Logging configuration

### Returns
- **int** - 0 on success
```

--------------------------------

### Lore.StorageGet()

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/operations-reference.md

Retrieves data from storage by address.

```APIDOC
## Lore.StorageGet()

### Description
Retrieves data from storage using the provided handle and item address.

### Signature
`public static LoreExecutor<LoreStorageGetArgs> StorageGet(in LoreGlobalArgs globalArgs, in LoreStorageGetArgs args)`

### Parameters
- **args.Handle** (LoreStore) - Required - Storage handle obtained from StorageOpen.
- **args.Items** (Array) - Required - Array of items to retrieve (must include address from previous StoragePut).

### Events Emitted
- **STORAGE_GET_DATA** - One or more events with data chunks.
- **STORAGE_GET_ITEM_COMPLETE** - Final event for each item.
- **LOG** - Get progress.
- **COMPLETE** - Operation complete (0 = success).
- **END** - Final event.
```

--------------------------------

### Build Lore C Library

Source: https://github.com/epicgames/lore-dotnet/blob/main/README.md

Build the Lore C library from source. This is required if you are modifying the Lore C/Rust core alongside the C# SDK.

```bash
cargo build --release
```

--------------------------------

### Configure Lore Logging

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Sets global logging parameters such as file path and log level.

```csharp
var logConfig = new LoreLogConfig
{
    FilePath = "/path/to/logs",
    File = true,
    Level = LoreLogLevel.DEBUG
};
int result = LoreLogConfigure(logConfig);
```

--------------------------------

### Configure Operation Execution

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/INDEX.md

Fluent configuration methods for setting callbacks, user context, and event filtering before execution.

```csharp
executor
    .Callback((evt, ctx) => { })        // Per-operation callback
    .UserContext(123)                   // Associate metadata
    .FilterByType([tag1, tag2])         // Filter events
    .Wait();
```

--------------------------------

### LoreRepositoryCreate

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Creates a new repository at the path specified in LoreGlobalArgs.RepositoryPath.

```APIDOC
## LoreRepositoryCreate

### Description
Creates a new repository at the path specified in `LoreGlobalArgs.RepositoryPath`.

### Signature
`public unsafe static int LoreRepositoryCreate(in LoreGlobalArgs globals, in LoreRepositoryCreateArgs args, LoreEventCallbackConfig callback)`

### Parameters
- **globals** (in LoreGlobalArgs) - Required - Global configuration including repository path and offline mode
- **args** (in LoreRepositoryCreateArgs) - Required - Repository creation arguments including the repository URL
- **callback** (LoreEventCallbackConfig) - Required - Callback configuration for event handling

### Returns
- **int** - 0 on success, non-zero on failure
```

--------------------------------

### Manage Resource Disposal

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Ensure proper cleanup of configuration objects using the using statement or explicit try-finally blocks.

```csharp
// Correct: Ensures cleanup
using var globalArgs = new LoreGlobalArgs { RepositoryPath = repoPath, Offline = false };
using var repoArgs = new LoreRepositoryCreateArgs { RepositoryUrl = url };
int result = Lore.RepositoryCreate(globalArgs, repoArgs).Wait();

// Also acceptable: Explicit disposal
var globalArgs = new LoreGlobalArgs { RepositoryPath = repoPath, Offline = false };
try
{
    // Use globalArgs
}
finally
{
    globalArgs.Dispose();
}
```

--------------------------------

### FFI Marshaling Abstraction

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/api-design-patterns.md

Demonstrates the separation between high-level managed APIs and low-level FFI calls to hide interop complexity.

```csharp
// High-level API: Just pass C# types
Lore.RepositoryCreate(globalArgs, repoArgs).Wait();

// Low-level API: Work directly with FFI
using static LoreVcs.Interop.Native;
var callback = new LoreEventCallbackConfig { /* ... */ };
int result = LoreRepositoryCreate(globalArgs, repoArgs, callback);
```

--------------------------------

### Lore.BranchSwitch()

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/operations-reference.md

Switches the working directory to a different branch.

```APIDOC
## Lore.BranchSwitch()

### Description
Switches the working directory to a different branch.

### Signature
`public static LoreExecutor<LoreBranchSwitchArgs> BranchSwitch(in LoreGlobalArgs globalArgs, in LoreBranchSwitchArgs args)`

### Parameters
- **globalArgs.RepositoryPath** - Path to the repository
- **args.Name** - Name of the branch to switch to

### Events Emitted
- **BRANCH_SWITCH** - Switch successful
- **LOG** - Switch progress
- **COMPLETE** - Operation complete (0 = success)
- **END** - Final event

### Throws
- **LoreError** - If branch does not exist or switch fails

### Example
```csharp
using var switchArgs = new LoreBranchSwitchArgs { Name = "main" };
var result = Lore.BranchSwitch(globalArgs, switchArgs).Wait();
```
```

--------------------------------

### Handle Concurrent Operations with Context

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/api-design-patterns.md

Demonstrates tracking multiple concurrent repository operations by assigning unique context IDs to each task.

```csharp
var tasks = Enumerable.Range(0, 5)
    .Select(i => Lore.RepositoryCreate(globalArgs, repoArgs)
        .UserContext((ulong)i)
        .Callback((evt, ctx) =>
        {
            Console.WriteLine($"Op {ctx}: {evt.Tag}");
        })
        .WaitAsync())
    .ToList();

await Task.WhenAll(tasks);
```

--------------------------------

### Validate and Create Repository in C#

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/error-handling.md

Performs input validation and directory checks before executing repository creation. Uses try-catch blocks to handle directory IO and Lore-specific exceptions.

```csharp
class RepositoryOperations
{
    public static int ValidateAndCreate(string repoPath, string repoUrl)
    {
        // Validate inputs
        if (string.IsNullOrWhiteSpace(repoPath))
        {
            Console.WriteLine("Repository path cannot be empty");
            return 1;
        }
        
        if (string.IsNullOrWhiteSpace(repoUrl))
        {
            Console.WriteLine("Repository URL cannot be empty");
            return 1;
        }
        
        // Validate preconditions
        if (Directory.Exists(repoPath))
        {
            Console.WriteLine($"Repository already exists at {repoPath}");
            return 1;
        }
        
        try
        {
            Directory.CreateDirectory(repoPath);
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Failed to create directory: {ex.Message}");
            return 1;
        }
        
        // Perform operation
        try
        {
            using var globalArgs = new LoreGlobalArgs 
            { 
                RepositoryPath = repoPath, 
                Offline = true 
            };
            using var repoArgs = new LoreRepositoryCreateArgs 
            { 
                RepositoryUrl = repoUrl 
            };
            
            int result = Lore.RepositoryCreate(globalArgs, repoArgs).Wait();
            return result;
        }
        catch (LoreError ex)
        {
            Console.WriteLine($"Repository creation failed: {ex.Message}");
            return ex.ReturnCode;
        }
    }
}
```

--------------------------------

### LoreStorageGetArgs

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Arguments for retrieving items from storage.

```APIDOC
## LoreStorageGetArgs

### Description
Defines the items to be retrieved from a specific storage handle.

### Properties
- **Handle** (LoreStore) - Required - Storage handle from StorageOpen.
- **Items** (LoreStorageGetItem[]) - Required - Array of items to retrieve.
```

--------------------------------

### LoreStoragePutArgs

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Arguments for writing items to storage.

```APIDOC
## LoreStoragePutArgs

### Description
Defines the items to be written to a specific storage handle.

### Properties
- **Handle** (LoreStore) - Required - Storage handle from StorageOpen.
- **Items** (LoreStoragePutItem[]) - Required - Array of items to write.
```

--------------------------------

### Lore.StoragePut()

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/operations-reference.md

Writes data to a specified storage instance.

```APIDOC
## Lore.StoragePut()

### Description
Writes an array of items to the storage instance identified by the handle.

### Signature
`public static LoreExecutor<LoreStoragePutArgs> StoragePut(in LoreGlobalArgs globalArgs, in LoreStoragePutArgs args)`

### Parameters
- **args.Handle** (LoreStore) - Required - Storage handle obtained from StorageOpen.
- **args.Items** (Array) - Required - Array of items to write.

### Events Emitted
- **STORAGE_PUT_ITEM_COMPLETE** - One event per item written.
- **LOG** - Put progress.
- **COMPLETE** - Operation complete (0 = success).
- **END** - Final event.
```

--------------------------------

### Run Unit Tests

Source: https://github.com/epicgames/lore-dotnet/blob/main/CONTRIBUTING.md

Execute the unit tests for the Lore SDK using the .NET test runner. Detailed output is enabled for easier debugging.

```shell
dotnet test LoreVcs.Tests --logger "console;verbosity=detailed"
```

--------------------------------

### Register Delegate-Based Callback

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Demonstrates manual callback lifecycle management by pinning a delegate to prevent garbage collection.

```csharp
using static LoreVcs.Interop.Native;

void EventHandler(LoreEventFFI loreEvent, ulong userContext)
{
    if (loreEvent.Tag == LoreEventTag.LOG)
    {
        var logData = loreEvent.GetData<LoreLogEventDataFFI>();
        Console.WriteLine($"[{logData.Level}] {logData.Message}");
    }
}

// Pin the delegate to prevent garbage collection
var gcHandle = GCHandle.Alloc(new LoreCallback(EventHandler), GCHandleType.Normal);
var funcPtr = Marshal.GetFunctionPointerForDelegate((LoreCallback)gcHandle.Target!);

var callback = new LoreEventCallbackConfig
{
    Func = (delegate* unmanaged[Cdecl]<_LoreEvent*, ulong, void>)funcPtr,
    UserContext = 123
};

try
{
    var globalArgs = new LoreGlobalArgs { RepositoryPath = "/path", Offline = true };
    var repoArgs = new LoreRepositoryCreateArgs { RepositoryUrl = "my-repo" };
    int result = LoreRepositoryCreate(globalArgs, repoArgs, callback);
}
finally
{
    gcHandle.Free();
}
```

--------------------------------

### LoreStorageGet

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Retrieves data from storage by address.

```APIDOC
## LoreStorageGet

### Description
Retrieves data from storage by address.

### Signature
`public unsafe static int LoreStorageGet(in LoreGlobalArgs globals, in LoreStorageGetArgs args, LoreEventCallbackConfig callback)`
```

--------------------------------

### Format Code with CSharpier

Source: https://github.com/epicgames/lore-dotnet/blob/main/CONTRIBUTING.md

Apply code formatting to the entire project using CSharpier. This command should be run before committing changes to maintain code style consistency.

```shell
dotnet csharpier .
```

--------------------------------

### Define LoreStore struct

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/types-and-enums.md

Opaque handle to a storage instance.

```csharp
public struct LoreStore
{
    public LoreStore(ulong handleId)
    public ulong HandleId { get; }
    public static LoreStore Invalid { get; }
}
```

--------------------------------

### Query Repository Status with Lore.RepositoryStatus

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/operations-reference.md

Retrieves file states and staging information. Requires an existing repository path.

```csharp
public static LoreExecutor<LoreRepositoryStatusArgs> RepositoryStatus(
    in LoreGlobalArgs globalArgs,
    in LoreRepositoryStatusArgs args
)
```

```csharp
var statusArgs = new LoreRepositoryStatusArgs { Staged = true, Scan = true };
var events = Lore.RepositoryStatus(globalArgs, statusArgs).Collect();

var fileEvents = events.OfType<LoreRepositoryStatusFileEventData>();
foreach (var fileEvent in fileEvents)
{
    Console.WriteLine($"{fileEvent.Path} — {fileEvent.State}");
}
```

--------------------------------

### Perform Storage Operations

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/quick-start.md

Handles opening, writing, reading, and closing in-memory storage using callbacks and event collection.

```csharp
// Open in-memory storage
ulong handleId = 0;
var openArgs = new LoreStorageOpenArgs { InMemory = true };
var openEvents = Lore.StorageOpen(globalArgs, openArgs)
    .Callback((evt, ctx) =>
    {
        if (evt.Tag == LoreEventTag.STORAGE_OPENED)
        {
            handleId = evt.GetData<LoreStorageOpenedEventDataFFI>().HandleId;
        }
    })
    .Collect();

// Write data to storage
var payload = new byte[] { 1, 2, 3, 4, 5 };
using var putArgs = new LoreStoragePutArgs
{
    Handle = new LoreStore(handleId),
    Items = new[]
    {
        new LoreStoragePutItem
        {
            Id = 1,
            Partition = new LorePartition(new byte[16]),
            Context = new LoreContext(new byte[16]),
            Data = payload,
            RemoteWrite = false
        }
    }
};

LoreAddress? address = null;
var putEvents = Lore.StoragePut(globalArgs, putArgs)
    .Callback((evt, ctx) =>
    {
        if (evt is LoreStoragePutItemCompleteEventData putComplete)
        {
            address = putComplete.Address;
        }
    })
    .Collect();

// Read data from storage
if (address.HasValue)
{
    using var getArgs = new LoreStorageGetArgs
    {
        Handle = new LoreStore(handleId),
        Items = new[]
        {
            new LoreStorageGetItem
            {
                Id = 1,
                Partition = new LorePartition(new byte[16]),
                Address = address.Value,
                Streaming = false
            }
        }
    };
    
    var getEvents = Lore.StorageGet(globalArgs, getArgs).Collect();
    var data = getEvents.OfType<LoreStorageGetDataEventData>()
        .SelectMany(e => e.Bytes)
        .ToArray();
    
    Console.WriteLine($"Retrieved {data.Length} bytes");
}

// Close storage
using var closeArgs = new LoreStorageCloseArgs { Handle = new LoreStore(handleId) };
Lore.StorageClose(globalArgs, closeArgs).Wait();
```

--------------------------------

### LoreBranchSwitch Function Signature

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Defines the signature for switching to a different branch.

```csharp
public unsafe static int LoreBranchSwitch(
    in LoreGlobalArgs globals,
    in LoreBranchSwitchArgs args,
    LoreEventCallbackConfig callback
)
```

--------------------------------

### Clone a Repository

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Clones a remote repository to a local path defined in the global arguments.

```csharp
public unsafe static int LoreRepositoryClone(
    in LoreGlobalArgs globals,
    in LoreRepositoryCloneArgs args,
    LoreEventCallbackConfig callback
)
```

--------------------------------

### Event Handling Pattern

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/README.md

Registers a callback for repository creation events and processes specific log event data.

```csharp
var events = Lore.RepositoryCreate(globalArgs, args)
    .Callback((evt, ctx) => { /* ... */ })
    .Collect();

foreach (var ev in events.OfType<LoreLogEventData>())
{
    Console.WriteLine(ev.Message);
}
```

--------------------------------

### LoreStoragePut

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Writes data to storage.

```APIDOC
## LoreStoragePut

### Description
Writes data to storage.

### Signature
`public unsafe static int LoreStoragePut(in LoreGlobalArgs globals, in LoreStoragePutArgs args, LoreEventCallbackConfig callback)`
```

--------------------------------

### Implement Global and Per-Operation Callbacks

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/api-design-patterns.md

Global callbacks monitor all operations, while per-operation callbacks are scoped to specific calls. Global callbacks execute before per-operation callbacks and are not subject to type filtering.

```csharp
// Applies to ALL operations, regardless of filters
using var logCallback = Lore.GlobalCallback(LoreEventTag.LOG,
    (evt, ctx) =>
    {
        var logData = evt.GetData<LoreLogEventDataFFI>();
        Console.WriteLine(logData.Message);
    });

// This operation is monitored by the global callback
Lore.RepositoryCreate(globalArgs, repoArgs).Wait();
```

```csharp
// Applies only to this operation
Lore.RepositoryCreate(globalArgs, repoArgs)
    .Callback((evt, ctx) => 
    {
        // Handle event specific to this operation
    })
    .Wait();
```

--------------------------------

### LoreBranchSwitch

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Switches to a different branch.

```APIDOC
## LoreBranchSwitch

### Description
Switches to a different branch.

### Signature
`public unsafe static int LoreBranchSwitch(in LoreGlobalArgs globals, in LoreBranchSwitchArgs args, LoreEventCallbackConfig callback)`
```

--------------------------------

### Lore.BranchFetch()

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/operations-reference.md

Fetches updates from the remote server.

```APIDOC
## Lore.BranchFetch()

### Description
Fetches updates from the remote server.

### Method
public static LoreExecutor<LoreBranchFetchArgs> BranchFetch(in LoreGlobalArgs globalArgs, in LoreBranchFetchArgs args)

### Parameters
- **globalArgs.Offline** (bool) - Required - Must be false to fetch from remote

### Events Emitted
- **BRANCH_FETCH** - Fetch complete
- **LOG** - Fetch progress
- **COMPLETE** - Operation complete (0 = success)
- **END** - Final event
```

--------------------------------

### Define LoreStorageOpenArgs structure

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Configuration structure for opening a storage repository, supporting both disk-based and in-memory modes.

```csharp
public struct LoreStorageOpenArgs : IDisposable
{
    public string RepositoryPath { get; set; }
    public bool InMemory { get; set; }
}
```

--------------------------------

### Define LoreStoragePutArgs structure

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Configuration structure for writing items to a storage handle.

```csharp
public struct LoreStoragePutArgs : IDisposable
{
    public LoreStore Handle { get; set; }
    public LoreStoragePutItem[] Items { get; set; }
}
```

--------------------------------

### Define LoreStorageGetArgs structure

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Configuration structure for retrieving items from a storage handle.

```csharp
public struct LoreStorageGetArgs : IDisposable
{
    public LoreStore Handle { get; set; }
    public LoreStorageGetItem[] Items { get; set; }
}
```

--------------------------------

### Lore.RepositoryClone()

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/operations-reference.md

Clones a remote repository to a local path.

```APIDOC
## Lore.RepositoryClone()

### Description
Clones a remote repository to a local path.

### Parameters
- **globalArgs.RepositoryPath** (string) - Required - Target local directory for the clone (must not exist).
- **globalArgs.Offline** (bool) - Required - Must be false to connect to remote.
- **args.RepositoryUrl** (string) - Required - Remote repository URL.

### Throws
- LoreError if offline, path exists, or remote is unavailable.
```

--------------------------------

### LoreStorageGet Function Signature

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Defines the signature for retrieving data from storage by address.

```csharp
public unsafe static int LoreStorageGet(
    in LoreGlobalArgs globals,
    in LoreStorageGetArgs args,
    LoreEventCallbackConfig callback
)
```

--------------------------------

### Configure File Logging

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Enables persistent logging to a specified directory by setting File to true.

```csharp
var logConfig = new LoreLogConfig
{
    File = true,
    FilePath = "/var/log/lore-app",
    Level = LoreLogLevel.DEBUG
};
Lore.LogConfigure(logConfig);

// All subsequent operations will log to /var/log/lore-app/
var result = Lore.RepositoryCreate(globalArgs, repoArgs).Wait();
```

--------------------------------

### Set LORE_BUILD_PATH Environment Variable

Source: https://github.com/epicgames/lore-dotnet/blob/main/CONTRIBUTING.md

Set the LORE_BUILD_PATH environment variable to point to your local Lore native library build. This is a prerequisite for building the SDK.

```shell
export LORE_BUILD_PATH="/<path-to>/lore/target/release"
```

--------------------------------

### LoreStoragePut Function Signature

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/native-api.md

Defines the signature for writing data to storage.

```csharp
public unsafe static int LoreStoragePut(
    in LoreGlobalArgs globals,
    in LoreStoragePutArgs args,
    LoreEventCallbackConfig callback
)
```

--------------------------------

### Push and Clone Remote Repositories

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/quick-start.md

Performs network operations by setting Offline to false in LoreGlobalArgs.

```csharp
// Push to remote
using var pushGlobalArgs = new LoreGlobalArgs 
{ 
    RepositoryPath = "/path/to/local-repo",
    Offline = false  // Enable network
};
var pushResult = Lore.BranchPush(pushGlobalArgs, new LoreBranchPushArgs()).Wait();

// Clone from remote
using var cloneGlobalArgs = new LoreGlobalArgs 
{ 
    RepositoryPath = "/path/to/clone",
    Offline = false 
};
using var cloneArgs = new LoreRepositoryCloneArgs 
{ 
    RepositoryUrl = "lore://server/my-repo" 
};
var cloneResult = Lore.RepositoryClone(cloneGlobalArgs, cloneArgs).Wait();
```

--------------------------------

### Repository Clone Arguments Structure

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Defines the structure for cloning a remote repository.

```csharp
public struct LoreRepositoryCloneArgs : IDisposable
{
    public string RepositoryUrl { get; set; }
}
```

--------------------------------

### Clone Repository with Lore.RepositoryClone

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/operations-reference.md

Clones a remote repository to a local path. Offline mode must be disabled.

```csharp
public static LoreExecutor<LoreRepositoryCloneArgs> RepositoryClone(
    in LoreGlobalArgs globalArgs,
    in LoreRepositoryCloneArgs args
)
```

```csharp
using var globalArgs = new LoreGlobalArgs 
{ 
    RepositoryPath = "/tmp/cloned-repo", 
    Offline = false 
};
using var cloneArgs = new LoreRepositoryCloneArgs 
{ 
    RepositoryUrl = "lore://server/remote-repo" 
};

var result = Lore.RepositoryClone(globalArgs, cloneArgs).Wait();
```

--------------------------------

### Configure per Operation

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/configuration.md

Define unique configuration instances for individual operations to maintain state isolation.

```csharp
// Each operation gets its own configuration
var publicRepoArgs = new LoreGlobalArgs { RepositoryPath = "/public/repo", Offline = false };
var privateRepoArgs = new LoreGlobalArgs { RepositoryPath = "/private/repo", Offline = true };

Lore.RepositoryStatus(publicRepoArgs, statusArgs1).Wait();   // Online
Lore.RepositoryStatus(privateRepoArgs, statusArgs2).Wait();  // Offline
```

--------------------------------

### Lore.BranchFetch Method Signature

Source: https://github.com/epicgames/lore-dotnet/blob/main/_autodocs/operations-reference.md

Defines the static method signature for fetching updates from a remote server.

```csharp
public static LoreExecutor<LoreBranchFetchArgs> BranchFetch(
    in LoreGlobalArgs globalArgs,
    in LoreBranchFetchArgs args
)
```

--------------------------------

### Set Runtime Identifier in Project File

Source: https://github.com/epicgames/lore-dotnet/blob/main/README.md

Configures the project to target a specific runtime identifier, recommended for RID-qualified restores.

```xml
<PropertyGroup>
  <RuntimeIdentifier>osx-arm64</RuntimeIdentifier>
</PropertyGroup>
```