docs: document the printer-agent subsystem

docs/printer-agent/README.md

@@ -0,0 +1,72 @@
+# Printer agents
+
+Printer agents let OrcaSlicer communicate with printers through a
+standardized protocol. They translate between a printer's
+native API and the application interfaces that the app already
+uses.
+
+This documentation explains the compatibility boundary, runtime ownership,
+connection and status flow, command and feature behavior, built-in and plugin
+agent implementations, and the testing evidence required for compatibility
+claims.
+
+## What printer agents do
+
+A printer agent has two jobs:
+
+1. Accept the app's existing commands and translate the ones its
+   printer supports.
+2. Convert native printer status into correctly-shaped state that
+   `MachineObject` understands.
+
+Currently, agents work at a compatibility boundary, i.e., making other vendors compatible with Bambu-shaped code, not a vendor-neutral one.
+Some Bambu concepts remain part of the payload and command vocabulary.
+End goal is to make the whole command and payload interfaces vendor-neutral.
+
+## Vocabulary
+
+Every chapter reuses these terms. The "Is not" column is the part that
+causes confusion when it is left implicit.
+
+| Term | Is | Selected by | Is not |
+| --- | --- | --- | --- |
+| Agent ID | Which printer agent implementation to use | `printer_agent` on the printer preset; empty is the legacy `bbl`-or-`orca` sentinel | Which printer |
+| Printer agent | The live `IPrinterAgent` instance for that ID, created and cached once per ID by `NetworkAgentFactory` | Factory lookup on the agent ID | A connection, and not one object per printer |
+| Device ID | One printer inside that implementation | Bind with Access Code for the Moonraker family, where the entered address becomes the ID; Bambu uses its own discovery identity | Which protocol |
+| `MachineObject` | The Device tab's view of one selected printer | `DeviceManager::selected_machine`, which stores only an ID | Proof that a printer is reachable |
+| Freshness | `is_connected()`, a test over the last-update time | Any reset of the update time, including one no status has followed | Proof that status arrived |
+| Status-confirmed readiness | A push-status message has actually been parsed | The first real status message | The same thing as a successful `connect_printer()` |
+
+Earlier drafts used "transport" for the printer agent instance. That term
+is retired: the code selects an implementation, not a wire protocol.
+
+## How to use this guide
+
+- [Architecture](architecture.md) describes objects, ownership, lifetimes,
+  error handling, the feature gate, and compatibility contracts for printer
+  agents.
+- [Connection and status](connection-and-status.md) describes how presets,
+  machines, access codes, status messages, and commands fit together at
+  runtime. Unlike Architecture, it follows the sequence of selecting an
+  agent, connecting, receiving status, and sending commands.
+- [Printing](printing.md), [filament synchronization](filament.md), and
+  [camera support](camera.md) are separate chapters because they contain
+  per-feature detail rather than because they are universally special:
+  Printing has its send, preflight, recovery, and start contracts; Filament
+  covers acquisition, mapping selection, and print-time delivery; Camera
+  covers the distinct Bambu, Moonraker, and Snapmaker ownership models.
+- [Built-in agents](agents.md) describes the Moonraker family and the Qidi,
+  Snapmaker variants.
+- [Python plugin agents](plugin-agents.md) describes the plugin bridge and
+  lifecycle.
+- [Testing and troubleshooting](testing.md) explains automated checks, manual
+  hardware work, known defects, and the evidence required for compatibility
+  claims.
+- The [capability matrix](reference/capability-matrix.md) is the compact
+  feature reference. The [manual checklist](reference/manual-checklist.html)
+  is for a live-printer verification pass.
+
+Treat source code as authoritative when it differs from this guide. In
+particular, preserve the compatibility rules called out in each chapter:
+they protect stored presets, existing profiles, and the Device tab's
+assumptions.