Version Compatibility

How the platform, the agent and these docs are versioned, what the compatibility rule between the platform and the agent is, how a mismatch presents, and what upgrading involves.

How versions are reported

Thing	Where the version is reported	Current value
The platform	The `version` field of `GET /api/system/status`	`1.0.0`
The socket protocol	The `v` field of every message envelope, and the `protocolVersion` field of the `auth` handshake	`1`
The agent	The capability list it registers with and presents in the socket handshake	The capabilities the agent declares
These docs	The docs app's own version registry (`data/docs-versions.ts`)	`v1` (labelled `v1.0`)

curl http://localhost:3000/api/system/status

{
  "status": "ready",
  "needsSetup": false,
  "databaseConfigured": true,
  "adminCreated": true,
  "version": "1.0.0"
}

The socket protocol has its own version, negotiated during the handshake. The agent sends protocolVersion in its auth request, the studio answers with the version it speaks, and the two must match — otherwise the studio answers PROTOCOL_VERSION_UNSUPPORTED and closes the socket.

Alongside that version number, the agent carries a capability list. The two are exchanged twice: once at registration, in the capabilities field of POST /api/agent/register, and once in the socket handshake, in the capabilities field of the auth response. Beyond the protocol version, compatibility is therefore a statement about commands and capabilities, not about two version strings being compared.

The docs are versioned on their own axis. Each docs line is a frozen set of pages with its own slug list; the current line is v1 and is served without a prefix. When a newer line ships, v1 becomes archived and moves under the /v1 prefix. The docs version is independent of the platform version: a docs line describes one state of the product, not a release channel.

The compatibility rule

An agent is compatible with a platform when it meets both of these conditions:

It completes the socket handshake — its protocolVersion matches the studio's, its agentId exists and its agentSecret matches agents.agent_secret.
It answers every command in the platform's current command contract with the current arguments.

The first condition is checked at connect time. The second is checked per command, and a command that does not meet it fails on its own without disturbing the others.

The command contract the rule refers to is shell, get_system_info, get_serial_ports, open_serial, close_serial, serial_write, run_test_suite and upload_artifact. See Command Reference.

How a mismatch presents

Situation	What you see
The agent speaks a different protocol version	The handshake fails. The studio answers `PROTOCOL_VERSION_UNSUPPORTED` and closes the socket.
The platform sends a command the agent does not know	That command comes back as `status: "error"` with `error.code: "UNKNOWN_COMMAND"` and the message `Unknown command: <name>`. Other commands keep working.
The platform sends a command whose arguments have been extended	The agent answers with the fields it understands and drops the rest, so the command runs with the older semantics.
The platform is older than the agent	Nothing breaks. The platform never asks for anything the agent does not have.

Apart from the handshake, a mismatch never shows up as a connection failure or as an agent that cannot be reached. It shows up on the one command that differs, and the error code names it.

Resolving a mismatch

Situation	Resolution
The agent speaks a different protocol version	Upgrade the agent to the current build and reconnect. The handshake carries the version the agent speaks, and the studio refuses a version it does not speak.
A command the agent does not know	Upgrade the agent to the current build and register it again. Registration issues a fresh `apiKey` and `agentSecret`, and the agent then answers the current command contract.
Arguments that have been extended	Upgrade the agent as above. The platform and the agent are then on the same contract.
A platform older than the agents	Raise the platform to a build that matches the command set the agents implement, or keep the older platform and the agents that go with it.

Upgrading

Step	What happens
Replace the platform build	The running server is restarted.
Restart	The server reads `.db-config.json`, connects to the database and serves the web UI, the REST API and the realtime socket from one process.
Apply the schema	The schema is applied at setup: `POST /api/system/setup` with `step: "initialize"` applies the DDL for the configured engine.
Change the database configuration	Re-run setup with `step: "database"` and then `step: "initialize"`.
Change the database engine	Apply the schema on the new engine and move the data across.

The schema is a set of static DDL files — lib/db/init.sqlite.sql, init.postgresql.sql and init.mysql.sql, 21 tables each. The initialize step applies the file for the engine you chose: on SQLite the whole file is executed with db.exec; on PostgreSQL and MySQL it is split on ;.

Re-running the initialize step applies the full DDL for the configured engine. Treat a schema change as a re-provisioning step rather than a patch.