# Neith Release User Guide

This guide is for release managers, QA leads, operations staff, and partner
teams consuming `@neith/release` outputs.

## Getting Started

If you are new to the release surface:

1. choose the release path that matches your audience and risk profile
2. generate the release plan and required artifacts
3. publish integrity metadata before promotion
4. validate rollout, update, accessibility, and performance evidence before
   final signoff

## Primary Release Paths

### Standard Stable Release

1. Determine the next version with the versioning helpers.
2. Create a release candidate and collect validation evidence.
3. Build the release pipeline definition with pre-check, build, security, and
   publish stages.
4. Register distribution artifacts, checksums, and signatures.
5. Stage rollout progression through percentage, ring, canary, or geography
   strategies.
6. Publish platform-specific metadata for the channels you support.

### Beta And Early Access

Use `BetaProgramManager` and `EarlyAccessManager` when a release must be tested
under controlled enrollment, tiered permissions, and structured feedback
collection.

### Hotfix And Security Release

Use `HotfixManager`, `SecurityAdvisoryManager`, and `SecurityReleaseManager`
when the priority is rapid remediation with explicit SLA and communication
control.

## Distribution Tasks

### Artifact Delivery

- Register artifacts in the download infrastructure.
- Publish or invalidate CDN metadata when a new release or rollback occurs.
- Maintain mirror health for low-latency regional access.

### Integrity Verification

- Generate checksums for every shipped artifact.
- Sign artifacts with the configured signing backend.
- Verify signatures and checksums before promotion to stable channels.

### Install And Update Channels

- Generate native installers and package-repository metadata for the target
  audience.
- Use offline installers for disconnected or regulated environments.
- Use auto-update and delta-update flows for bandwidth-sensitive fleets.

## Platform Publishing Targets

`@neith/release` covers:

- Linux packages and repository flows
- Windows MSI and MSIX
- macOS DMG and package submission helpers
- iOS App Store and TestFlight
- Android Play Store tracks
- Steam, Epic, Xbox, PlayStation, Nintendo, and Meta Quest
- web distribution, Docker, cloud marketplaces, and enterprise catalogs

Choose only the surfaces relevant to the release train. The package does not
assume every release must publish everywhere.

## Accessibility And Performance Evidence

For web distribution releases:

- Run the accessibility auditor and attach the generated statement.
- Confirm contrast, keyboard navigation, landmarks, heading order, labels, and
  reduced-motion support.

For all release surfaces:

- Run the benchmark suite and confirm both budget compliance and `< 5%`
  regression status before signoff.

## Troubleshooting

| Symptom                        | Likely surface                 | First check                                              |
| ------------------------------ | ------------------------------ | -------------------------------------------------------- |
| Rollout paused unexpectedly    | `staged-rollouts.ts`           | Health thresholds and rollback counters                  |
| Update not offered to clients  | `auto-update.ts`               | version resolution, maintenance window, channel metadata |
| Artifact rejected by consumers | `checksum.ts` / `signature.ts` | digest mismatch or trust policy                          |
| Platform submission blocked    | `src/platform/*`               | generated manifest or required metadata                  |
| Accessibility audit failing    | `platform/web.ts`              | missing WCAG input fields in manifest                    |

Use the [Operations Runbook](./runbook.md) for incident-response sequences.

## Related Documentation

- [Release Overview](./README.md)
- [Operations Runbook](./runbook.md)
- [Neith Domain User Guide](../user-guide.md)
