# Agent Guide

This file is the permanent operating guide for any coding agent working on this
project.

## Project Scope

- This project is a native macOS application.
- The minimum deployment target is macOS 14.0.
- Use Swift and SwiftUI according to the architecture documented for this
  project.
- Do not invent undocumented features or requirements.
- Any substantial change to the architecture or product scope must be documented
  before implementation.

## Required Reading

Before making significant changes, read:

- `docs/PRODUCT.md`
- `docs/ARCHITECTURE.md`
- `docs/DATA_MODEL.md`
- `docs/TASKS.md`
- `docs/OPEN_QUESTIONS.md`

Use these documents as the project references:

- `docs/PRODUCT.md` is the source of truth for product requirements.
- `docs/ARCHITECTURE.md` is the reference for architecture decisions.
- `docs/DATA_MODEL.md` is the reference for data models.
- `docs/TASKS.md` is the reference for implementation phases and tasks.
- `docs/OPEN_QUESTIONS.md` contains decisions that are not resolved yet.

## Decision Rules

- If documents conflict, do not guess. State the conflict before making a
  decision.
- Do not decide anything listed in `docs/OPEN_QUESTIONS.md` on your own.
- Do not automatically move to a new phase in `docs/TASKS.md` unless explicitly
  asked.
- Update `docs/TASKS.md` when tasks are completed.
- Preserve version history and the Song Project concept as documented.

## Code Standards

- Write organized code that is maintainable and extensible.
- Keep clear separation between UI, Models, Services, Persistence, and
  Integrations.
- Keep OpenAI, instrument catalog/selector, and Suno integrations separated from
  UI logic as much as possible.
- In the current scope, the app prepares and stores final lyrics and style
  prompts only; it does not open, embed or control an external
  music-generation website.
- Do not modify files outside the task scope without a clear reason.
- Do not perform a broad refactor while implementing a small task unless it is
  explicitly required.

## Secrets And Configuration

- Do not place API keys, tokens, or secrets in source code or Git.
- Read secrets only from secure environment or configuration mechanisms.
- Do not log secrets.

## Verification

- Run a build after code changes.
- Run relevant tests when they are available.
- Do not consider a task complete if the project fails to build because of new
  changes.