docs: note the metadata field under Registration

[rickstaa]

register_runner and runners.json both accept an optional metadata string, it reaches the client through /discovery, and nothing in the repo mentioned it. One paragraph under Registration, where someone scanning "what can I pass at registration" actually looks.

Stating the boundary matters as much as the field. Discovery can only filter on app and gpu, and one registration carries exactly one price_info, so anything a caller selects or pays differently for has to live in the app id — metadata can do neither. It is for detail the protocol has no place for, like a context window or the languages a model handles.

The paragraph also says plainly that no example sets it, so the absence reads as a rule rather than an oversight. That is accurate: every variable dimension in this set is already covered by the app id (vllm, api-proxy, realtime-transcription), capacity (tiles), gpu, or price.

Two implementation details worth knowing, both from the code rather than docs: the orchestrator validates it at ≤1024 bytes as valid UTF-8 with no U+FFFD (ai/runner/live_runner.go:904-915) and otherwise never interprets it, and the SDK gives it no first-class field — LiveRunnerInstance exposes it only through raw, so client-side filtering is the only option.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds missing documentation to the root README explaining the optional metadata field accepted during runner registration and how it surfaces back through discovery, including guidance on when it should/shouldn’t be used.

Changes:

• Documented the optional metadata string under Registration.
• Clarified intended usage boundaries (non-selectable/non-priced details vs app id / other first-class fields).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (1)

README.md:59

• This paragraph says the app id is the only key /discovery can filter on, but the PR description states discovery can filter on app and gpu. Also, since metadata is optional, the examples should avoid raw["metadata"] (KeyError when absent) and use .get("metadata") instead.

Both forms also take an optional **`metadata`** string: up to 1 KB of app-controlled UTF-8, echoed back in `/discovery` and never read by the orchestrator. Use it to pass callers app-specific detail the protocol doesn't model, such as a context window or the languages a model handles; clients read it off the discovered runner, as `cursor.candidates[0].raw["metadata"]` after `runner_selector`, or `session.runner.raw["metadata"]` after `reserve_session`. Anything a caller **selects or pays differently for** belongs in the app id instead, which is the only key discovery can filter — none of the examples here need `metadata` for that reason.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (1)

README.md:59

• The docs describe metadata as optional, but the access examples use raw["metadata"], which will raise KeyError when the field is absent. Using .get("metadata") (or an equivalent safe access pattern) better matches the optional contract.

Both forms also take an optional **`metadata`** string: up to 1 KB of app-controlled UTF-8, echoed back in `/discovery` and never read by the orchestrator. Use it to pass callers app-specific detail the protocol doesn't model, such as a context window or the languages a model handles; clients read it off the discovered runner, as `cursor.candidates[0].raw["metadata"]` after `runner_selector`, or `session.runner.raw["metadata"]` after `reserve_session`. Anything a caller **selects or pays differently for** belongs in the app id instead, which is the only key discovery can filter — none of the examples here need `metadata` for that reason.