Copilot instructions for Swift

# GitHub Copilot instructions

These instructions apply to the whole Swift repository. Copilot reads them from `.github/copilot-instructions.md`.
Prefer the commands and layout below over guesses.

## Stack

This repository is a Swift app for Apple platforms. Match SwiftUI or UIKit, whichever the target already uses. Stay off the main actor only for work that is actually background work.

## Layout

- Features sit in the group or Swift package the project already uses.
- Views do not own networking. A type the project already has loads data.
- Preview providers stay next to the view they preview.

## Commands

- Tests: `xcodebuild test`
- Open: `Open the project in Xcode and build the app target`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Do not force-unwrap input that can be missing. Use `if let` or `guard`.
- UI updates hop to the main actor.
- Prefer async/await over new callback pyramids when the file already uses concurrency.
- Keep `@State` local. Hoist state only when two views need it.
- Match the existing navigation API. Do not mix NavigationView and NavigationStack in new code.
- Name types the way the module already does.

## Testing

Add or update tests when behavior changes.

Add an XCTest for the type that owns the rule. Do not snapshot the whole screen as the only check.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Model recoverable failure as a thrown error or a Result the view can show. Do not `try!` on user input.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not capture `self` strongly in a long-lived task without a reason.
- Do not block the main thread with file or network I/O.
- Do not add a new architecture layer for one screen.
- Do not disable a compiler warning to ship a force cast.

## Done when

- The requested behavior works.
- The app target builds and the XCTest for the type you changed passes.
- The diff stays inside the task.
- You list anything you could not run.

## Review checklist

- The change matches the commands and layout in this file.
- No new dependency was added without a reason already present in the repo.
- Keep keys out of the repository and out of Info.plist when a build setting can inject them.
- Use the Keychain for tokens. UserDefaults is not a secret store.
- Validate universal-link and URL-scheme parameters.