> ## Documentation Index
> Fetch the complete documentation index at: https://akron-cdb9eaf4.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Development setup

> Set up an Akron checkout, build the Everest Celeste mod locally, and run the first focused verification commands.

This guide leads a contributor from an initial checkout to a local build and the first targeted test run.

## Requirements

* .NET SDK compatible with the Akron project.
* A Celeste/Everest install for [live verification](/contributing/testing-and-verification).
* Access to this repository checkout.
* Celeste references available through the normal Everest mod layout or an explicit `CelestePrefix`.

## Build

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dotnet build Source/Akron.csproj
```

Set `CelestePrefix` if the mod is not inside a normal Everest `Mods/Akron/Source` layout or if references live elsewhere.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dotnet build Source/Akron.csproj -p:CelestePrefix=/path/to/Celeste
```

## Run tests

Use the focused test for the change when possible:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dotnet test tests/akron-tests.csproj --nologo
```

Targeted examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dotnet test tests/akron-tests.csproj --nologo --filter FeatureRegistryTests
dotnet test tests/akron-tests.csproj --nologo --filter ModuleSettingsTests
dotnet test tests/akron-tests.csproj --nologo --filter ArchiveTests
```

## Formatting

Format changed C# project files before opening a pull request:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dotnet format Akron.sln --include Source/Core/AkronFeatureRegistry.cs tests/feature-registry-tests.cs
```

Replace the example file paths with the C# files changed by your pull request. Run the full formatter only when intentionally normalizing repository-wide style:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dotnet format Akron.sln
```

## CI reference archive

GitHub Actions does not commit `lib-stripped/` into the repository. CI build and test jobs need `AKRON_CELESTE_REFS_URL` to point at a zip or tar.gz archive containing a complete `lib-stripped` reference directory.

Set `AKRON_CELESTE_REFS_TOKEN` only when the archive URL requires bearer-token auth.

CI fails when `AKRON_CELESTE_REFS_URL` is not configured because a passing run must prove Akron can build and test. Release packaging requires the archive and fails fast when it is missing.

## Safety

* Do not commit personal Celeste paths, local captures, `.env` files, or tokens.
* Use fixtures and [focused tests](/contributing/testing-and-verification) before reaching for live host state.
* When [live verification](/contributing/testing-and-verification) is required, record the map, visible policy/status state, setup state, command or interaction, and what the evidence proves.

## First contribution loop

<Steps>
  <Step title="Read the relevant public docs">
    Start with the user-facing page for the behavior you are changing.
  </Step>

  <Step title="Find the source layer">
    Identify whether the change touches policy, overlay rows, settings, runtime behavior, persisted setup state, `.akr` import/export, archive contracts, or tests.
  </Step>

  <Step title="Add or update tests">
    Add focused tests for classification, defaults, clamps, archive shape, or non-trivial behavior.
  </Step>

  <Step title="Build and verify">
    Run formatting checks, targeted tests, build, and [live verification](/contributing/testing-and-verification) when the behavior is visual, timing-sensitive, input-driven, or map-dependent.
  </Step>

  <Step title="Update docs">
    Update user-facing docs and [contributor architecture notes](/contributing/public-architecture) when behavior, policy, or contracts change.
  </Step>
</Steps>