# Beat Saber Artifact Policy

Use this policy for plugin install/update/bootstrap tasks and for audit reports
that discuss candidate artifacts.

## Source Priority

- Prefer upstream GitHub release artifacts for ordinary repository-backed
  plugins.
- Use BeatMods primarily as compatibility, dependency, and verification
  metadata.
- Use BeatMods CDN artifacts only for inaccessible upstream assets,
  BeatMods-only packages, framework/library dependencies, or cases where no
  matching upstream release asset exists.
- Skip paid/private Patreon, Discord, and closed-source sources during automated
  public update checks. Report them as manual follow-up unless the user provides
  the artifact and asks to manage it.

## Repository Guardrail

- For ordinary GitHub-hosted plugins, require an explicit GitHub repository,
  release URL, or user-provided local planning note before selecting a release.
- If the user provided a repo URL but no release URL, query that exact repo's
  releases and choose the most appropriate non-draft, non-prerelease release for
  the target instance.
- If the user provided no repo or release URL for a plugin install/update, stop
  and ask for one.
- Do not discover a different repository from web search, substitute a fork, or
  infer the "correct" project from a similar package name.
- If the URL is a releases page, use that repo's release API and choose the
  latest non-draft, non-prerelease release unless the user asks for a tag.
- If the URL is a tag URL, use that exact tag.

## BeatMods Exceptions

When the user explicitly asks to bootstrap a Beat Saber instance or install
verified mods without GitHub URLs, use BeatMods verified metadata to identify
compatible versions and dependency closure. Still prefer upstream GitHub assets
when BeatMods exposes a `gitUrl` and a matching release asset can be found.

Record the artifact source plus BeatMods `modVersion`, version id, `zipHash`,
dependencies, and supported game version in repo notes or lock data when
BeatMods metadata drives the selection.

BeatMods dependency entries are mod-version ids. Resolve the selected mod's
dependency closure before downloading.

## Checksums And Inspection

- Download artifacts into the selected helper state directory, normally:

  ```bash
  <state_dir>/instances/<instance>/downloads/<plugin-id>/
  ```

- Record SHA-256 checksums for downloaded or built artifacts.
- Match the checksum against GitHub's `digest` when available.
- For BeatMods CDN artifacts, preserve BeatMods `zipHash` metadata and verify
  the downloaded archive against the expected hash when the helper supports it.
- Inspect archive contents before selecting install strategy:

  ```bash
  unzip -l <artifact>
  ```

## Install Strategy Guide

- `dll-to-plugins`: asset is a single `.dll` that belongs in `Plugins/`.
- `bsipa-zip`: zip top-level paths are only `IPA/`, `Libs/`, or `Plugins/`.
- `root-zip`: zip contains valid game-root paths outside the BSIPA top-level
  set. Use this for BSIPA/bootstrap archives because `IPA.exe`,
  `IPA.runtimeconfig*.json`, and root `winhttp.dll` are game-root files.
- `zip-to-pending`: only when the release is intended for `IPA/Pending/`.
- `manual`: do not use for installable releases.

## BSIPA Bootstrap

Treat BSIPA as a bootstrap phase. `bootstrap` installs the locked BSIPA archive
and records generated files. Ordinary plugin plans should depend on healthy
bootstrap state.

For BSIPA bootstrap archives, expect root-relative `IPA/` and `IPA.exe` files
whether sourced from GitHub or BeatMods. Extract into the instance root and run
`IPA.exe -n` under the same Proton environment used by the smoke test. This
creates or copies root `winhttp.dll` and root `Libs/` substrate files.