AkurAI-Build

Latest change 32946d79ecd7d436b3978f5757db6b3a392b3ca8 - AKURAI-BUILD-11 consolidate self-hosted deployment 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`
- 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. The 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. `deploy/service-deploy.sh` verifies both health endpoints and rolls the service back on failure. Explicit worker-image and host-MCP maintenance uses the codified `deploy/compose-release.sh` path outside the worker, builds both images from one revision/tag, installs the host binary atomically, and verifies both endpoints.

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.