Develop with Platonic

Developer docs

Orientation, not architecture law. These pages explain the current tree and route you to its owners. The workspace naming authority, the repository agent guide, the accepted decision map, typed source, and executable tests remain authoritative.

The boundary

Platonic is the agent server and product. Its platonic command is a thin entry point over the technical platonic-server crate. Plato Agent is the client distribution built on that server; it provides the plato and plato-tui commands. Those exact forms come from the branding authority, while dependency ownership is enforced by the repository boundary rules.

Clients submit typed protocol requests. The server owns workspace and thread authority, run admission, policy, approvals, provider and tool effects, and persistence. The pure platonic-core kernel owns typed state-machine rules, but never performs an effect. The architecture invariant test prevents the client distribution from acquiring server ownership through a dependency.

The working vocabulary

Term	Meaning	Authority
Workspace	A named, registered directory with a stable server-minted identity and one workspace ledger. Moving the directory does not mint a new identity.	Decision map, P006/P021 and WorkspaceRecord
Agent profile	Immutable configured data bound to one workspace: model defaults, approval policy, and default toolset. It can serve many threads; it is not a process or plugin.	Repository agent guide and immutability schema
Thread	Durable authority for an ongoing conversation and its runs. Its complete authority record is written before the first turn.	Decision map, P020 and ThreadAuthorityRecord
Run	One ordered execution within a thread or session. Its state is derived from contiguous recorded events.	RunState on docs.rs
Approval	A server-persisted question about one tool call, followed by a single decision. A client can present or decide it; the client does not own the approval state.	tool_call_approvals
Command	On the wire, a callable protocol method. Inside the kernel, a RunCommand is a pure request for the host to call a model, await approval, or execute a tool. Neither is a new authority owner.	ProtocolMethod and RunCommand on docs.rs

Follow one request

Start with the request lifecycle. It follows a real one-shot request through local transport, server admission, the pure kernel boundary, provider or tool effects, the ledger, and ordered observation.

Then use the page that matches the boundary you are changing:

• Protocol and observation for the handshake, callable methods, capabilities, controllers, observers, gateways, and the remote-transport gate.
• Durability and replay for JSONL commits, SQLite state, crash repair, interrupted runs, approvals, and offline replay.
• Crates and change routing for dependency rules and the small set of modules where these boundaries meet.

Operational setup and troubleshooting belong to the User operations guide, not to this architecture journey. Deployment remains separately gated.