feat(core): OperationBuilder in the SDK, on optional peers

Antonio: the suggestion builder is platform business and belongs in the
services API, not in the fragments toolkit. Same class the apps carried as a
stopgap copy: geometry-less .frag, envelope revitflow/op@2, laid out exactly
as the C# reader expects, bytes ready for suggest({ payload }). flatbuffers
and @thatopen/fragments become OPTIONAL peers, dynamically imported only when
build() runs and kept external in the bundle, so nothing changes for apps
that never author operations.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: agviegas

.changeset/operation-builder.md

@@ -0,0 +1,5 @@
+---
+'@thatopen/services': minor
+---
+
+`OperationBuilder` joins the SDK: authors an interoperability operation — geometry-less .frag, envelope `revitflow/op@2`, laid out exactly as the C# reader expects — from plain `add`/`set`/`remove` calls, returning the deflated bytes for `suggest({ payload })` or a recipe's result. Attributes are written untranslated, in the target application's own terms and units. Its two dependencies, `flatbuffers` and `@thatopen/fragments`, are OPTIONAL peers resolved only when `build()` runs, so apps that never author operations install and pay nothing new.

docs/ai-quickstart.md

@@ -415,6 +415,14 @@ await client.recipes.run('my-recipe', {            // only QUEUES a suggestion:
 `docs()` also answers `folderId` — the id the CDE knows that document by, the
 bridge between this section and 5c.
 
+To AUTHOR a suggestion's payload, `OperationBuilder` (same import) writes the
+operation .frag: `new OperationBuilder(target).add(attrs, placement)` /
+`.set(id, attrs)` / `.remove(id)`, then `await builder.build(opId)` gives the
+bytes for `suggest({ payload })`. Attributes go in the TARGET app's own terms
+and units, untranslated. It needs the optional peers `flatbuffers` and
+`@thatopen/fragments` installed (loaded only when `build()` runs — nothing
+else in the package needs them).
+
 This surface is the only supported way in: the storage underneath is private
 and will move. Never list or write the `bimterop` files directly. The full
 walkthrough (manifest fields, StaleHistoryError on concurrent syncs, payloads)

package.json

@@ -82,16 +82,24 @@
   },
   "peerDependencies": {
     "@thatopen/components": "~3.4.0",
+    "@thatopen/fragments": "~3.4.0",
     "@thatopen/ui": "~3.4.0",
+    "flatbuffers": ">=23.0.0",
     "three": ">=0.182.0"
   },
   "peerDependenciesMeta": {
     "@thatopen/components": {
       "optional": true
     },
+    "@thatopen/fragments": {
+      "optional": true
+    },
     "@thatopen/ui": {
       "optional": true
     },
+    "flatbuffers": {
+      "optional": true
+    },
     "three": {
       "optional": true
     }