Merge pull request #3944 from ann0see/ai/agents

Refine compiling and agent docs

Author: ann0see

AGENTS.md

@@ -1,20 +1,18 @@
 # Jamulus — Agent Instructions
 
-Real-time networked music jamming app. Qt/C++ qmake project. Client and server share one codebase; entry point: `src/main.cpp`. Configure `CONFIG` flags in `Jamulus.pro`.
+Real-time networked music jamming app. Qt/C++ qmake project. Client and server share one codebase; entry point: `src/main.cpp`. Qt project configuration in `Jamulus.pro`.
 
 **Make the smallest possible change. One logical change per PR. Never mix refactoring with fixes/features.**
 
 Priority order: Stability > Low latency / real-time safety > Backwards compatibility > Maintainability > New features. This order resolves conflicts only — new features are welcome.
 
 ---
 
-## Build
+## Build and Test
 
-Linux: `qmake && make` (use `qmake-qt5` on Fedora). Headless server: `qmake "CONFIG+=headless serveronly" && make`. First run: `git submodule update --init` (oboe for Android). Run `make distclean` before re-running `qmake` with different `CONFIG` flags. Full per-platform table: `COMPILING.md`.
+**Before running a build**, read `COMPILING.md` for your compile target. It includes build commands, platform-specific dependencies and `CONFIG` flags. `.github/autobuild` contains the build scripts for the GitHub Actions workflow. Read these files if you are stuck and need an example.
 
-macOS: `qmake QMAKE_APPLE_DEVICE_ARCHS=arm64 QT_ARCH=arm64 -spec macx-xcode Jamulus.pro` (Use `x86_64` on Intel Macs; `macx-clang` if using `make`). Then `xcodebuild build`, and `macdeployqt ./{Debug,Release}/Jamulus.app`.
-
-**Testing:** run headless server (args `-s -n`), connect a client (e.g. via: `-n -c localhost`; may need jackd running on Linux. Run dummy Jack via: `jackd -d dummy`), exercise the change; use the JSON-RPC API (`docs/JSON-RPC.md`) where possible. Connecting a client needs a non-`serveronly` build (Build section above); `serveronly` rejects `-c`. State what you tested in the PR with evidence. GitHub Actions builds multiple platforms — on failure read the failing step's log.
+**Testing:** run headless server (args `-s -n`), connect a client (e.g. via: `-n -c localhost`; may need jackd running on Linux. Run dummy Jack via: `jackd -d dummy`), exercise the change; use the JSON-RPC API (`docs/JSON-RPC.md`, enabled with `--jsonrpcport` and `--jsonrpcsecretfile`) where possible. Connecting a client needs a build without `serveronly` (`COMPILING.md`, "Compile time arguments"); `serveronly` rejects `-c`. State what you tested in the PR with evidence. GitHub Actions builds multiple platforms — on failure read the failing step's log.
 
 ## Never Do
 

COMPILING.md

@@ -110,7 +110,9 @@ You will need Xcode and Qt.
 
 First, install [Xcode from the Mac AppStore](https://apps.apple.com/us/app/xcode/id497799835?mt=12). Then [install homebrew](https://brew.sh/).
 
-After that you can install Qt via homebrew:
+**Note:** the official macOS builds use Qt6, plus Qt5 for the legacy Intel build; the exact versions are in `.github/workflows/autobuild.yml`. The steps below use Qt5 from Homebrew because it is easier to set up. To match the official build instead, install Qt6 via the [official open-source installer](https://www.qt.io/download-qt-installer).
+
+You can install Qt5 via homebrew:
 
 ```shell
 brew install Qt@5
@@ -120,6 +122,7 @@ brew link Qt@5 --force
 ### Generate Xcode Project file
 
 `qmake QMAKE_APPLE_DEVICE_ARCHS=arm64 QT_ARCH=arm64 -spec macx-xcode Jamulus.pro`
+
 **Note:** if you still build on x86_64, not Apple Silicon, you must replace `arm64` with `x86_64`.
 
 ### Print build targets and configuration in console
@@ -149,8 +152,9 @@ Schemes:
 
 `xcodebuild build`
 
-Will build the file and make it available in `./Release/Jamulus.app`
-In order to run the application, you need to run `macdeployqt ./Release/Jamulus.app` once to set up all required libraries and frameworks.
+Will build the file and make it available in `./Release/Jamulus.app`.
+
+**Note:** To run the application, you need to run `macdeployqt ./Release/Jamulus.app` once to set up all required libraries and frameworks.
 
 If you want to build the installer, please run the `deploy_mac.sh` script: `./mac/deploy_mac.sh`. You'll find the installer in the deploy/ folder.
 
@@ -184,7 +188,7 @@ If you want to build the installer, please run the `deploy_mac.sh` script: `./ma
 
 - Install Qt, including the Android support from the Qt installer
 - Follow Qt's [Getting Started with Qt for Android](https://doc.qt.io/qt-5/android-getting-started.html) instructions
-- Make sure Jamulus submodules are present, notably oboe:
+- **Important**: Make sure Jamulus submodules are present, notably oboe:
   `git submodule update --init`
 - Open Jamulus.pro in Qt Creator
 - Now you should be able to Build & Run for Android.