retrace AGENTS.md

Retrace - Agent Guide

Standard: This file follows the AGENTS.md specification - a vendor-agnostic standard for AI agent guidance. For human-readable project information, see README.md.

Retrace is a local-first screen recording and search application for macOS, inspired by Rewind AI. It captures screens, extracts text via OCR, and makes everything searchable—all locally on-device.

Status: Core screen capture (CGWindowListCapture), OCR (Vision), full-text search (FTS5), HEVC encoding, and Rewind import are working. Audio transcription and vector search are planned for future releases.

---

Quick Reference

• Module-Specific Instructions: Each module has its own AGENTS.md file in its directory
• Human Documentation: README.md, CONTRIBUTING.md, and AI_ISSUE_TEMPLATE.md
• Issue Reporting: Use AI_ISSUE_TEMPLATE.md and gh issue create --body-file ... for AI-authored GitHub issues
• Bug Fixes by Non-Owners: If the user is fixing a bug/crash and does not appear to be the repo owner, encourage them to create or link a GitHub issue before making code changes
• Technical Audit Docs: local/docs/ (includes deep-dive implementation and performance audit notes)

---

Project Commands

Build & Test

# Build all targets
swift build

# Run all tests
swift test

# Run specific module tests
swift test --filter DatabaseTests

# Run specific test
swift test --filter testSpecificMethod

# Clean build artifacts
rm -rf .build/

---

Project Structure

