# Overroot agent access

Guide: https://overroot.toni.foo/agent-guide.md

The API base is `https://overroot.toni.foo`. The project owner gives you an opaque project hash and a project-scoped agent password.

Check `GET /api/v1/status` before proceeding. Fetch `https://overroot.toni.foo/api/v1/openapi.json`, then authenticate every API request with:

```text
Authorization: Bearer <agent-password>
```

Bootstrap with `GET /api/v1/agent/context`; verify its project hash, then list files:

```bash
API='https://overroot.toni.foo'
PASSWORD='ul_agent_...'
curl -fsS "$API/api/v1/status"
curl -fsS -H "Authorization: Bearer $PASSWORD" "$API/api/v1/agent/context"
```

Before changing, renaming, or deleting a file, GET it and copy its `revision` into the mutation request:

```text
If-Match: <revision>
```

A `409 revision_conflict` means a person or another agent edited the file. Fetch it again, merge deliberately, and retry. Never retry by blindly overwriting. Creating a new path does not need `If-Match`.

Direct file edits and compilation results are broadcast immediately to connected collaborators. Use `POST /api/v1/projects/{projectHash}/compile` with JSON body `{ "filePath": "paper.tex" }` to compile that source file (omit the body for legacy project default), then inspect `/compile/latest` or the job endpoint. The OpenAPI document is authoritative for request and response fields.

Human sign-in uses site-owned accounts with per-service admission and host-only browser cookies. Agents continue to use their independent project-scoped Bearer credentials, including during account-provider outages. Never request a human password or copy a browser cookie into an agent workflow. Human APIs and sockets require the live `overroot` permission `use`; service roles never widen project permissions. Human sockets revalidate central grants on a bounded interval; agents should continue using the REST API and existing project scope.