docs: Add more pointers for the API being machine readable

AGENTS.md

@@ -54,6 +54,13 @@ If you are looking for OliveTin's AI policy, you can find it in `AI.md`.
 3. Executor runs a chain of steps: request binding → concurrency/rate/ACL checks → arg parsing → exec → post-exec → logging/triggering.
 4. Logs are stored and can be fetched via `ExecutionStatus`/`GetLogs`.
 
+### Machine-readable API
+- The OliveTin API is completely machine readable: it is defined in Protobuf and served with Connect RPC (Connect JSON/binary and gRPC-Web).
+- Source of truth: `proto/olivetin/api/v1/olivetin.proto` (service `olivetin.api.v1.OliveTinApiService`), online at https://github.com/OliveTin/OliveTin/tree/main/proto
+- Prefer reading the proto over guessing endpoints. Each RPC is callable as `POST /api/<MethodName>` with a protobuf-JSON body (lowerCamelCase fields, eg `{"bindingId": "..."}`).
+- After changing the proto, regenerate code with `cd proto && make` (buf) — generated code lives in `service/gen/` and `frontend/resources/scripts/gen/`.
+- User docs for the API: `docs/modules/ROOT/pages/api/intro.adoc`. LLM-oriented docs index: https://docs.olivetin.app/llm.txt
+
 ### Common Tasks
 - Add/modify actions: update `config.yaml` and ensure `executor.RebuildActionMap()` is called when needed.
 - Adjust dashboard rendering: see `service/internal/api/dashboards.go` and `apiActions.go`.

README.md

@@ -50,7 +50,7 @@ The AsciiDoc sources for that site live in this repository under [`docs/`](docs/
 * **Accessible** - passes all the accessibility checks in Firefox, and issues with accessibility are taken seriously.
 * **Container** - available for quickly testing and getting it up and running, great for the selfhosted community.
 * **Integrate with anything** - OliveTin just runs Linux shell commands, so theoretically you could integrate with a bunch of stuff just by using curl, ping, etc. However, writing your own shell scripts is a great way to extend OliveTin.
-* **Lightweight on resources** - uses only a few MB of RAM and barely any CPU. Written in Go, with a web interface written as a modern, responsive, Single Page App that uses the REST/Connect RPC API.
+* **Lightweight on resources** - uses only a few MB of RAM and barely any CPU. Written in Go, with a web interface written as a modern, responsive, Single Page App that uses the REST/Connect RPC API. The API is completely machine readable, defined in [Protobuf](https://github.com/OliveTin/OliveTin/tree/main/proto) (gRPC / Connect RPC), so it is easy to integrate with from scripts, generated clients, and AI agents.
 * **Good amount of unit tests and style checks** - helps potential contributors be consistent, and helps with maintainability.
 
 ## Screenshots

docs/modules/ROOT/pages/api/intro.adoc

@@ -8,11 +8,19 @@ This section of the documentation is intended for developers, and those who want
 * http://olivetinServer:1337/api on your OliveTin server to get the REST API. 
 * link:http://docs.olivetin.app/api/swagger/[Swagger] documents the API.
 
-**Longer version**: The OliveTin API is formally defined using the Protobuf IDL, which generates gRPC stubs, as well as a REST Gateway. 
+**Longer version**: The OliveTin API is formally defined using the Protobuf IDL, in link:https://github.com/OliveTin/OliveTin/tree/main/proto[the `proto/` directory of the OliveTin repository]. Server and client code is generated from that definition, and the API is served using link:https://connectrpc.com[Connect RPC].
 
-The REST API gateway is used by the WebUI, and you can use it too by default - it is exposed at "/api" by default.
+The API is exposed at `/api/` on the single HTTP frontend (port 1337 by default), and is the same API used by the WebUI. You can call it with plain JSON over HTTP (eg: `curl http://olivetinServer:1337/api/WhoAmI --json '{}'`), with binary Protobuf, or with gRPC-Web clients.
 
-The gRPC API only listens on localhost default, but it can be set to listen publicly. See xref:reference/network-ports.adoc[the network ports documentation] for a better description of how the APIs are exposed. Most people do not need to use the gRPC API. 
+[#machine-readable-api]
+== Machine readable API (for scripts, integrations and AI agents)
+
+The OliveTin API is completely machine readable - every method, request and response message, field, and enum is defined in the Protobuf files. This makes it straightforward for code generators, API tooling, and LLMs / AI agents to discover and use the API without guessing.
+
+* **Source of truth**: link:https://github.com/OliveTin/OliveTin/tree/main/proto[`proto/`] on GitHub - the service is `olivetin.api.v1.OliveTinApiService` in link:https://github.com/OliveTin/OliveTin/blob/main/proto/olivetin/api/v1/olivetin.proto[`olivetin/api/v1/olivetin.proto`].
+* **Generate a client**: use link:https://buf.build[buf] or `protoc` with the Connect, gRPC, or gRPC-Web plugins for your language of choice (Go, TypeScript, Python, Java, etc).
+* **Call it directly**: each RPC is available as `POST /api/<MethodName>` with a JSON body matching the request message, using protobuf JSON field names (lowerCamelCase, eg: `bindingId`).
+* **OpenAPI**: the Swagger / OpenAPI links below are also available for tools that prefer OpenAPI.
 
 == Links
 
@@ -20,7 +28,8 @@ The gRPC API only listens on localhost default, but it can be set to listen publ
 * link:http://docs.olivetin.app/api/swagger/OliveTin.openapi.json[OliveTin 2k API: OpenAPI JSON Definition]
 * link:http://docs.olivetin.app/api/swagger/3k/[OliveTin 3k API: Swagger UI]
 * link:http://docs.olivetin.app/api/swagger/3k/OliveTin.openapi.json[OliveTin 3k API: OpenAPI JSON Definition]
-* link:https://github.com/OliveTin/OliveTin/blob/main/proto/olivetin/api/v1/olivetin.proto[The OliveTin Protobuf file]. 
+* link:https://github.com/OliveTin/OliveTin/tree/main/proto[The OliveTin Protobuf definitions (source)]
+* link:https://github.com/OliveTin/OliveTin/blob/main/proto/olivetin/api/v1/olivetin.proto[The OliveTin Protobuf file]
 
 Please do talk to the developers on Discord if you'd like help using the API, or you're thinking about building something interesting using the API!
 

docs/modules/ROOT/pages/index.adoc

@@ -47,3 +47,5 @@ The OliveTin documentation site supports the llm.txt and llm-full.txt files, ava
 
 * link:https://docs.olivetin.app/llm.txt[llm.txt]
 * link:https://docs.olivetin.app/llm-full.txt[llm-full.txt]
+
+The OliveTin API is completely machine readable. It is defined in Protobuf (gRPC / Connect RPC), and the definitions are the source of truth for every method and message - see link:https://github.com/OliveTin/OliveTin/tree/main/proto[`proto/` on GitHub] and xref:api/intro.adoc#machine-readable-api[the API overview].