From 2e054572c40a868df16e8f1120763ee771dc7817 Mon Sep 17 00:00:00 2001
From: Peter Zandbergen <peter.zandbergen@myhops.com>
Date: Thu, 18 Jun 2026 08:06:39 +0200
Subject: [PATCH] OpenCode init

---
 AGENTS.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..66d04c2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,70 @@
+# AGENTS.md
+
+## Project Overview
+
+Go-based REST API wrapping [signal-cli](https://github.com/AsamK/signal-cli) for Signal Messenger. Runs exclusively inside Docker; there is no standalone `go run` dev server for the full API. The Go app orchestrates `signal-cli` (a Java binary) or `signal-cli-native` (GraalVM precompiled), communicating via CLI args in normal/native mode or JSON-RPC in daemon mode.
+
+## Architecture
+
+- `src/` — Go source (the REST API server)
+  - `main.go` — entrypoint; sets up Gin router, routes, cron, plugin loader
+  - `api/api.go` — all HTTP handlers
+  - `client/` — signal-cli interaction layer; three modes: `Normal`, `Native`, `JsonRpc` (see `client.go` constants)
+  - `datastructs/datastructs.go` — shared structs
+  - `utils/` — helpers, plugin config, text-style parser
+  - `docs/` — Swagger docs (auto-generated by `swag init`)
+  - `scripts/jsonrpc2-helper.go` — daemon manager for json-rpc mode
+- `plugin_loader.go` — Go plugin system using Lua scripts (v1/v2 plugin API)
+- `plugins/` — example Lua plugins and persistence plugin
+- `Dockerfile` — multi-stage build: Go compile → release image with signal-cli + Java runtime
+- `entrypoint.sh` — container entrypoint; handles UID/GID, chown, supervisor for json-rpc mode
+
+## Build & Run
+
+- **Build & test (local):** All commands run from `src/`
+  ```bash
+  cd src
+  go test ./client -v
+  go test ./utils -v
+  go build -o signal-cli-rest-api main.go
+  ```
+- **Build & run (Docker, the primary workflow):**
+  ```bash
+  # Edit docker-compose.yml: change image to build: "."
+  docker compose build
+  docker compose up
+  ```
+- **No linter or typecheck config exists** — standard Go tooling only (e.g., `go vet`).
+
+## Swagger / API Docs
+
+Docs are auto-generated from swag annotations in `main.go` and `api/api.go`.
+
+```bash
+cd src
+go run github.com/swaggo/swag/cmd/swag@v1.16.6 init --requiredByDefault --outputTypes "go,json"
+```
+
+The receive V1 schemas require an extra step (`add_v1_receive_schemas.go`); see `src/docs/README.md`. CI checks that generated docs are up-to-date (workflow: `check-docs.yml`).
+
+## Key Environment Variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `MODE` | `normal` | `normal`, `native`, `json-rpc`, `json-rpc-native` |
+| `PORT` | `8080` | Listen port |
+| `ENABLE_PLUGINS` | `false` | Enable Lua plugin system |
+| `AUTO_RECEIVE_SCHEDULE` | — | Cron expression; **incompatible with json-rpc mode** |
+| `SIGNAL_CLI_CMD_TIMEOUT` | — | CLI timeout; **incompatible with json-rpc mode** |
+| `RECEIVE_WEBHOOK_URL` | — | Webhook on receive; **json-rpc mode only** |
+| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |
+| `DEFAULT_SIGNAL_TEXT_MODE` | `normal` | `normal` or `styled` |
+
+## Gotchas
+
+- The Dockerfile pins `SIGNAL_CLI_VERSION` and `LIBSIGNAL_CLIENT_VERSION` as build args. After bumping these, verify the `libsignal-client-*.jar` filename still matches.
+- Multi-arch build targets: `linux/amd64`, `linux/arm64`, `linux/arm/v7`. The `native` (GraalVM) binary is unavailable on armv7 — code falls back to `normal` mode.
+- `AUTO_RECEIVE_SCHEDULE` and `SIGNAL_CLI_CMD_TIMEOUT` cause a fatal error in json-rpc mode.
+- `RECEIVE_WEBHOOK_URL` is only valid in json-rpc mode; fatal in other modes.
+- CI uses Podman for multi-arch builds, not Docker Buildx.
+- Release versions are published via `publish.sh` triggering GitHub Actions (dev vs stable tags).
\ No newline at end of file