AkurAI-Platform / AGENTS.md

Latest change ab5af3b4bf8dbd84fe1c393cd0649b929a224d26 - docs: codify worker privilege boundary (AKURAI-PLATFORM-41) by Ólafur Búi Ólafsson

# AGENTS.md — AkurAI-Platform

Documentation for this repo lives in **akurai-notes MCP**.

- **Canonical note:** `AkurAI-Platform — Docs` (note id 26)
- **Index note:** `AkurAI-Platform — Project Index` (note id 84)
- **Secrets:** akurai-passvault; merchant login is entry 42, production Checkout credentials are not yet available

## How to retrieve

```
search_notes("AkurAI-Platform")
get_note(26)
```

Covers: purpose, scope rules, file index, deployment rule, ISA (problem/vision/criteria/decisions/verification).

## Agent operations

### AkurAI Build MCP tool access

AkurAI Build MCP tools (e.g., `mcp__akurai_build_akurai_repo_sync`, `mcp__akurai_build_akurai_run_queue`, `akurai_run_promote`) are only available in the root/operator OMP session where the MCP server is configured. Task-worker and background-agent sessions inside pi-bun's dispatch loop do **not** have the AkurAI Build MCP tools mounted.

When a task requires Build operations (sync, queue, promote), the implementation agent MUST:
1. Complete all local edits, commit, and record the full commit SHA.
2. Report the required Build operations and commit SHA to the root session.

Internal agents MUST NOT attempt to call `mcp__akurai_build_akurai_*` tools directly; these calls fail with "Tool not found" in the worker context.

### Privilege boundary

Task-worker sessions run without root escalation. NEVER run local `sudo`; it cannot
succeed under the worker's `no_new_privileges` sandbox. Local implementation and
static checks use only repository-owned paths and the commands in `package.json`.
Privileged EC2 changes run only in the approval-gated `.akurai.yml` deploy job via
`akurai-ec2`; implementation agents hand the commit SHA to the release stage.