AkurAI-Build

public

Latest change a7c60e6c4413fa9cff6ed41223148b68f01f669c - Add self-host service promotion for UI wave (AKURAI-BUILD-2..9) by Ólafur Búi Ólafsson

# AkurAI Build operating contract

## Deployment workflow

1. Read `skills/akurai-build/SKILL.md` and the repository's `.akurai.yml`.
2. Run the focused local source checks.
3. Commit only the intended paths in the trusted Titan checkout and record the full commit SHA.
4. Publish the committed revision with `mcp__akurai_build_akurai_repo_sync`.
5. Confirm the hosted branch head with `mcp__akurai_build_akurai_repo_branches`.
6. Queue the exact SHA with `mcp__akurai_build_akurai_run_queue`.
7. Inspect or wait through `akurai_run_show`/`akurai_run_wait`; promote a persisted `waiting` production environment only with `akurai_run_promote`.
8. Require persisted `succeeded` state, then verify public health and the changed behavior.

## Prohibited direct mutations

Do not directly run SSH mutations, package managers, `systemctl`, Docker mutations, Nginx/certbot changes, database tools, artifact copies, raw Git push, `akurai-ec2 release`, or `deploy.sh publish|release|deploy`. 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`. A narrowly staged local commit is the only permitted Git mutation; hosted publication, CI, artifacts, approval, and deployment use the `akurai-build` MCP tools.

## Deployment

A deployable repository owns the full release contract in `.akurai.yml`:

1. `verify` runs formatting, linting, tests, and project-specific gates.
2. `package` produces an immutable artifact and recorded SHA-256.
3. An approval-gated production job consumes that artifact without rebuilding it.
4. Post-deploy acceptance verifies health and changed behavior; failure rolls back.

Agent-side flow is always:

```text
local commit → repo_sync → verify hosted head → run_queue(exact SHA) → wait/promote → persisted success → acceptance
```

Commands such as `akurai-ec2` service or edge operations may appear inside a committed pipeline job. They are not agent-side queue, publication, approval, or deployment substitutes.

AkurAI Build is self-hosted as separate service and worker containers. Its protected `deploy-production` job consumes the package job's prebuilt binary and atomically replaces only `akurai-build-service`; the worker remains alive to persist the deployment result. Worker-image and host-side MCP binary changes remain maintenance work and must not be smuggled into a service deploy.

Every published version must match the newest `CHANGELOG.md` entry. Version components are bounded to `1..10`: patch `10` rolls to the next minor, minor `10` rolls to the next major, and `10.10.10` is terminal.

## MCP tool set

Use the configured `mcp__akurai_build_akurai_*` tools. Never invoke the installed binary's stdio protocol, direct Build HTTP, or `deploy.sh cli|mcp`. The mounted tool schema is authoritative. Current 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_release`, `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 1). 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.