If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/azahar-emu/azahar shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit today
• 16 active contributors
• Distributed ownership (top contributor 44% of recent commits)
• GPL-2.0 licensed
• CI configured
• ⚠ GPL-2.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live azahar-emu/azahar repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/azahar-emu/azahar.

What it runs against: a local clone of azahar-emu/azahar — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in azahar-emu/azahar | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of azahar-emu/azahar. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/azahar-emu/azahar.git
#   cd azahar
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of azahar-emu/azahar and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "azahar-emu/azahar(\\.git)?\\b" \\
  && ok "origin remote is azahar-emu/azahar" \\
  || miss "origin remote is not azahar-emu/azahar (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-2.0" \\
  || miss "license drift — was GPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"
test -f "CMakeModules/GenerateBuildInfo.cmake" \\
  && ok "CMakeModules/GenerateBuildInfo.cmake" \\
  || miss "missing critical file: CMakeModules/GenerateBuildInfo.cmake"
test -f "dist/languages/.tx/config" \\
  && ok "dist/languages/.tx/config" \\
  || miss "missing critical file: dist/languages/.tx/config"
test -f "AI-POLICY.md" \\
  && ok "AI-POLICY.md" \\
  || miss "missing critical file: AI-POLICY.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/azahar-emu/azahar"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Azahar is an open-source Nintendo 3DS emulator written in C++ that evolved from merging PabloMK7's Citra fork and the Lime3DS project after Citra's shutdown. It executes 3DS ARM binaries, handles the 3DS OS layer, GPU rendering via OpenGL/Vulkan, and provides multi-platform support (Windows, macOS, Linux, Android, iOS) with both a Qt desktop UI and native mobile interfaces (Kotlin for Android, Objective-C++ for iOS). Monorepo with a CMake-driven build system (CMakeLists.txt, CMakeModules/) supporting cross-platform compilation. Core emulation engine is C++ (src/ implied by file structure). Mobile native code: src/android/ (Kotlin) and src/ios/ (Objective-C++). CI layer (.ci/) contains platform-specific build scripts (linux.sh, windows.sh, macos.sh, android.sh, ios.sh). Desktop UI likely Qt-based. Build configuration modularized via CMakeModules/ with specific modules for Android NDK (AndroidNdkModules.cmake), external downloads (DownloadExternals.cmake), and build info generation (GenerateBuildInfo.cmake, GenerateSCMRev.cmake).

Game preservation enthusiasts and developers who want to play Nintendo 3DS titles on modern hardware; contributors with expertise in emulation, graphics APIs, ARM instruction sets, or mobile development who want to advance the de-facto successor to Citra.

Actively developed and production-ready: the project is distributed across Windows installer, macOS universal binaries, Google Play Store (io.github.lime3ds.android), and Flathub with documented CI/CD pipelines (.github/workflows/build.yml shows multi-platform builds). GitHub Actions enforce code formatting (format.yml) and license headers (license-header.yml), indicating established processes. However, maturity varies by platform—desktop is stable while mobile (Android/iOS) continues rapid iteration.

Moderate risk: the codebase is large (9.1M lines of C++) with complex dependencies on graphics libraries and OS-level emulation details, making code reviews critical. The reliance on a merged codebase from two competing Citra forks (PabloMK7 + Lime3DS) introduces integration risk. Legal risk exists around copyright/licensing given the sensitive nature of emulation and ROM handling—mitigated by strict license header enforcement (.ci/license-header.rb). No obvious single-maintainer bottleneck visible, but mobile platforms (Kotlin, Objective-C++) may lag desktop in attention.

Active multi-platform development: iOS support is being added (.ci/ios.sh, dist/apple/ with Info.plist.in and LaunchScreen.storyboard); Android app is published and maintained (Google Play Store link in README); code quality enforcement is ongoing (clang-format.sh, license-header.yml workflows); and libretro integration is being developed (.ci/libretro-ci.yml, libretro-pack.sh). GitHub Actions workflows show automated building and testing for multiple targets.

git clone https://github.com/azahar-emu/azahar.git
cd azahar
mkdir build && cd build
cmake ..
make -j$(nproc)

