Neon-Vision-Editor/AGENTS.md

Codex Project Instructions - Neon Vision Editor

This file is the single source of truth for how Codex must work in this repository. Primary goal: ship small, safe changes that preserve existing behavior and architecture.

Neon Vision Editor is a native SwiftUI/AppKit editor focused on speed, stability, and minimalism. Avoid "helpful refactors." Fix or implement exactly what is requested.

---

0) Global Non-Negotiables (Always)

A. Preserve working code

• Do NOT touch working code unless strictly required.
• No opportunistic refactors.
• No renaming/moving for aesthetics.

B. No deprecated APIs

• Do not introduce deprecated Apple APIs.
• Modern Swift patterns only if required for the task.

C. Security & Privacy

• No telemetry.
• No sensitive logging (documents, prompts, tokens).
• Network calls only when explicitly user-triggered.
• API tokens must remain in Keychain.
• No weakening sandbox or file security.

D. Small, reviewable diffs

• Minimal patches only.
• If change is large, split into phases.
• If diff exceeds reasonable review scope, stop and split.

E. Multi-window correctness

• No accidental shared state across windows/scenes.
• Window state must remain isolated unless explicitly designed otherwise.

F. Main thread discipline

• UI mutations must be on main thread / @MainActor.
• No blocking IO, parsing, or network on main thread.

---

1) Hard Cross-Platform Rule (Blocking)

Neon Vision Editor ships on:

• macOS
• iOS
• iPadOS

ANY change targeting one platform MUST prove it does not break the others.

Mandatory compile safety

• No AppKit types in shared code without #if os(macOS) guards.
• No UIKit-only APIs leaking into macOS builds.
• Shared models must remain platform-agnostic.

Mandatory verification requirement (STRICT)

A patch is NOT acceptable without explicit iOS and iPadOS verification steps.

Your response MUST include either:

A) Exact build commands executed for:

• macOS
• iOS simulator
• iPad simulator

OR

B) A detailed manual verification checklist for:

• macOS
• iOS
• iPadOS

If this section is missing, the answer is incomplete.

Standard build verification command

Prefer the repo matrix script when Xcode and simulator services are available:

scripts/ci/build_platform_matrix.sh

It runs macOS, iOS Simulator, and iPad Simulator builds sequentially with CODE_SIGNING_ALLOWED=NO. By default it writes to .DerivedDataMatrix and removes it on exit. Use --keep-derived-data only when actively debugging build artifacts, then remove the derived data directory before finishing.

Equivalent individual commands, when the matrix script is not suitable:

xcodebuild -project "Neon Vision Editor.xcodeproj" -scheme "Neon Vision Editor" -configuration Debug -destination "generic/platform=macOS" -derivedDataPath .DerivedData-macOS CODE_SIGNING_ALLOWED=NO build
xcodebuild -project "Neon Vision Editor.xcodeproj" -scheme "Neon Vision Editor" -configuration Debug -sdk iphonesimulator -destination "generic/platform=iOS Simulator" -derivedDataPath .DerivedData-iOS CODE_SIGNING_ALLOWED=NO build
xcodebuild -project "Neon Vision Editor.xcodeproj" -scheme "Neon Vision Editor" -configuration Debug -sdk iphonesimulator -destination "generic/platform=iOS Simulator" -derivedDataPath .DerivedData-iPad TARGETED_DEVICE_FAMILY=2 CODE_SIGNING_ALLOWED=NO build

Remove any .DerivedData* folders created during verification before returning.

---

2) Accessibility Rule (Non-Optional)

Every UI-affecting change must consider:

• VoiceOver (macOS + iOS/iPadOS)
• Keyboard navigation (macOS + iPad with keyboard)
• Focus management

You must explicitly state:

• What accessibility elements were affected
• How labels/traits remain correct
• That focus order is preserved
• That no UI state traps accessibility focus

If accessibility validation is missing, the patch is incomplete.

---

3) Mode Selection (Declare One)

At the top of every implementation response, state:

• MODE: BUGFIX/DEBUG or
• MODE: NEW FEATURE

If unclear, default to BUGFIX/DEBUG.

---

MODE: BUGFIX / DEBUG

Scope

Crashes, regressions, incorrect behavior, UI glitches, build failures, performance issues.

Rules

• Do not change expected behavior unless clearly wrong.
• Fix smallest surface possible.
• Prefer guards and state corrections over redesign.
• Debug logs must be #if DEBUG gated.

Required Output Structure

1. Repro steps
2. Root cause hypothesis
3. Minimal patch plan
4. Patch
5. Verification
   • macOS
   • iOS
   • iPadOS
   • Accessibility checks (if UI touched)
6. Risk assessment

If any section is missing, the response is invalid.

---

MODE: NEW FEATURE

Scope

New UI, new settings, new editor capability, new integration.

Rules

• Must fit lightweight editor philosophy.
• No IDE bloat.
• Integrate into existing infrastructure.
• No hidden default behavior changes.

Platform Requirements

• Must define macOS interaction model.
• Must define iOS touch interaction.
• Must define iPad keyboard/multitasking behavior.
• If platform-limited, explicitly guard and document.

Required Output Structure

1. User problem
2. Proposed solution
3. Why this fits scope
4. Alternatives considered
5. Minimal phased plan
6. Patch
7. Acceptance criteria
8. Verification checklist
   • macOS
   • iOS
   • iPadOS
   • Accessibility validation
9. Security/privacy impact
10. Performance impact

If cross-platform verification is missing, the patch is invalid.

---

4) Repo Workflows and Commands

Local git hooks

Install the repo hooks before routine development:

scripts/install_git_hooks.sh

The pre-commit hook auto-bumps CURRENT_PROJECT_VERSION for non-doc-only commits. Set NVE_SKIP_BUILD_NUMBER_BUMP=1 only for intentional release/doc automation commits that should not bump the build number.

Release validation

Use dry-run validation before creating or pushing release tags:

scripts/release_dry_run.sh v0.6.2

Use the full release orchestrator only from a clean, authenticated repo with gh available:

scripts/release_all.sh v0.6.2 --dry-run
scripts/release_all.sh v0.6.2 notarized

If an existing tag must be repointed as part of a notarized release, the supported command shape is:

scripts/release_all.sh v0.6.2 notarized --retag

Use --resume-auto to continue an interrupted release flow after checking whether local and remote tags already exist.

Release preflight

For release-specific local checks, run:

scripts/ci/release_preflight.sh v0.6.2

This validates release docs, README metrics freshness when applicable, critical runtime tests, and icon payloads.

---

5) Code Style Expectations

• Explicit naming over comments.
• Comments explain WHY, not WHAT.
• No clever hidden logic.
• No dead code.
• No temporary hacks.

---

6) Absolute Stop Conditions

Stop and ask for clarification if:

• Feature requires architectural rewrite.
• Expected behavior is ambiguous.
• Security posture would change.
• Cross-platform behavior cannot be guaranteed.

Do NOT guess.

Remove .DerivedData* folders after use so they are not accumulated.