overlord/plugin-sample-go/README.md

# Sample Go Plugin (sample)

This sample lives at the repo root and builds a native Go plugin.

## Files to include in the plugin zip

At the root of the zip:
- sample-linux-amd64.so / sample-darwin-arm64.dylib / sample-windows-amd64.dll
- sample.html
- sample.css
- sample.js

## Build

Use the provided build scripts:

```bash
# Linux/macOS
./build-plugin.sh

# Multiple targets
BUILD_TARGETS="linux-amd64 linux-arm64 darwin-arm64" ./build-plugin.sh

# Windows
build-plugin.bat
```

## Create the zip

The build script automatically creates `sample.zip` containing the built
binaries and web assets.

Then place `sample.zip` in `Overlord-Server/plugins`.

## Open the UI

Navigate to:
- /plugins/sample?clientId=<CLIENT_ID>

Click "Send event" and the plugin will echo back to the server logs.

## OS detection (Windows-only logic)

The plugin receives host metadata in the `init` payload. The sample plugin shows
how to detect the host OS and branch logic (see
`plugin-sample-go/native/main.go`). For example:

- If `host.os == "windows"`, you can safely run Windows-only flows (e.g., WinAPI-backed behavior).
- Otherwise, skip or provide a fallback path.