AniShelf: Instructions file for Codex

AniShelf - Developer Notes

Workflow

• Use Makefile targets for routine tasks (make help lists them).
• Run make clean, make refresh-packages, or make format only when the task needs it or the user asks. make refresh-packages deletes Package.resolved, so dependencies can move to newer versions; make format rewrites the whole repository. Format only the files you touched with swift format -i <paths>.
• Validate on the affected platform. For iOS, use make test-sim for broad simulator-based validation and make run-sim when validating runtime or UI behavior rather than relying only on make build. For native macOS, verify with make build-mac; launch with make run-mac only when the user asks. make run-mac loads an 800-entry fixture library by default, not the real library.
• Physical-device targets (make run-device, make test, make test-app, make test-app-live-fetch) run only when the user explicitly asks. If a check needs a device, explain why and ask.
• If the user asks to perform a change in a new worktree, create that worktree under .worktrees/ in the repository root.
• Use the write-ai-doc skill for substantial features and decision-shaping fixes, as defined in docs-ai/workflow.md.

Code Style

• When creating new Swift source files, include the standard Xcode file comment header. Attribute authorship to the agent (OpenAI Codex or Claude Code) on behalf of Samuel He, and use the real creation date in YYYY/M/D format:

  //
  //  FileName.swift
  //  AniShelf
  //
  //  Created by <agent> on behalf of Samuel He on YYYY/M/D.
  //
  

  Omit this header only when the user explicitly requests it.
• Give scrollable content under a navigation bar (Form, List, ScrollView, including each step of a multi-step sheet) .preferredNavigationBarScrollEdgeEffect(), so it follows the soft-edges setting, followed by .navigationTitle(...), .inlineNavigationTitle(), and .toolbar. In sheet toolbars, put a dismiss button at .cancellationAction with SheetCloseLabel, and other buttons at .sheetLeading/.sheetTrailing, never at raw .topBar* placements, which break the Mac's sheet bar.
• Pass plain string literals to SwiftUI APIs that already take a LocalizedStringKey (Text, Button, Label, .help, and similar); do not wrap them in LocalizedStringResource. Use LocalizedStringResource for user-facing strings held in properties, models, or enums, or passed to APIs that do not localize literals.