AkurAI-Build

Latest change 1f6e68b042d24122753dc5b677fceb64b94e49b4 - Pin actual Rust 1.97 build toolchain by Ólafur Búi Ólafsson

# AkurAI Build operating contract

This is the first document to consult for every task.

## Command ladder

1. Read `skills/akurai-build/SKILL.md`.
2. Check `./deploy.sh help` for source, host, service, GitHub, EC2, Nginx, TLS, version, release, rollback, health, and logs operations.
3. Check `./deploy.sh cli --help` for repositories, runs, jobs, artifacts, promotions, recovery, and diagnostics.
4. Use the existing maintained command.
5. If no command exists, run only the smallest bounded **read-only probe** needed to understand the gap.
6. Once the probe succeeds, implement that operation in `deploy.sh` or `akurai`, add a focused check, and update this document plus the skill before performing the mutation.

## Prohibited direct mutations

Do not directly run SSH mutations, package managers, `systemctl`, Docker mutations, Nginx/certbot changes, database tools, artifact copies, Git commit/push, or edits to installed/runtime files. Do not hand-edit anything below:

- `~/.local/lib/akurai-build`
- `~/.local/share/akurai-build`
- `~/.config/akurai-build`
- `/etc/systemd/system/akurai-build.service`
- EC2 `/etc/nginx` or `/etc/letsencrypt`

Repository source changes happen only in `~/Projects/AkurAI-Build`; run `./deploy.sh sync` before Titan checks, then `./deploy.sh check`, and publish with `./deploy.sh publish` or `./deploy.sh release`; both maintain the repository-local GitHub author identity.

## Maintained operations

```sh
./deploy.sh sync
./deploy.sh edge-probe
./deploy.sh probe
./deploy.sh bootstrap
./deploy.sh lock
./deploy.sh version show
./deploy.sh version patch|minor|major "summary"
./deploy.sh format
./deploy.sh clean-build
./deploy.sh recover-checks
./deploy.sh check
./deploy.sh docker-smoke
./deploy.sh build
./deploy.sh build-info
./deploy.sh deploy-local
./deploy.sh deploy
./deploy.sh vhost
./deploy.sh status-local
./deploy.sh status
./deploy.sh logs 100
./deploy.sh rollback
./deploy.sh publish "summary"
./deploy.sh release patch|minor|major "summary"
./deploy.sh cli ...
```

Source-changing/checking commands automatically run `sync` when forwarded from another host. Cargo incremental compilation is disabled because version-only rebuilds reproduced corrupt `rust-lld` objects in the Syncthing-backed tree. `check` bounds formatting, Clippy, and tests to 30/180/90 seconds with process-group termination so a deadlock is killed instead of hanging.

`docker-smoke` runs the real restricted Docker executor and verifies artifact creation on Titan. `deploy-local` verifies the Titan service independently with a bounded 15-second readiness wait. `deploy` owns the entire route to `https://akurai-builds.olibuijr.com`: Titan build/install/migration/system service with the Docker supplementary group, Pi skill, EC2 DNS/HTTP/S reachability, AkurAI-VPN upstream, Nginx, certificate presence/30-day expiry check, issuance or renewal, and local/public health verification.

Version components are bounded to `1..10`: `major.minor.patch`, starting at `1.1.1`. Patch `10` rolls to the next minor; minor `10` rolls to the next major; `10.10.10` is terminal. Every published version must match the newest `CHANGELOG.md` entry; `publish` compares against Git `HEAD` so non-version `Cargo.toml` edits cannot bypass a bump.

## CI operations

```sh
./deploy.sh cli doctor
./deploy.sh cli repo list
./deploy.sh cli repo add NAME URL --branch main
./deploy.sh cli run NAME --git-ref main
./deploy.sh cli runs --repo NAME --limit 20
./deploy.sh cli show RUN
./deploy.sh cli wait RUN --timeout 3600
./deploy.sh cli logs RUN --failed
./deploy.sh cli retry RUN
./deploy.sh cli promote RUN ENVIRONMENT
./deploy.sh cli artifact get ARTIFACT OUTPUT
```

Parse the JSON envelope and require persisted `succeeded` status before reporting success. Never read or expose protected token/key/secret values.

## Learning loop

Run history, immutable commits, logs, artifact digests, deployment records, health results, tests, changelog entries, and rollback evidence are the system's knowledge. Improve commands and documentation from that evidence. Never implement autonomous unreviewed source mutation.