Gotcha/AGENTS.md

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.

Run issue-detail commands directly, for example tea issues 7. In a sandboxed runner, grant network access before invoking tea. Without DNS/network access, the current tea detail path may panic inside Gitea SDK version handling instead of returning the underlying connection error.

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.

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:

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.