Save this content to: AGENTS.md

# Agent guidance — superconductor/mcp

1. **Read [`.okf/index.md`](.okf/index.md) first** before changing a message, a procedure, the client or the server. Open only the concepts the change touches.
2. **The spec version is 2024-11-05, and the protocol line is accumulated, never dropped.** A new version is a new stop (`2025-03-26`, `2025-06-18`, `2025-11-25`, `2026-07-28`); the ones before it keep working. Check the spec page for the version before changing a wire shape. See [`.okf/protocol/messages.md`](.okf/protocol/messages.md).
3. **Server and client are different entities.** A server is a sketch run by a transport; an `MCPServer` only says what it serves. A client is an in-process component inside the application's own loop, one `MCPClient` per connection, and never owns a loop. They share only messages, definitions and the router. See [`.okf/architecture/roles.md`](.okf/architecture/roles.md).
4. **Every wire shape is a readonly message class.** Requests are built from a decoded line by `generate()` and sent with `toJson()`; responses are built from a reply by `fromReceived()` and sent with `toJson()`. Empty maps go out as `{}`. The decoder is the only place a line is trusted. See [`.okf/protocol/messages.md`](.okf/protocol/messages.md).
5. **Errors are JSON-RPC errors with the spec's code and the request's id.** Reuse `InvalidRequest`, `InvalidParams`, `MethodNotFound`, `InternalError` and the MCP-coded ones; never add an error class for a message that an existing one plus text can carry. A notification is never answered. See [`.okf/protocol/errors.md`](.okf/protocol/errors.md).
6. **Ids are per requestor.** Each side keeps two `RequestIds`: one for the ids it sent, one for the ids it received. A repeated incoming id is refused; the two sides may use the same numbers. See [`.okf/protocol/ids.md`](.okf/protocol/ids.md).
7. **Capabilities gate what goes out.** `MCPServer::notify()` drops a notification the server does not advertise; `MCPServerBag::wants()` drops what this session did not ask for; the client lists only what the server advertised. See [`.okf/server/capabilities.md`](.okf/server/capabilities.md).
8. **Procedures that run developer code are `ASYNC`.** Tool calls, resource reads, prompt gets and completion run in a loop fiber so pings, cancellation and progress work while they run. Lifecycle and list procedures stay synchronous. See [`.okf/mechanism/procedures.md`](.okf/mechanism/procedures.md).
9. **Config keys are documented and mirrored.** A key added to `config/mcp.php` is described in the README and copied into any app that published the file. No key is read that the file does not declare.
10. **Transports are separate packages** (`semiconductor/*`). This package knows no transport by name; a transport registers its sketch through `sketches.load` and its client creator on `mcp.clients`. See [`.okf/architecture/transports.md`](.okf/architecture/transports.md).
11. **Tests are Pest v4 and need no server.** The client is tested on a `FakeConnection`, procedures on a bench `MCPServer`, the decoder on lines. A behaviour change comes with a test; `vendor/bin/pest` stays green.
12. **Durable facts go in `.okf`.** Update the matching concept, bump its `generated.at`, append `.okf/log.md`. The bundle documents the package, never a session.
13. **Versions** move only past a published tag, in `composer.json` `version` and `MCPClient::VERSION` together.