docs: document the printer-agent subsystem

docs/printer-agent/filament.md

@@ -0,0 +1,110 @@
+# Filament synchronization and mapping
+
+*Owns the three filament stages end to end: acquiring printer state,
+selecting a mapping, and delivering it at print time. Defers the upload
+and start mechanics to [Printing](printing.md), and per-vendor discovery
+detail to [Built-in agents](agents.md).*
+
+Filament support has three separate stages. A successful first stage does
+not mean that a selected mapping will be delivered to the printer.
+
+Stage 3 is where the two paths diverge, and only one of them reaches the
+printer:
+
+```mermaid
+flowchart TD
+    SRC["Filament source<br/>Moonraker lane_data, or the classic MMU object"]
+    ACQ["1 - Acquire state<br/>Moonraker pull, not subscription"]
+    ST["DevFilaSystem<br/>Bambu-shaped view, synthetic 4-slot groups"]
+    SEL["2 - Select mapping<br/>Send dialog matches project filament to slots"]
+    PAR["PrintParams<br/>ams_mapping fields"]
+    QIDI["Qidi agent writes enable_box<br/>and value_t per tool, then starts the print"]
+    BASE["Base Moonraker, Happy Hare, AFC<br/>upload and start ignore the mapping fields"]
+    OK["Mapping reaches the printer"]
+    DEAD["Mapping never reaches the printer<br/>the job runs on the printer's own loaded-lane behavior"]
+
+    SRC --> ACQ --> ST --> SEL --> PAR
+    PAR -- Qidi --> QIDI --> OK
+    PAR -- every other target --> BASE --> DEAD
+```
+
+## 1. Acquire printer state
+
+`FilamentSyncMode` declares how the UI obtains filament state:
+
+| Mode | Meaning |
+| --- | --- |
+| `subscription` | A status stream keeps the state current. |
+| `pull` | The UI must request state before it can use it. |
+| `none` | The agent has no usable filament state. |
+
+Moonraker uses `pull`. Its ordinary status stream does not supply the
+filament data used by this UI. In particular, `lane_data` is a Moonraker
+database namespace, not a printer object that the existing subscription
+can follow. Changing Moonraker to `subscription` would suppress the pull
+that actually populates the UI.
+
+The agent first reads `lane_data`, which can describe AFC and newer Happy
+Hare installations. If that is unavailable, it reads the classic Happy
+Hare `mmu` object. Those response shapes are source-supported but not yet
+verified against current Happy Hare and AFC installations.
+
+The current parser expects lane values as strings and silently skips
+numeric values. Whether current AFC or Happy Hare installations emit
+numeric lane values is unverified.
+
+The received lanes are converted into a Bambu-shaped model so existing
+AMS UI can render them. The model groups numeric lane indexes into
+synthetic groups of four slots and passes the result through
+`ParseV1_0`. This is a UI compatibility adapter, not evidence that the
+printer has a Bambu AMS.
+
+Pull state can be stale. The Send dialog can build a mapping from the
+current `DevFilaSystem` without refreshing it first, and a failed pull can
+leave older state visible. Do not represent a displayed lane list as a
+fresh printer read unless the call site just performed the pull.
+
+## 2. Select a mapping
+
+The Send dialog matches each project filament to a compatible reported
+slot. It rejects a mismatched material type and then prefers compatible
+slots according to the existing mapping rules. The result is carried in
+the legacy linear mapping, the explicit AMS-and-slot mapping, and mapping
+metadata for the job.
+
+Treat lane numbers as printer contracts. A numeric lane index is used as a
+slot index in the synthetic four-slot view, so an incorrect numbering
+assumption can select the wrong physical lane.
+
+The material identity code also retains a defect: ABS and ASA can be
+shown as PLA when profile identifiers collide. This is not fixed here,
+and multi-color mapping has not received hardware verification.
+
+## 3. Deliver the mapping at print time
+
+`PrintJob` copies the selected mappings into `PrintParams`, but base
+Moonraker does not read those fields when it uploads and starts a print.
+For plain Moonraker, Happy Hare, and AFC targets using that base path, a
+correct-looking mapping in the UI is therefore not delivered to the
+printer. The print runs using the printer's own loaded-lane behavior.
+
+Qidi is the implemented exception. Its agent writes its own box mapping
+before starting the print. That is a Qidi-specific delivery contract, not
+a generic Moonraker solution.
+
+There are deliberately no guessed Happy Hare or AFC write macros. Their
+macro and variable names are defined by printer-side configuration, so a
+guessed command could silently do nothing or control the wrong setup. Add
+a delivery path only after verifying the exact contract against upstream
+documentation or a real printer.
+
+## Maintenance checklist
+
+- Keep Moonraker in `pull` mode while `lane_data` remains pull-only.
+- Refresh or clearly surface stale state before relying on Send-dialog
+  mappings.
+- Do not claim base Moonraker honors mappings until it consumes them at
+  print time.
+- Preserve Qidi as a distinct delivery implementation.
+- Verify lane numbering, material identity, and multi-color behavior on
+  hardware before expanding the mapping contract.