AGENTS.md git:20261011.4851662A

Immutable. This exact content never changes and is served at /api/v1/blob/d6a12dde0ba842da.

# Toastty

## Instruction Scope

- This project file is shared across agent runtimes. Follow the active agent's global instructions for interaction style, review mechanics, and tool availability; the Toastty commands and project constraints here win for this repository.
- When a workflow points at `.agents/skills/.../SKILL.md`, read that file as the authoritative task guide when the task applies. If the active runtime does not load skill files automatically, read the referenced file directly and follow the documented workflow intent.
- Keep this file concise. Detailed workflows and reference material live here:
  - `.agents/skills/toastty-verify/SKILL.md` for choosing, running, and reporting Toastty verification.
  - `.agents/skills/toastty-debug/SKILL.md` for debugging, log discovery, runtime target selection, and focused repro planning.
  - `.agents/skills/toastty-dev-run/SKILL.md` for isolated live dev/debug app instances.
  - `.agents/skills/toastty-diagnostics/SKILL.md` for fetching and analyzing submitted diagnostics reports.
  - `docs/agents/automation.md` for smoke, remote, and xcodebuild test details.
  - `docs/agents/workspace-scope.md` for cooperative workspace-scoped automation semantics and CLI commands.
  - `docs/agents/menu-performance.md` for menu-related regressions and shortcuts.
  - `docs/agents/manual-interaction.md` for background notes on interaction pitfalls.
  - `docs/ghostty-integration.md` for Ghostty artifact, build, config, and validation details.
  - `.agents/skills/toastty-computer-use/SKILL.md` for remote Computer Use GUI debugging and verification beyond smoke-test coverage.

## Build And Generate

- Toastty has two independent Tuist graphs. The macOS source of truth is root `Project.swift`; the native client source of truth is `ios/Project.swift` with `ios/Workspace.swift`. Never hand-edit either graph's generated Xcode project/workspace files, and run Tuist from the graph's own directory.
- Web-panel bundles under `Sources/App/Resources/WebPanels/` are generated artifacts. For local-document behavior, inspect and edit `WebPanels/LocalDocumentApp/src/` rather than loading or modifying the generated `local-document-panel` bundle; use the bundle only when validating generated output.
- Install packages with `tuist install` after cloning and whenever `Tuist/Package.swift` or `Tuist/Package.resolved` changes. Repo scripts do this automatically where needed.
- For a fresh worktree, or when `Tuist/Package.swift`, `Tuist/Package.resolved`, or Ghostty artifact state changes, run `./scripts/dev/bootstrap-worktree.sh`. It links local Ghostty artifacts when needed, then runs `tuist install` and `tuist generate --no-open`.
- In an already-bootstrapped worktree, regenerate the macOS graph from the worktree root after project/build-setting changes, source file additions/renames/deletions, or branch switches. Use `sv exec -- tuist generate --no-open` when `sv` is available so configured manifest-scoped values are forwarded; without `sv`, export the desired generation values and run `tuist generate --no-open`. Optional values may still be unset: without `TUIST_DEVELOPMENT_TEAM`, generation intentionally falls back to ad-hoc signing, and unset diagnostics values omit diagnostics injection. Generated `.xcodeproj` and `.xcworkspace` files are disposable and can otherwise keep stale references; fix generation inputs rather than changing signing or other settings in Xcode.
- Generate, build, or test the iOS graph through `node ios/scripts/toastty-ios.mjs generate|build|test`. The dispatcher installs and generates the `ios/` graph; build and test select a compatible iPhone Simulator. All commands support `--dry-run`.
- Build:
  ```bash
  ARCH="${ARCH:-$(if [[ "$(sysctl -n hw.optional.arm64 2>/dev/null || echo 0)" == "1" ]]; then echo arm64; else uname -m; fi)}"; xcodebuild -workspace toastty.xcworkspace -scheme ToasttyApp -configuration Debug -destination "platform=macOS,arch=${ARCH}" -derivedDataPath Derived build
  ```
- Full local gate: `./scripts/automation/check.sh` (generate, artifact self-tests, web-panel tests, build, smoke, and app tests; Ghostty-backed unless fallback is explicitly requested).
- After any code, project, dependency, or merge-related change, ensure the generated Xcode project is current and the app builds cleanly before handoff. This includes branch merges and branch switches that may leave generated project state stale.
- Avoid deriving `ARCH` from `uname -m` in translated shells or inside `sv exec`; it may report `x86_64` on arm64 hosts. Set `ARCH=arm64` explicitly for agent/remote runs unless intentionally validating Rosetta. Prefer invocation-scoped overrides such as `ARCHS` and `ONLY_ACTIVE_ARCH=YES` over mutating project settings.
- Agent-driven iOS simulator tests run on the remote toastty-mini path: `sv exec -- scripts/remote/test.sh --platform ios --scope working-tree`. Do not boot or drive a local simulator unless the user explicitly requests local validation.

