docs: Document the model visualization contract (service-module + platform layers)

[oemebamo]

closes https://github.com/TimefoldAI/timefold-solver-enterprise/issues/815

[cedricdhooge96]

It's the first time I'm seeing this. Do you happen to know which model we use this for? Most model visualisations currently depend on a single page with multiple tabs.

[cedricdhooge96]

Answering my own question after digging in:

TL;DR: no model uses this, and nothing reads it either. Org-wide, timefold.model.visualization.pages appears only in the solver's own config class and test. On the platform side the field stops at the descriptor: ModelDescriptorDTO/RegisteredCatalogEntry never carry visualizationPages, and the frontend renders one hardcoded iframe gated only on uiSupport != "NONE". It shipped in #2510 to the shape the platform side requested (timefold-solver-enterprise#656), ahead of any consumer. The issue behind this PR (timefold-solver-enterprise#815) explicitly asked for that caveat to ship with this section ("say plainly it has no visible effect on the platform today"), but the section instead states the platform "knows what to offer users". Please add the caveat back.

How the pieces fit (the reason "single page with multiple tabs" is what we all see today): platform-drawn tabs need two things. First, knowing which pages exist, ideally before the iframe loads. That is this metadata: the menu card. Second, actually switching pages inside the iframe without reloading it, and knowing which page is active. That is a runtime postMessage channel (a views announce plus navigate), which already ships in the rebuilt FSR visualization but is not documented here: https://github.com/TimefoldAI/timefold-visualisations/blob/main/docs/EMBEDDING.md. Today the menu card is printed but nobody reads it, and the waiter works but is not on this page. Every existing model therefore still draws its own tabs inside the frame.

One more concrete fix for this page: the example icon TbChartGantt does not exist in react-icons 5.7.0, the version the platform frontend pins, so the doc's own example would render no icon once consumption lands (measured against the package; TbMap is fine). Worth picking an icon that resolves, and the "any icon name from Tabler Icons" sentence oversells slightly.

We are wiring the two halves together rather than keeping two systems, and this metadata wins the argument: the embed no longer declares its views at all (TimefoldAI/timefold-visualisations#87 removed the upward views message), so this build-time declaration is the single source of the tab set, and the runtime channel carries only what a running embed can know — readiness, the active view, and navigation. Consumption is tracked in TimefoldAI/timefold-platform#5274 (models API) and TimefoldAI/frontend#3991 (run-page menu), and the model-side declarations in TimefoldAI/timefold-field-service-routing#1385 / TimefoldAI/timefold-employee-scheduling#1387. When a model and its visualization live in the same repository, the properties file and the page keys it must match sit side by side, which is the intended end state.