AkurAI Build
Sign in with AkurAI ID
Menu

AkurAI-Build

public

Latest change 806accca7722067e06bbbc6f7e85a875194e7817 - Redesign public homepage and add social discovery by Ólafur Búi Ólafsson

 # AkurAI Build operating contract
 
 ## Deployment workflow
 
 1. Read `skills/akurai-build/SKILL.md`.
 2. Run `akurai-ec2 release --mode publish --yes` from the repo root to build, check, and deploy through the AkurAI-Build CI/CD pipeline.
 3. For repository, pipeline, run, artifact, and promotion operations, use the `akurai-build` MCP tool set (registered in `~/.omp/agent/mcp.json`).
 4. Use the existing maintained command or MCP tool.
 5. If no command or tool exists, run only the smallest bounded **read-only probe** needed to understand the gap.
 6. Once the probe succeeds, implement that operation, 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`; use `akurai-ec2 release --mode publish --yes` to build, check, and deploy through the AkurAI-Build CI/CD pipeline. This maintains the repository-local GitHub author identity.

 ## Deployment
 
 The primary deployment command is:
 
 ```sh
 akurai-ec2 release --mode publish --yes
 ```
 
 This triggers the AkurAI-Build CI/CD pipeline, which automatically handles:
 
 - Source tree synchronization
 - Code formatting and Clippy checks (30s/180s bounded)
 - Tests with process-group termination (90s bounded, Cargo incremental compilation disabled — version-only rebuilds reproduced corrupt `rust-lld` objects in the Syncthing-backed tree)
 - ARM64 binfmt installation from pinned `tonistiigi/binfmt:qemu-v10.2.3-68`
 - Docker executor smoke test with artifact verification
 - Build with retained previous binary for rollback
 - Local service deploy and readiness check (15-second bounded wait)
 - Systemd service install/migration with the Docker supplementary group
 - Pi skill installation
 - EC2 DNS/HTTP/S reachability verification
 - VPN mesh recovery on Titan and EC2 after host reboot
 - Nginx virtual host setup, certificate presence and 30-day expiry check (issuance or renewal)
 - Local and public health endpoint verification
 - HTTP smoke test (CSP, X-Frame-Options, X-Content-Type-Options headers, unauthenticated API rejection)
 - MCP server deployment
 
 Each stage has bounded timeouts with process-group termination so a deadlock is killed instead of hanging. On failure the pipeline fails closed; rollback uses the retained previous binary.
 
 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; `akurai-ec2 release` compares against Git `HEAD` so non-version `Cargo.toml` edits cannot bypass a bump.
 ## MCP tool set
 
 The `akurai-build` MCP tool set is registered in `~/.omp/agent/mcp.json` as a stdio server
 running the `akurai` binary directly. The server binary is at
 `~/.local/lib/akurai-build/akurai`:
 
 ```json
 "akurai-build": { "type": "stdio", "command": "/home/olafurbui/.local/lib/akurai-build/akurai", "args": ["mcp"], "timeout": 30000 }
 ```
 
 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.