# Repository instructions

## Gitea issue workflow

Use the `tea` command-line tool as the preferred way to list, inspect, create,
and update Gitea issues. Run it from the repository root so it can use the
configured remote, for example `tea issues` or `tea issues 1`.

## Required pre-commit gates

Run every gate below from the repository root before committing. Every command
must succeed; do not commit code that is unformatted, fails Clippy, or compiles
with warnings.

```sh
cargo fmt --all -- --check
RUSTFLAGS="-D warnings" cargo check --workspace --all-targets
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```

Do not weaken or skip these gates to make a commit pass. Fix the underlying
warning, lint, formatting issue, or test failure.

## iOS simulator build and deployment

This Apple Silicon project builds the simulator app for `arm64`. Do not disable
code signing: the Rust build script consumes Xcode's generated simulator
entitlement paths. Do not request an `x86_64` simulator build unless the
`x86_64-apple-ios` Rust target has explicitly been installed.

Use this sequence from the repository root:

```sh
cd ios
xcodegen generate

xcodebuild \
  -project Gotcha.xcodeproj \
  -scheme Gotcha \
  -configuration Debug \
  -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
  ARCHS=arm64 \
  ONLY_ACTIVE_ARCH=YES \
  build

gotcha_build_dir="$(
  xcodebuild \
    -project Gotcha.xcodeproj \
    -scheme Gotcha \
    -configuration Debug \
    -sdk iphonesimulator \
    -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
    -showBuildSettings -json \
    ARCHS=arm64 \
    ONLY_ACTIVE_ARCH=YES |
  plutil -extract 0.buildSettings.TARGET_BUILD_DIR raw -o - -
)"
xcrun simctl install booted "$gotcha_build_dir/Gotcha.app"
xcrun simctl launch booted de.rfc1437.gotcha
```

Before deploying, check for a booted simulator with
`xcrun simctl list devices available`. If none is booted, boot an available
iPhone (currently `xcrun simctl boot "iPhone 17 Pro"`) and open Simulator.
CoreSimulator access may require running `xcodebuild` and `simctl` outside the
workspace sandbox.

## Generated build data

Use Xcode's default DerivedData location; do not pass `-derivedDataPath`.
Cargo's ignored `target/` directory is a disposable build cache. Cargo does not
bound or garbage-collect stale target artifacts, so check it with
`du -sh target` and run `cargo clean` when disk space is worth a full rebuild.
Do not add a custom cache-pruning tool or disable incremental compilation just
to reduce routine cache usage.