## Validation

Use `.agents/skills/toastty-verify/SKILL.md` as the authoritative workflow for choosing, running, and reporting validation after implementation, build, project, dependency, automation, UI/runtime, menu/shortcut, or agent-instruction changes.

- Keep detailed smoke, remote, test, and local-helper command semantics in `docs/agents/automation.md`.
- Do not probe `TOASTTY_REMOTE_GUI_HOST` outside `sv exec`; remote GUI/test env is injected there.
- In handoffs, say whether validation ran remotely, locally, or through `validate.sh` with local fallback.
- Artifacts are stored in `artifacts/` (gitignored). Manual captures go in `artifacts/manual/`. Committed planning docs belong in `docs/plans/`, not `artifacts/`.

## Live App Runs

Use `.agents/skills/toastty-dev-run/SKILL.md` for live Toastty dev/debug app instances and user-observable runtime checks. For pure unit/integration tests, remote smoke, or remote xcodebuild wrappers, use `.agents/skills/toastty-verify/SKILL.md` and `docs/agents/automation.md`.

- Use runtime isolation and per-run filesystem paths for local dev/debug/test runs.
- Preserve `TOASTTY_DEV_WORKTREE_ROOT=$(SRCROOT)` in the Tuist-generated `ToasttyApp` and `ToasttyApp-Release` Run schemes.
- Treat `instance.json` as authoritative for PID, paths, logs, and socket targeting.
- Do not drive a local Toastty GUI with Peekaboo (focus, clicks, screenshots) unless the user explicitly asks for local validation. Use `scripts/remote/validate.sh` or `.agents/skills/toastty-computer-use/SKILL.md` instead; local socket-only checks that never focus a window are fine.

## Release Workflow

- Ghostty release provenance: install release artifacts with `GHOSTTY_BUILD_FLAGS=... ./scripts/ghostty/install-local-xcframework.sh`; the installer writes ignored sidecar metadata under `Dependencies/GhosttyKit.Release.metadata.env`.
- Build release DMG and draft notes: follow `.agents/skills/toastty-release/SKILL.md`. `scripts/release/release.sh` requires a clean Toastty git tree and a clean Ghostty metadata snapshot, then writes `release-metadata.env`, `ghostty-metadata.env`, `sparkle-metadata.env`, and drafted `release-notes.md` into `artifacts/release/<version>-<build>/`.
- Publish later: follow `.agents/skills/toastty-publish/SKILL.md`. It verifies existing drafted notes and release metadata, then runs `scripts/release/publish-github-release.sh --create-tag`.

## Debugging

Use `.agents/skills/toastty-debug/SKILL.md` for debugging, log discovery, runtime target selection, and focused repro planning.

- First identify the target being debugged. Production/installed Toastty logs differ from worktree/Xcode/dev/smoke runtime-isolated logs.
- For worktree, Xcode, dev, or smoke runs, resolve `instance.json` and read its `logFilePath`; do not default to production logs.
- If the target is ambiguous, default to the current worktree's runtime-isolated instance before inspecting broad process lists.
- For agent-specific terminal input bugs, validate the managed launch environment as well as AppKit/Ghostty routing. A fixture that enables terminal protocols itself can hide launch overrides that disable them in the real agent.
- For remote Claude login failures over SSH, check authentication in the macOS GUI login session before concluding that Claude is logged out. The SSH security session can lack access to an existing subscription login; run the live CLI check in the GUI session when this occurs.
- Before retrying remote GUI input or investigating `cgWindowNotFound`, check whether the remote desktop is locked. A running GUI session and a valid provider login do not prove that its windows are available to Computer Use.

## Specialized References

- Before changing Ghostty artifacts, config loading, host-side terminal styling, or fallback builds, read `docs/ghostty-integration.md`.
- Before touching menu rebuilds, hidden system menu items, workspace shortcuts, terminal jank that may involve AppKit, or `Cmd+W`, read `docs/agents/menu-performance.md`.
- Manual GUI reproduction: prefer `.agents/skills/toastty-computer-use/SKILL.md`; `docs/agents/manual-interaction.md` covers local interaction pitfalls.