AkurAI-Framework / docs/cross-repo-binaries.md

Latest change 64c0dba2296e41722c261d7a9c4d804cb4fdc020 - OLI-176: document cross-repo binary pattern for CI by Ólafur Búi Ólafsson

# Cross-repo binaries in CI

Forge jobs run with a per-run sandbox `HOME` (`workspaces/<run>/.home`), so `$HOME`, `~`, `/home/<user>` and run-numbered artifact paths (`artifacts/<run>/<job>/...`) must never appear in `.akurai.yml`.

## Pattern

Consumers of the `akurai` binary (e.g. AkurAI-Platform's `package` job) read it from a stable installed path:

    ${AKURAI_FRAMEWORK_BIN:-/opt/akurai/bin/akurai}

- `/opt/akurai/bin/akurai` is root-owned (755), outside any sandbox HOME. Install or refresh it from a Framework release build: `sudo install -D -m755 target/release/akurai /opt/akurai/bin/akurai`.
- Override per job with `AKURAI_FRAMEWORK_BIN`.
- Host paths use `$AKURAI_HOST_HOME`; forge data and cross-repo git refs use `$AKURAI_BUILD_DATA` (e.g. `$AKURAI_BUILD_DATA/hosted/<Repo>.git`). Both are set by `akurai-build.service` (`60-toolchains.conf`).

## Enforcement

`AkurAI-Build/scripts/lint-akurai-yml.sh` rejects the forbidden forms; its `lint-config` job runs first in AkurAI-Build CI (tested by `scripts/test-lint-akurai-yml.sh`).

## Future

Replace the installed path with a forge "latest successful artifact of repo X on branch Y" reference once the forge supports it.