For Android (requires Android NDK, Java, Gradle): ./ci/android.sh. For macOS universal: ./ci/macos-universal.sh. For iOS: ./ci/ios.sh. Refer to respective .ci/*.sh scripts for platform-specific dependencies and environment setup.

Daily commands: Desktop (Linux/macOS/Windows after build):

./build/bin/azahar  # or citra (binary name)

Android: Install APK from Releases or Google Play Store, launch app. iOS: Build and deploy via ./ci/ios.sh and Xcode (or TestFlight from releases). LibretrO core: Use ./ci/libretro-pack.sh to generate core, load in RetroArch.

• CMakeLists.txt — Root build configuration that orchestrates the entire project compilation across all platforms (Windows, macOS, Linux, Android, iOS); every contributor must understand the build system.
• .github/workflows/build.yml — CI/CD pipeline definition that validates all commits across multiple platforms; critical for understanding how code reaches releases.
• CMakeModules/GenerateBuildInfo.cmake — Build metadata generation system that embeds version and SCM information; breaking this breaks versioning across all targets.
• dist/languages/.tx/config — Transifex internationalization configuration; defines how translations are synced and managed across 25+ languages.
• AI-POLICY.md — Project governance and AI contribution policy; establishes community standards and legal boundaries for all contributors.
• README.md — Primary project documentation covering installation, the Citra/Lime3DS merge history, and download channels across platforms.
• .gitmodules — Git submodule configuration for external dependencies and vendored code; affects dependency resolution for all clones.

Add Support for a New Platform/Architecture

1. Create a platform-specific build script in .ci/ directory (e.g., .ci/newplatform.sh) following the pattern of .ci/android.sh or .ci/ios.sh (.ci/newplatform.sh)
2. Add CMake toolchain configuration in CMakeModules/ for cross-compilation and platform-specific flags (CMakeModules/NewPlatformToolchain.cmake)
3. Register the new platform in .github/workflows/build.yml as a new job in the matrix strategy (.github/workflows/build.yml)
4. Add distribution packaging config in dist/ (e.g., dist/app_name.manifest for new platform specific metadata) (dist/newplatform-manifest)
5. Update README.md Installation section with download link and instructions for the new platform (README.md)

Add Support for a New Language/Locale

1. Create a new .ts (Qt Linguist) file in dist/languages/ with the locale code (e.g., dist/languages/de_DE.ts) (dist/languages/xx_XX.ts)
2. Register the new language in .tx/config under the [o:azahar-emu.r:azahar] section with file pattern mapping (dist/languages/.tx/config)
3. Commit the new translation file; Transifex will auto-sync translations via .github/workflows/transifex.yml (.github/workflows/transifex.yml)
4. Update dist/languages/README.md to document the new language addition (dist/languages/README.md)

Modify Build Configuration or Add CMake Dependency

1. Edit CMakeLists.txt to declare the new dependency using find_package() or add_subdirectory() (CMakeLists.txt)
2. If external, add download logic in CMakeModules/DownloadExternals.cmake using ExternalProject_Add() (CMakeModules/DownloadExternals.cmake)
3. For cross-platform toolchain adjustments, modify relevant CMakeModules/*.cmake file (AndroidNdkModules.cmake, etc.) (CMakeModules/AndroidNdkModules.cmake)
4. Test the change locally and via .github/workflows/build.yml to ensure all platform CI jobs pass (.github/workflows/build.yml)

• CMake — Cross-platform build system enabling single configuration to target Windows, macOS, Linux, Android, iOS with minimal duplication
• GitHub Actions — Native CI/CD for multi-platform matrix builds; free compute for open-source; native integration with repository
• Qt Linguist (.ts files) — Standard Qt framework i18n system; enables community translation via Transifex while maintaining single codebase
• Transifex — Crowdsourced translation platform; automated sync via webhook reduces manual i18n overhead
• Flatpak/Flathub — Sandboxed, distribution-agnostic Linux packaging; simplifies multi-distro deployment

• Citra fork-based architecture (vs. ground-up rewrite)

  • Why: Inherit battle-tested 3DS emulation logic; faster path to feature parity after Citra shutdown
  • Consequence: Locked to Citra's architectural patterns and code style; merge conflicts with upstream abandoned codebase

• Multiple platform-specific build scripts in .ci/ (vs. unified cross-platform builder)

  • Why: Each platform has unique SDKs, signing, and packaging requirements; explicit per-platform control
  • Consequence: Higher maintenance burden; easier to introduce platform-specific bugs; build.yml matrix is complex

• Submodules for external dependencies (vs. package managers)

  • Why: Deterministic builds; offline builds; control over dependency versions and patches
  • Consequence: Larger repository size; submodule synchronization friction; developers must understand git submodule workflow

• Qt framework for UI (inherited from Citra)

  • Why: Native desktop experience across platforms; mature, battle-tested; Citra ecosystem already tooled around it
  • Consequence: Qt licensing considerations; desktop-first (web UI not prioritized); larger binary footprint

• Web-based emulator UI (desktop/native application only)
• Real-time multiplayer (local network or online play not supported)
• Linux-exclusive emulator (multi-platform first-class support required)
• Commercial licensing (open-source only; no closed-source derivatives)
• Game modding/ROM hacking tools (emulator-only scope)

License headers mandatory: Every source file must include the project's license header (enforced by .ci/license-header.rb workflow); missing headers will fail CI. CMake version sensitivity: Build system is modular and may require specific CMake versions; check CMakeLists.txt for cmake_minimum_required(). Android NDK path: Android builds require ANDROID_NDK_ROOT environment variable set and correct NDK version (check .ci/android.sh for specifics). Submodules: .gitmodules likely references external dependencies (emulation cores, libraries); git clone --recursive required. Build artifact size: 3DS emulation with multi-platform support generates large binaries; disk space and build time can be significant. GPU backend toggle: Code likely has conditional compilation for OpenGL vs. Vulkan—wrong backend selection can cause runtime crashes. iOS signing: iOS builds require valid Apple developer certificate and provisioning profile (dist/apple/ suggests this is complex).

• ARM Instruction Set Emulation (Thumb/Thumb-2) — The 3DS CPU is ARM11, requiring a complete interpreter and/or JIT compiler to execute game binaries; understanding ARM ISA variants is essential for debugging emulation correctness.
• GPU Command Submission & Register Emulation — The 3DS GPU (PICA200) has a unique command buffer and register layout; Azahar must translate these to OpenGL/Vulkan calls, requiring deep knowledge of graphics command queues.
• Memory Management & Virtual Address Translation — 3DS games expect a specific virtual memory layout with page tables and caching behaviors; emulation must accurately model MMU (Memory Management Unit) to avoid memory corruption bugs.
• JIT Compilation vs. Interpretation Trade-offs — Azahar likely switches between ARM interpreter (correctness, debugging) and JIT (speed); understanding the trade-offs is critical for performance optimization contributions.
• Cross-Platform UI Abstraction (Qt for Desktop, Native for Mobile) — Azahar maintains a single core engine with separate UI layers (Qt, Kotlin, Objective-C++); contributors must understand how core emulation is decoupled from platform-specific presentation.
• Filesystem Virtualization & ROMFS/Save Data Emulation — 3DS games access virtual filesystems (SD card, internal storage, game ROMs); Azahar must intercept and map these to host filesystems while preserving 3DS save formats.
• Android NDK & JNI Bridges — The Android build bridges Kotlin UI code to C++ emulation core via JNI; understanding memory passing and thread safety across language boundaries is essential for mobile development.

• citra-emu/citra — The original 3DS emulator project that Azahar forked from; understanding Citra's architecture is essential context for this codebase.
• PabloMK7/citra — PabloMK7's Citra fork (one of the two merged projects); contains the desktop improvements and optimizations integrated into Azahar.
• Lime3DS/Lime3DS — The Lime3DS project (second merged project); likely contains mobile-specific code and alternative implementations that were unified into Azahar.
• libretro/RetroArch — Azahar integrates with libretro (.ci/libretro-ci.yml); RetroArch is the primary frontend for the libretro Azahar core.
• yuzu-emu/yuzu — Similar open-source Nintendo console emulator (Switch); useful reference for multi-platform emulation architecture and CI/CD patterns.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add platform-specific CI workflow validation for build scripts

The repo has comprehensive build scripts for multiple platforms (.ci/android.sh, .ci/ios.sh, .ci/macos.sh, .ci/windows.sh, .ci/linux.sh, .ci/mxe.sh) but no dedicated CI workflow to validate syntax and basic functionality of these scripts. A new GitHub Action workflow could catch shell script errors early, preventing broken builds in platform-specific pipelines that may not run on every PR.

• [ ] Create .github/workflows/build-scripts-lint.yml to run shellcheck on all .ci/*.sh files
• [ ] Add validation that critical build scripts are syntactically correct before merge
• [ ] Reference the existing .ci/clang-format.sh pattern for consistency
• [ ] Test against the 8 platform-specific build scripts in the .ci directory

Create missing documentation for CMake configuration modules and build system

The CMakeModules directory contains 9 specialized modules (AndroidNdkModules, BundleTarget, GenerateBuildInfo, GenerateSCMRev, etc.) but there's no documentation explaining their purpose, dependencies, or how contributors should modify them. This is a barrier for contributors wanting to improve cross-platform support or packaging.

• [ ] Create CMakeModules/README.md explaining each module's purpose (especially GenerateBuildInfo.cmake, GenerateSCMRev.cmake, GenerateSettingKeys.cmake)
• [ ] Document the build configuration flow and when each module is invoked
• [ ] Add examples for common customization scenarios (custom package layouts, new platforms)
• [ ] Link to this documentation from the main README.md build instructions section

Implement language file validation CI workflow for translation completeness

The repo has 8+ translation files in dist/languages/*.ts (catalán, danish, german, greek, spanish variants, finnish, french, hungarian) with a Transifex configuration, but no CI workflow validates that translation files are well-formed, complete, or properly indexed. This could catch broken translations before release.

• [ ] Create .github/workflows/validate-translations.yml to parse all .ts files in dist/languages/
• [ ] Add validation that each translation file has consistent key counts compared to the base language
• [ ] Check for malformed XML/TS structure that could break the build
• [ ] Reference the existing .ci/transifex.sh and .github/workflows/transifex.yml for context on translation workflow

• Add unit tests for ARM instruction decoder/emulator in src/core/arm/; currently test coverage appears minimal. Start with a single instruction class and create tests/ directory following xUnit pattern.: Emulation correctness is critical and currently undertested; this improves reliability and helps newcomers learn the CPU layer.
• Document mobile-specific build prerequisites in README.md; currently only desktop instructions are clear. Create BUILDING.md with per-platform sections including Android NDK version, iOS certificate setup, and Gradle configuration.: Mobile contributor onboarding is rough; clear prerequisites reduce friction and increase contribution diversity.
• Add GitHub Actions workflow status badges to README for each platform (Windows, macOS, Linux, Android, iOS) linking to .github/workflows/build.yml; currently only generic CI badge exists.: Users and contributors can't quickly see which platforms are stable; per-platform badges improve transparency and help triage platform-specific issues.

• Medium · Potential Hardcoded Configuration in CMake Build System — CMakeModules/aqt_config.ini, CMakeModules/*.cmake. The CMakeModules directory contains several build configuration files (aqt_config.ini, GenerateSCMRev.cmake, GenerateSettingKeys.cmake) that may contain hardcoded settings, credentials, or sensitive paths. Without reviewing the actual content, there's a risk these files could expose build secrets or API keys. Fix: Audit all CMake configuration files to ensure no credentials, API keys, or sensitive paths are hardcoded. Use environment variables or secure secret management for build-time secrets.
• Medium · CI/CD Script Security Review Needed — .ci/android.sh, .ci/ios.sh, .ci/docker.sh, .ci/linux.sh, .ci/windows.sh, .ci/macos.sh, .ci/mxe.sh, .ci/pack.sh. Multiple CI/CD shell scripts (.ci/*.sh) are present that orchestrate builds across multiple platforms (Android, iOS, Linux, Windows, macOS). These scripts may execute external commands or download dependencies without proper validation, creating potential vectors for supply chain attacks or arbitrary code execution. Fix: Review all shell scripts for: (1) Proper input validation and escaping, (2) Verification of downloaded dependencies (checksums, signatures), (3) Use of HTTPS with certificate pinning for downloads, (4) Principle of least privilege in execution, (5) Audit logging of sensitive operations.
• Medium · GitHub Workflow File Security Configuration — .github/workflows/build.yml, .github/workflows/libretro.yml, .github/workflows/format.yml, .github/workflows/ci-merge.js. The .github/workflows directory contains CI/CD pipeline definitions (build.yml, libretro.yml, format.yml, etc.). These workflow files may have overly permissive permissions, exposed secrets in logs, or insecure checkout configurations that could lead to privilege escalation or credential theft. Fix: Audit workflow files for: (1) Principle of least privilege PERMISSIONS declarations, (2) Ensure secrets are not logged or exposed in build artifacts, (3) Use GITHUB_TOKEN with minimal required scopes, (4) Enable branch protection rules, (5) Review ci-merge.js for injection vulnerabilities, (6) Use actions from verified publishers only.
• Low · Transifex Integration Potential Risk — .ci/transifex.sh, .github/workflows/transifex.yml, .tx/config. The .ci/transifex.sh script and .github/workflows/transifex.yml indicate integration with Transifex for localization. External service integrations can be attack vectors if credentials are mishandled or if responses aren't properly validated. Fix: Ensure: (1) Transifex API tokens are stored only in GitHub Secrets, never in code, (2) Validate all translations before merging to prevent XSS or injection attacks, (3) Use least-privilege API tokens with read-only access where possible, (4) Monitor for unauthorized access to Transifex account.
• Low · License Header Validation Script Review — .ci/license-header.rb, .github/workflows/license-header.yml. The .ci/license-header.rb script performs automated license header validation. Ruby scripts that modify or validate files can be vectors for code injection if not properly implemented. Fix: Review the Ruby script to ensure: (1) No arbitrary code execution, (2) Proper regex escaping to prevent ReDoS attacks, (3) Safe file handling without symlink attacks, (4) Input validation on file paths.
• Low · Submodule Dependency Chain Risk — .gitmodules. The .gitmodules file indicates use of Git submodules for external dependencies. Submodules create supply chain risks if dependent repositories are compromised or deleted. Fix: Implement: (1) Periodic audits of submodule sources, (2) Pin to specific commits rather than branches, (3) Verify submodule repository ownership and maintenance status, (4) Consider vendoring critical dependencies instead of using submodules, (5) Use GPG-signed commits for submodule updates.
• Low · Desktop Application File Configurations — undefined. Desktop entry files (dist/azahar.desktop, dist/azahar-room.desktop) and application Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.