Sybil-2/ios/AGENTS.md

AGENTS.md (iOS)

Scope

Instructions for work under /Users/buzzert/src/sybil-2/ios.

Build + Run

• Preferred build command: just build
• just build will:
  1. generate Sybil.xcodeproj with xcodegen if missing,
  2. build scheme Sybil for iPhone 16e simulator.
• Preferred test command: just test
• just test runs the Swift package tests through xcodebuild test on the iPhone 16e iOS simulator from ios/Packages/Sybil.
• just test disables Xcode parallel testing because the current async view-model tests use timing-sensitive selection tasks.
• Do not use plain swift test for this package; it runs as host macOS and hits a deployment mismatch with MarkdownUI.
• If xcbeautify is installed it is used automatically; otherwise raw xcodebuild output is used.

Simulator Workflow

• Run the app in the simulator with just run from /Users/buzzert/src/sybil-2/ios.
• just run boots the iPhone 16e simulator if needed, builds with a stable derived data path, installs Sybil.app, and launches bundle id net.buzzert.sybil2.
• Capture a simulator screenshot with just screenshot from /Users/buzzert/src/sybil-2/ios; it writes build/sybil-screenshot.png by default.
• To choose a screenshot path, run just screenshot path=build/name.png.
• The underlying screenshot command is xcrun simctl io booted screenshot <path> and requires a booted simulator.

App Structure

• App target entry: /Users/buzzert/src/sybil-2/ios/Apps/Sybil/Sources/SybilApp.swift
• Shared iOS app code lives in Swift package:
  • /Users/buzzert/src/sybil-2/ios/Packages/Sybil/Sources/Sybil
• Main UI root: SplitView.swift
• Networking + SSE client: SybilAPIClient.swift
• State coordinator: SybilViewModel.swift

Product Expectations

• Keep the iOS design aligned to the web app dark aesthetic (no light mode support required).
• Preserve these core features:
  • conversation/search list,
  • streaming chat transcript,
  • streaming search results + answer,
  • settings screen for API URL and token.
• Markdown rendering currently uses MarkdownUI via SwiftPM.

API Contract

• iOS client must follow docs in:
  • /Users/buzzert/src/sybil-2/docs/api/rest.md
  • /Users/buzzert/src/sybil-2/docs/api/streaming-chat.md
• If backend contract changes (request/response shapes, SSE events, auth semantics), update docs in the same change.

Practical Notes

• Default API URL is http://127.0.0.1:8787 (configurable in-app).
• The iOS client preserves an explicit /api base path for proxied deployments.
• Provider fallback models:
  • OpenAI: gpt-4.1-mini
  • Anthropic: claude-3-5-sonnet-latest
  • xAI: grok-3-mini
  • Hermes Agent: hermes-agent