retrace/
├── AGENTS.md                    # This file - main agent coordination
├── .env.example                 # Template for local release credentials (copy to .env)
├── .github/                     # GitHub configuration
│   ├── CODEOWNERS
│   ├── FUNDING.yml
│   └── ISSUE_TEMPLATE/
│       └── bug_report.yml       # GitHub bug report form aligned with AI issue template
├── AI_ISSUE_TEMPLATE.md         # Canonical markdown template for AI-authored bug reports
├── README.md                    # Human-readable project overview
├── CONTRIBUTING.md              # Contribution guidelines
├── Package.swift                # Swift Package Manager configuration
├── scripts/                     # Build/release/validation scripts
│   ├── release.sh               # End-to-end release automation
│   ├── create-release.sh        # Release build + packaging helper
│   ├── check_no_nanoseconds_sleep.sh # Guardrail for Task.sleep(nanoseconds:)
│   ├── validate_sleep_wake_stability.sh # Sleep/wake soak validation workflow
│   └── validate_darkwake_watchdog.sh # Automated darkwake watchdog regression validation
│
├── Shared/                      # CRITICAL: Shared types and protocols
│   ├── Logging.swift            # Central log utility (Log.debug/info/warning/error)
│   ├── AppPaths.swift           # Application path configuration
│   ├── BGRAImageUtilities.swift # Shared BGRA conversion + patch extraction helpers
│   ├── MasterKeyManager.swift   # Keychain-backed master key creation + recovery phrase export
│   ├── ReversibleOCRScrambler.swift # Deterministic reversible OCR patch scrambling + text protection
│   ├── Models/                  # Data types used across modules
│   │   ├── Frame.swift          # FrameID, CapturedFrame, VideoSegment
│   │   ├── Text.swift           # ExtractedText, OCRTextRegion
│   │   ├── TextRegion.swift     # OCR text region types
│   │   ├── Search.swift         # SearchQuery, SearchResult
│   │   ├── Segment.swift        # Segment data model
│   │   ├── Config.swift         # Configuration types
│   │   ├── Errors.swift         # Error types
│   │   ├── Audio.swift          # Audio model types (Release 2)
│   │   ├── FilterCriteria.swift # Timeline/search filter criteria
│   │   ├── Source.swift         # Data source enum (native, rewind, etc.)
│   │   ├── Tag.swift            # Tag model types
│   │   └── Comment.swift        # Segment comment and attachment models
│   └── Protocols/               # Module interfaces
│       ├── DatabaseProtocol.swift
│       ├── StorageProtocol.swift
│       ├── CaptureProtocol.swift
│       ├── ProcessingProtocol.swift
│       ├── SearchProtocol.swift
│       └── MigrationProtocol.swift
│
├── Database/                    # SQLite + FTS5 storage
│   ├── AGENTS.md                # Module-specific agent instructions
│   ├── DatabaseManager.swift    # Main database coordinator
│   ├── DatabaseConnection.swift # SQLite connection management
│   ├── DatabaseConfig.swift     # Database configuration
│   ├── FTSManager.swift         # Full-text search management
│   ├── IDMappingService.swift   # ID mapping between sources
│   ├── Schema.swift             # Current schema definition
│   ├── Migrations/              # Schema migration scripts
│   ├── Queries/                 # Query implementations
│   └── Tests/
│
├── Storage/                     # File I/O, HEVC encoding
│   ├── AGENTS.md
│   ├── StorageManager.swift
│   ├── ImageExtractor.swift     # Extract frames from video files
│   ├── IncrementalSegmentWriter.swift
│   ├── SegmentWriterImpl.swift
│   ├── FileManager/             # File system utilities
│   ├── VideoEncoder/            # HEVC video encoding
│   ├── WAL/                     # Write-Ahead Log (WALManager, RecoveryManager)
│   └── Tests/
│
├── Capture/                     # CGWindowListCapture integration
│   ├── AGENTS.md
│   ├── CaptureManager.swift
│   ├── ScreenCapture/           # Screen capture implementation
│   ├── Deduplication/           # Perceptual hash deduplication
│   ├── Metadata/                # AppInfoProvider, BrowserURLExtractor
│   └── Tests/
│
├── Processing/                  # OCR and text extraction
│   ├── AGENTS.md
│   ├── ProcessingManager.swift
│   ├── FrameProcessingQueue.swift # Async frame processing queue
│   ├── URLExtractor.swift       # URL extraction from OCR text
│   ├── OCR/                     # Vision framework OCR
│   ├── Accessibility/           # Accessibility API integration
│   ├── TextMerger/              # Text merging utilities
│   └── Tests/
│
├── Search/                      # Full-text search
│   ├── AGENTS.md
│   ├── SearchManager.swift
│   ├── IngestionManager.swift   # Search index ingestion
│   ├── QueryParser/             # Query parsing (app:, date:, -exclude)
│   ├── Ranking/                 # Result ranking implementation
│   ├── VectorSearchTODO/        # Planned for Release 2 (excluded from build)
│   └── Tests/
│
├── Migration/                   # Import from other apps
│   ├── AGENTS.md
│   ├── MigrationManager.swift
│   └── Importers/               # Source-specific importers (Rewind)
│
├── App/                         # Main application coordinator
│   ├── AppCoordinator.swift     # Central coordinator (orchestrates all modules)
│   ├── DataAdapter.swift        # Data layer adapter (DB queries, transformations)
│   ├── FeedbackRecentMetricSupport.swift # Shared feedback-export metric models and sanitization helpers
│   ├── ServiceContainer.swift   # Dependency injection container
│   ├── AppLifecycle.swift       # App lifecycle management
│   ├── ModelManager.swift       # Model management
│   ├── OnboardingManager.swift  # First-run onboarding flow
│   ├── RetentionManager.swift   # Data retention policies
│   └── Tests/
│       ├── FeedbackRecentMetricSupportTests.swift # Feedback-export metric sanitization coverage
│       ├── InPageURLCaptureRoutingTests.swift
│       ├── MasterKeyManagerTests.swift
│       ├── ServiceContainerRewindCutoffTests.swift # Rewind cutoff defaults and latest-frame probe coverage
│       ├── TestLogger.swift
│       ├── TimelineStillDiskWriterTests.swift
│       └── UnexpectedRecordingStopHeuristicTests.swift # Unexpected-stop watchdog heuristic coverage
│
└── UI/                          # SwiftUI interface
    ├── AGENTS.md
    ├── RetraceApp.swift         # App entry point
    ├── ContentView.swift        # Root content view
    ├── CrashRecoveryHelper/     # Bundled crash-recovery XPC helper executable
    ├── CrashRecoverySupport/    # Shared crash-recovery support code for app + helper targets
    ├── LaunchAgents/            # Embedded SMAppService launch-agent plists
    ├── Components/              # Reusable UI components (MenuBarManager, HotkeyManager, etc.)
    │   ├── MasterKeyRedactionFlowCoordinator.swift # Shared missing-master-key prompt/recovery coordinator
    │   ├── HoverLatchedScrollMonitor.swift # Shared nested-scroll latch helper for hover-routed inner scroll regions
    │   └── ProcessMonitorModels.swift # System Monitor snapshot/models + ranking helpers
    ├── ViewModels/              # View models (Dashboard, Search, Timeline, Feedback, Settings)
    │   └── Settings/            # Settings-specific view models and extracted helper logic
    ├── Views/
    │   ├── Dashboard/           # App usage analytics views
    │   ├── FullscreenTimeline/  # Timeline scrubbing & playback (10 views)
    │   ├── Search/              # Search UI (SearchView, ResultRow, FrameViewer)
    │   ├── Settings/            # Settings shell, support components, and extracted section/action files
    │   │   └── Sections/        # Concern-split settings sections, verification flows, and shared actions
    │   ├── Onboarding/          # Onboarding flow
    │   └── Feedback/            # Feedback form, diagnostics presentation, and submission/export helpers
    └── Tests/
        ├── Dashboard/           # Dashboard-specific XCTestCase files
        ├── MenuBar/             # Menu bar XCTestCase files
        ├── Search/              # Search/deeplink XCTestCase files
        ├── Settings/            # Settings XCTestCase files
        ├── Support/             # Shared XCTest helpers and support-only tests
        ├── SystemMonitor/       # System monitor XCTestCase files
        └── Timeline/            # Timeline XCTestCase files