Add sequence diagram showing how the plugin works

README.md

@@ -4,6 +4,46 @@ A [Buildkite plugin](https://buildkite.com/docs/agent/v3/plugins) that sets up y
 
 The plugin removes the need to manually install bktec, set up authentication, or create your test suite before running tests. The plugin works with every test runner that bktec supports, including RSpec, Jest, pytest, and Go test.
 
+## How it works
+
+```mermaid
+sequenceDiagram
+    participant Pipeline as Pipeline YAML
+    participant Agent as Buildkite Agent
+    participant Plugin as Tests Plugin
+    participant OIDC as Buildkite OIDC
+    participant API as Test Engine API
+    participant GH as GitHub Releases
+    participant bktec
+    participant Runner as Test Runner
+
+    Pipeline->>Agent: step with tests plugin and bktec run command
+
+    Note over Agent,Plugin: environment hook
+    Plugin->>Plugin: map plugin options to BUILDKITE_TEST_ENGINE_* env vars
+
+    Note over Agent,Plugin: pre-command hook
+    Plugin->>OIDC: request suite-scoped OIDC token
+    OIDC-->>Plugin: token
+    Plugin->>API: GET /suites/{slug}
+    alt suite does not exist (404 or 401)
+        Plugin->>OIDC: request org-scoped OIDC token
+        OIDC-->>Plugin: org token
+        Plugin->>API: POST /suites/create_from_pipeline
+        API-->>Plugin: suite created
+    end
+    Plugin->>GH: download bktec binary (if install-client: true)
+    GH-->>Plugin: verified binary → added to PATH
+
+    Note over Agent,bktec: command step
+    Agent->>bktec: bktec run
+    bktec->>API: fetch test plan for this node
+    API-->>bktec: assigned test files
+    bktec->>Runner: run assigned tests
+    Runner-->>bktec: results
+    bktec->>API: upload results
+```
+
 ## Example
 
 ```yaml