AkurAI-Build

Latest change 1488f88860de09bbb6791f4c67d3a8a8a3e0765f - Replace the JSON CI CLI with a full read/write akurai-build MCP tool set (repo add/host/sync/rename/remove/visibility/branches/tree, run queue/wait/retry/promote, artifact get, doctor, init); keep keygen/migrate/serve as plain CLI subcommands; update skill and deploy.md to the MCP tool set by Ólafur Búi Ólafsson

# AkurAI Build operating contract

## 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 the `akurai-build` MCP tool set (`tools/list` over `./deploy.sh mcp`) for repositories, runs, jobs, artifacts, and promotions.
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 mesh-recover
./deploy.sh http-smoke
./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 binfmt
./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 mcp
```

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.
`mesh-recover` restarts the managed VPN tunnels on Titan and EC2 after a host reboot, then waits until EC2 can reach AkurAI Build's private health endpoint; it fails closed if the upstream does not return.

`http-smoke` verifies page rendering, strict CSP/frame/nosniff headers, health, and unauthenticated API rejection. `binfmt` installs only ARM64 emulation from pinned `tonistiigi/binfmt:qemu-v10.2.3-68`, verifies kernel registration, and runs an ARM Alpine smoke command. `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.

## MCP tool set

```sh
./deploy.sh mcp
```

Register the stdio server once: `command: "~/Projects/AkurAI-Build/deploy.sh"`, `args: ["mcp"]`. JSON-RPC `2025-06-18` over stdio; call `tools/list` for the live schema. Tools: `akurai_doctor`, `akurai_repo_list`, `akurai_repo_add`, `akurai_repo_host`, `akurai_repo_sync`, `akurai_repo_rename`, `akurai_repo_remove`, `akurai_repo_visibility`, `akurai_repo_branches`, `akurai_repo_tree`, `akurai_init`, `akurai_run_queue`, `akurai_runs`, `akurai_run_show`, `akurai_run_wait`, `akurai_run_logs`, `akurai_run_retry`, `akurai_run_promote`, `akurai_artifact_get`, `akurai_workers`.

Each tool returns its JSON payload as the sole `content` text entry, or `isError: true` with a message. Require persisted `succeeded` status before reporting success; `waiting` requires an explicit `akurai_run_promote`, and `queued`/`running` are incomplete. `akurai_repo_list` supports text/visibility filters; `akurai_runs` supports `repo`/`status`/`trigger` as a string, comma-separated values, or an array, plus exact `git_ref`, free-text `search`, bounded `limit`/`offset`. `AKURAI_WORKERS` configures 1–16 Titan workers (the service default is 2). Never read or expose protected token/key/secret values.

`akurai_repo_host` is the maintained migration path from an external Git remote to AkurAI Build's authenticated Smart HTTP host. It creates a bare mirror below the protected data root and updates the CI registration only after the mirror is complete. `akurai_repo_sync` is the maintained source-publication path from a trusted Titan checkout. Public Git clients use `https://akurai-build.olibuijr.com/git/NAME.git` with the protected API bearer token supplied through a credential helper; never put the token in a URL or argument.

`akurai_repo_remove` and `akurai_run_promote` are consequential — confirm intent before calling them; `akurai_repo_remove` cascades runs, jobs, logs, and artifacts.

## 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.