@superdoc-dev/sdk 1.0.0-next.73 → 1.0.0-next.75

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/README.md +28 -21
  2. package/dist/generated/client.cjs +476 -0
  3. package/dist/generated/client.d.ts +9049 -147
  4. package/dist/generated/client.d.ts.map +1 -1
  5. package/dist/generated/client.js +475 -0
  6. package/dist/generated/contract.cjs +1338 -287
  7. package/dist/generated/contract.d.ts.map +1 -1
  8. package/dist/generated/contract.js +1338 -287
  9. package/dist/generated/intent-dispatch.generated.cjs +1 -0
  10. package/dist/generated/intent-dispatch.generated.d.ts.map +1 -1
  11. package/dist/generated/intent-dispatch.generated.js +1 -0
  12. package/dist/helpers/format.d.ts +6 -8
  13. package/dist/helpers/format.d.ts.map +1 -1
  14. package/dist/helpers/format.js +5 -8
  15. package/dist/index.cjs +130 -8
  16. package/dist/index.d.ts +73 -8
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/index.js +130 -8
  19. package/dist/runtime/process.d.ts +2 -2
  20. package/dist/runtime/process.d.ts.map +1 -1
  21. package/dist/runtime/transport-common.d.ts +7 -0
  22. package/dist/runtime/transport-common.d.ts.map +1 -1
  23. package/dist/tools.cjs +19 -6
  24. package/dist/tools.d.ts +8 -3
  25. package/dist/tools.d.ts.map +1 -1
  26. package/dist/tools.js +19 -6
  27. package/package.json +6 -6
  28. package/tools/__pycache__/__init__.cpython-312.pyc +0 -0
  29. package/tools/__pycache__/intent_dispatch_generated.cpython-312.pyc +0 -0
  30. package/tools/catalog.json +100 -1039
  31. package/tools/intent_dispatch_generated.py +2 -0
  32. package/tools/system-prompt.md +47 -11
  33. package/tools/tools-policy.json +1 -1
  34. package/tools/tools.anthropic.json +96 -1039
  35. package/tools/tools.generic.json +99 -1041
  36. package/tools/tools.openai.json +96 -1039
  37. package/tools/tools.vercel.json +96 -1039
@@ -3,177 +3,49 @@
3
3
  "tools": [
4
4
  {
5
5
  "name": "superdoc_get_content",
6
- "description": "Read document content in various formats",
6
+ "description": "Read document content. Use action \"info\" for structure and styles, \"blocks\" for all block IDs and types, \"text\" or \"markdown\" for content. Call info or blocks before editing.",
7
7
  "input_schema": {
8
8
  "type": "object",
9
9
  "properties": {
10
10
  "action": {
11
11
  "type": "string",
12
12
  "enum": [
13
+ "blocks",
13
14
  "html",
14
15
  "info",
15
16
  "markdown",
16
17
  "text"
17
18
  ],
18
- "description": "The action to perform. One of: html, info, markdown, text."
19
+ "description": "The action to perform. One of: blocks, html, info, markdown, text."
19
20
  },
20
- "doc": {
21
- "type": "string",
22
- "description": "Document path. Optional when a session is already open."
21
+ "unflattenLists": {
22
+ "type": "boolean",
23
+ "description": "When true, flattens nested list structures in output. Default: false. Only for action 'html'. Omit for other actions."
23
24
  },
24
- "sessionId": {
25
- "type": "string",
26
- "description": "Session ID for multi-session workflows. Optional when only one session is open."
25
+ "offset": {
26
+ "type": "number",
27
+ "description": "Number of blocks to skip. Default: 0. Only for action 'blocks'. Omit for other actions."
27
28
  },
28
- "in": {
29
- "oneOf": [
30
- {
31
- "type": "object",
32
- "properties": {
33
- "kind": {
34
- "const": "story",
35
- "type": "string"
36
- },
37
- "storyType": {
38
- "const": "body",
39
- "type": "string"
40
- }
41
- },
42
- "required": [
43
- "kind",
44
- "storyType"
45
- ]
46
- },
47
- {
48
- "type": "object",
49
- "properties": {
50
- "kind": {
51
- "const": "story",
52
- "type": "string"
53
- },
54
- "storyType": {
55
- "const": "headerFooterSlot",
56
- "type": "string"
57
- },
58
- "section": {
59
- "type": "object",
60
- "properties": {
61
- "kind": {
62
- "const": "section",
63
- "type": "string"
64
- },
65
- "sectionId": {
66
- "type": "string"
67
- }
68
- },
69
- "required": [
70
- "kind",
71
- "sectionId"
72
- ]
73
- },
74
- "headerFooterKind": {
75
- "enum": [
76
- "header",
77
- "footer"
78
- ]
79
- },
80
- "variant": {
81
- "enum": [
82
- "default",
83
- "first",
84
- "even"
85
- ]
86
- },
87
- "resolution": {
88
- "enum": [
89
- "effective",
90
- "explicit"
91
- ]
92
- },
93
- "onWrite": {
94
- "enum": [
95
- "materializeIfInherited",
96
- "editResolvedPart",
97
- "error"
98
- ]
99
- }
100
- },
101
- "required": [
102
- "kind",
103
- "storyType",
104
- "section",
105
- "headerFooterKind",
106
- "variant"
107
- ]
108
- },
109
- {
110
- "type": "object",
111
- "properties": {
112
- "kind": {
113
- "const": "story",
114
- "type": "string"
115
- },
116
- "storyType": {
117
- "const": "headerFooterPart",
118
- "type": "string"
119
- },
120
- "refId": {
121
- "type": "string"
122
- }
123
- },
124
- "required": [
125
- "kind",
126
- "storyType",
127
- "refId"
128
- ]
129
- },
130
- {
131
- "type": "object",
132
- "properties": {
133
- "kind": {
134
- "const": "story",
135
- "type": "string"
136
- },
137
- "storyType": {
138
- "const": "footnote",
139
- "type": "string"
140
- },
141
- "noteId": {
142
- "type": "string"
143
- }
144
- },
145
- "required": [
146
- "kind",
147
- "storyType",
148
- "noteId"
149
- ]
150
- },
151
- {
152
- "type": "object",
153
- "properties": {
154
- "kind": {
155
- "const": "story",
156
- "type": "string"
157
- },
158
- "storyType": {
159
- "const": "endnote",
160
- "type": "string"
161
- },
162
- "noteId": {
163
- "type": "string"
164
- }
165
- },
166
- "required": [
167
- "kind",
168
- "storyType",
169
- "noteId"
170
- ]
171
- }
172
- ]
29
+ "limit": {
30
+ "type": "number",
31
+ "description": "Maximum blocks to return. Omit for all blocks. Only for action 'blocks'. Omit for other actions."
173
32
  },
174
- "unflattenLists": {
175
- "type": "boolean",
176
- "description": "When true, flattens nested list structures in output. Default: false."
33
+ "nodeTypes": {
34
+ "type": "array",
35
+ "items": {
36
+ "enum": [
37
+ "paragraph",
38
+ "heading",
39
+ "listItem",
40
+ "table",
41
+ "tableRow",
42
+ "tableCell",
43
+ "tableOfContents",
44
+ "image",
45
+ "sdt"
46
+ ]
47
+ },
48
+ "description": "Filter by block types (e.g. ['paragraph', 'heading']). Omit for all types. Only for action 'blocks'. Omit for other actions."
177
49
  }
178
50
  },
179
51
  "required": [
@@ -199,14 +71,6 @@
199
71
  ],
200
72
  "description": "The action to perform. One of: delete, insert, redo, replace, undo."
201
73
  },
202
- "doc": {
203
- "type": "string",
204
- "description": "Document path. Optional when a session is already open."
205
- },
206
- "sessionId": {
207
- "type": "string",
208
- "description": "Session ID for multi-session workflows. Optional when only one session is open."
209
- },
210
74
  "force": {
211
75
  "type": "boolean",
212
76
  "description": "Bypass confirmation checks."
@@ -416,159 +280,13 @@
416
280
  ],
417
281
  "description": "Target address object. Use 'ref' instead if you have a search handle. Format: {kind:'text', blockId, range:{start,end}} or {kind:'block', nodeType, nodeId}."
418
282
  },
419
- "in": {
420
- "oneOf": [
421
- {
422
- "type": "object",
423
- "properties": {
424
- "kind": {
425
- "const": "story",
426
- "type": "string"
427
- },
428
- "storyType": {
429
- "const": "body",
430
- "type": "string"
431
- }
432
- },
433
- "required": [
434
- "kind",
435
- "storyType"
436
- ]
437
- },
438
- {
439
- "type": "object",
440
- "properties": {
441
- "kind": {
442
- "const": "story",
443
- "type": "string"
444
- },
445
- "storyType": {
446
- "const": "headerFooterSlot",
447
- "type": "string"
448
- },
449
- "section": {
450
- "type": "object",
451
- "properties": {
452
- "kind": {
453
- "const": "section",
454
- "type": "string"
455
- },
456
- "sectionId": {
457
- "type": "string"
458
- }
459
- },
460
- "required": [
461
- "kind",
462
- "sectionId"
463
- ]
464
- },
465
- "headerFooterKind": {
466
- "enum": [
467
- "header",
468
- "footer"
469
- ]
470
- },
471
- "variant": {
472
- "enum": [
473
- "default",
474
- "first",
475
- "even"
476
- ]
477
- },
478
- "resolution": {
479
- "enum": [
480
- "effective",
481
- "explicit"
482
- ]
483
- },
484
- "onWrite": {
485
- "enum": [
486
- "materializeIfInherited",
487
- "editResolvedPart",
488
- "error"
489
- ]
490
- }
491
- },
492
- "required": [
493
- "kind",
494
- "storyType",
495
- "section",
496
- "headerFooterKind",
497
- "variant"
498
- ]
499
- },
500
- {
501
- "type": "object",
502
- "properties": {
503
- "kind": {
504
- "const": "story",
505
- "type": "string"
506
- },
507
- "storyType": {
508
- "const": "headerFooterPart",
509
- "type": "string"
510
- },
511
- "refId": {
512
- "type": "string"
513
- }
514
- },
515
- "required": [
516
- "kind",
517
- "storyType",
518
- "refId"
519
- ]
520
- },
521
- {
522
- "type": "object",
523
- "properties": {
524
- "kind": {
525
- "const": "story",
526
- "type": "string"
527
- },
528
- "storyType": {
529
- "const": "footnote",
530
- "type": "string"
531
- },
532
- "noteId": {
533
- "type": "string"
534
- }
535
- },
536
- "required": [
537
- "kind",
538
- "storyType",
539
- "noteId"
540
- ]
541
- },
542
- {
543
- "type": "object",
544
- "properties": {
545
- "kind": {
546
- "const": "story",
547
- "type": "string"
548
- },
549
- "storyType": {
550
- "const": "endnote",
551
- "type": "string"
552
- },
553
- "noteId": {
554
- "type": "string"
555
- }
556
- },
557
- "required": [
558
- "kind",
559
- "storyType",
560
- "noteId"
561
- ]
562
- }
563
- ]
564
- },
565
283
  "value": {
566
284
  "type": "string",
567
- "description": "Text content to insert."
285
+ "description": "Text content to insert. Only for action 'insert'. Omit for other actions."
568
286
  },
569
287
  "type": {
570
288
  "type": "string",
571
- "description": "Content format: 'text' (default), 'markdown', or 'html'.",
289
+ "description": "Content format: 'text' (default), 'markdown', or 'html'. Only for action 'insert'. Omit for other actions.",
572
290
  "enum": [
573
291
  "text",
574
292
  "markdown",
@@ -593,11 +311,11 @@
593
311
  }
594
312
  }
595
313
  ],
596
- "description": "Document fragment to insert (structured content)."
314
+ "description": "Document fragment to insert (structured content). Only for actions 'insert', 'replace'. Omit for other actions."
597
315
  },
598
316
  "placement": {
599
317
  "type": "string",
600
- "description": "Where to place content relative to target: 'before', 'after', 'insideStart', or 'insideEnd'.",
318
+ "description": "Where to place content relative to target: 'before', 'after', 'insideStart', or 'insideEnd'. Only for action 'insert'. Omit for other actions.",
601
319
  "enum": [
602
320
  "before",
603
321
  "after",
@@ -615,7 +333,7 @@
615
333
  ]
616
334
  }
617
335
  },
618
- "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables."
336
+ "description": "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables. Only for actions 'insert', 'replace'. Omit for other actions."
619
337
  },
620
338
  "blockId": {
621
339
  "type": "string",
@@ -631,11 +349,11 @@
631
349
  },
632
350
  "offset": {
633
351
  "type": "number",
634
- "description": "Character offset for insertion (alias for --start/--end with same value)."
352
+ "description": "Character offset for insertion (alias for --start/--end with same value). Only for action 'insert'. Omit for other actions."
635
353
  },
636
354
  "text": {
637
355
  "type": "string",
638
- "description": "Replacement text content."
356
+ "description": "Replacement text content. Only for action 'replace'. Omit for other actions."
639
357
  },
640
358
  "behavior": {
641
359
  "type": "string",
@@ -643,7 +361,7 @@
643
361
  "selection",
644
362
  "exact"
645
363
  ],
646
- "description": "Delete behavior: 'selection' (default) or 'exact'."
364
+ "description": "Delete behavior: 'selection' (default) or 'exact'. Only for action 'delete'. Omit for other actions."
647
365
  }
648
366
  },
649
367
  "required": [
@@ -654,7 +372,7 @@
654
372
  },
655
373
  {
656
374
  "name": "superdoc_format",
657
- "description": "Change text and paragraph formatting",
375
+ "description": "Change text and paragraph formatting. Use action \"inline\" with a search ref for bold/italic/etc. Use action \"set_style\" with a styleId from superdoc_get_content info to apply a named paragraph style.",
658
376
  "input_schema": {
659
377
  "type": "object",
660
378
  "properties": {
@@ -670,14 +388,6 @@
670
388
  ],
671
389
  "description": "The action to perform. One of: inline, set_alignment, set_direction, set_indentation, set_spacing, set_style."
672
390
  },
673
- "doc": {
674
- "type": "string",
675
- "description": "Document path. Optional when a session is already open."
676
- },
677
- "sessionId": {
678
- "type": "string",
679
- "description": "Session ID for multi-session workflows. Optional when only one session is open."
680
- },
681
391
  "force": {
682
392
  "type": "boolean",
683
393
  "description": "Bypass confirmation checks."
@@ -853,152 +563,6 @@
853
563
  ],
854
564
  "description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle. Required for actions 'set_style', 'set_alignment', 'set_indentation', 'set_spacing', 'set_direction'."
855
565
  },
856
- "in": {
857
- "oneOf": [
858
- {
859
- "type": "object",
860
- "properties": {
861
- "kind": {
862
- "const": "story",
863
- "type": "string"
864
- },
865
- "storyType": {
866
- "const": "body",
867
- "type": "string"
868
- }
869
- },
870
- "required": [
871
- "kind",
872
- "storyType"
873
- ]
874
- },
875
- {
876
- "type": "object",
877
- "properties": {
878
- "kind": {
879
- "const": "story",
880
- "type": "string"
881
- },
882
- "storyType": {
883
- "const": "headerFooterSlot",
884
- "type": "string"
885
- },
886
- "section": {
887
- "type": "object",
888
- "properties": {
889
- "kind": {
890
- "const": "section",
891
- "type": "string"
892
- },
893
- "sectionId": {
894
- "type": "string"
895
- }
896
- },
897
- "required": [
898
- "kind",
899
- "sectionId"
900
- ]
901
- },
902
- "headerFooterKind": {
903
- "enum": [
904
- "header",
905
- "footer"
906
- ]
907
- },
908
- "variant": {
909
- "enum": [
910
- "default",
911
- "first",
912
- "even"
913
- ]
914
- },
915
- "resolution": {
916
- "enum": [
917
- "effective",
918
- "explicit"
919
- ]
920
- },
921
- "onWrite": {
922
- "enum": [
923
- "materializeIfInherited",
924
- "editResolvedPart",
925
- "error"
926
- ]
927
- }
928
- },
929
- "required": [
930
- "kind",
931
- "storyType",
932
- "section",
933
- "headerFooterKind",
934
- "variant"
935
- ]
936
- },
937
- {
938
- "type": "object",
939
- "properties": {
940
- "kind": {
941
- "const": "story",
942
- "type": "string"
943
- },
944
- "storyType": {
945
- "const": "headerFooterPart",
946
- "type": "string"
947
- },
948
- "refId": {
949
- "type": "string"
950
- }
951
- },
952
- "required": [
953
- "kind",
954
- "storyType",
955
- "refId"
956
- ]
957
- },
958
- {
959
- "type": "object",
960
- "properties": {
961
- "kind": {
962
- "const": "story",
963
- "type": "string"
964
- },
965
- "storyType": {
966
- "const": "footnote",
967
- "type": "string"
968
- },
969
- "noteId": {
970
- "type": "string"
971
- }
972
- },
973
- "required": [
974
- "kind",
975
- "storyType",
976
- "noteId"
977
- ]
978
- },
979
- {
980
- "type": "object",
981
- "properties": {
982
- "kind": {
983
- "const": "story",
984
- "type": "string"
985
- },
986
- "storyType": {
987
- "const": "endnote",
988
- "type": "string"
989
- },
990
- "noteId": {
991
- "type": "string"
992
- }
993
- },
994
- "required": [
995
- "kind",
996
- "storyType",
997
- "noteId"
998
- ]
999
- }
1000
- ]
1001
- },
1002
566
  "inline": {
1003
567
  "type": "object",
1004
568
  "properties": {
@@ -1258,27 +822,15 @@
1258
822
  "type": "boolean"
1259
823
  }
1260
824
  },
1261
- "description": "Inline formatting properties to apply. Set a property to apply it, use null to clear it. Example: {bold: true, italic: true} or {bold: null} to remove bold."
825
+ "description": "Inline formatting properties to apply. Set a property to apply it, use null to clear it. Example: {bold: true, italic: true} or {bold: null} to remove bold. Only for action 'inline'. Omit for other actions."
1262
826
  },
1263
827
  "ref": {
1264
828
  "type": "string",
1265
- "description": "Handle ref string from a superdoc_search result. Pass the handle.ref value directly (e.g. 'text:eyJ...'). Preferred over 'target' for inline formatting."
1266
- },
1267
- "blockId": {
1268
- "type": "string",
1269
- "description": "Block ID of the target paragraph."
1270
- },
1271
- "start": {
1272
- "type": "number",
1273
- "description": "Start offset within the block (character index)."
1274
- },
1275
- "end": {
1276
- "type": "number",
1277
- "description": "End offset within the block (character index)."
829
+ "description": "Handle ref string from a superdoc_search result. Pass the handle.ref value directly (e.g. 'text:eyJ...'). Preferred over 'target' for inline formatting. Only for action 'inline'. Omit for other actions."
1278
830
  },
1279
831
  "styleId": {
1280
832
  "type": "string",
1281
- "description": "Required for action 'set_style'."
833
+ "description": "Named paragraph style ID (e.g. 'Normal', 'Heading1', 'BodyText'). Use superdoc_search to find a nearby paragraph, then inspect its style to determine the correct styleId. Required for action 'set_style'."
1282
834
  },
1283
835
  "alignment": {
1284
836
  "type": "string",
@@ -1292,35 +844,35 @@
1292
844
  },
1293
845
  "left": {
1294
846
  "type": "number",
1295
- "description": "Left indentation in twips (1440 = 1 inch)."
847
+ "description": "Left indentation in twips (1440 = 1 inch). Only for action 'set_indentation'. Omit for other actions."
1296
848
  },
1297
849
  "right": {
1298
850
  "type": "number",
1299
- "description": "Right indentation in twips (1440 = 1 inch)."
851
+ "description": "Right indentation in twips (1440 = 1 inch). Only for action 'set_indentation'. Omit for other actions."
1300
852
  },
1301
853
  "firstLine": {
1302
854
  "type": "number",
1303
- "description": "First line indent in twips. Cannot be combined with hanging."
855
+ "description": "First line indent in twips. Cannot be combined with hanging. Only for action 'set_indentation'. Omit for other actions."
1304
856
  },
1305
857
  "hanging": {
1306
858
  "type": "number",
1307
- "description": "Hanging indent in twips. Cannot be combined with firstLine."
859
+ "description": "Hanging indent in twips. Cannot be combined with firstLine. Only for action 'set_indentation'. Omit for other actions."
1308
860
  },
1309
861
  "before": {
1310
862
  "type": "number",
1311
- "description": "Space before paragraph in twips (20 twips = 1pt)."
863
+ "description": "Space before paragraph in twips (20 twips = 1pt). Only for action 'set_spacing'. Omit for other actions."
1312
864
  },
1313
865
  "after": {
1314
866
  "type": "number",
1315
- "description": "Space after paragraph in twips (20 twips = 1pt)."
867
+ "description": "Space after paragraph in twips (20 twips = 1pt). Only for action 'set_spacing'. Omit for other actions."
1316
868
  },
1317
869
  "line": {
1318
870
  "type": "number",
1319
- "description": "Line spacing value. Meaning depends on lineRule. Must be provided together with lineRule."
871
+ "description": "Line spacing value. Meaning depends on lineRule. Must be provided together with lineRule. Only for action 'set_spacing'. Omit for other actions."
1320
872
  },
1321
873
  "lineRule": {
1322
874
  "type": "string",
1323
- "description": "Line spacing rule. Required when 'line' is set.",
875
+ "description": "Line spacing rule. Required when 'line' is set. Only for action 'set_spacing'. Omit for other actions.",
1324
876
  "enum": [
1325
877
  "auto",
1326
878
  "exact",
@@ -1340,7 +892,8 @@
1340
892
  "enum": [
1341
893
  "preserve",
1342
894
  "matchDirection"
1343
- ]
895
+ ],
896
+ "description": "Only for action 'set_direction'. Omit for other actions."
1344
897
  }
1345
898
  },
1346
899
  "required": [
@@ -1351,187 +904,33 @@
1351
904
  },
1352
905
  {
1353
906
  "name": "superdoc_create",
1354
- "description": "Create structural block elements",
907
+ "description": "Create one paragraph or heading per call. After creating, search for it and apply formatting (fontFamily, fontSize) from neighboring blocks. For multiple paragraphs, use superdoc_mutations with text.insert steps instead of calling create repeatedly.",
1355
908
  "input_schema": {
1356
909
  "type": "object",
1357
910
  "properties": {
1358
911
  "action": {
1359
912
  "type": "string",
1360
- "enum": [
1361
- "heading",
1362
- "paragraph"
1363
- ],
1364
- "description": "The action to perform. One of: heading, paragraph."
1365
- },
1366
- "doc": {
1367
- "type": "string",
1368
- "description": "Document path. Optional when a session is already open."
1369
- },
1370
- "sessionId": {
1371
- "type": "string",
1372
- "description": "Session ID for multi-session workflows. Optional when only one session is open."
1373
- },
1374
- "force": {
1375
- "type": "boolean",
1376
- "description": "Bypass confirmation checks."
1377
- },
1378
- "changeMode": {
1379
- "type": "string",
1380
- "enum": [
1381
- "direct",
1382
- "tracked"
1383
- ],
1384
- "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions."
1385
- },
1386
- "dryRun": {
1387
- "type": "boolean",
1388
- "description": "Preview the result without applying changes."
1389
- },
1390
- "in": {
1391
- "oneOf": [
1392
- {
1393
- "type": "object",
1394
- "properties": {
1395
- "kind": {
1396
- "const": "story",
1397
- "type": "string"
1398
- },
1399
- "storyType": {
1400
- "const": "body",
1401
- "type": "string"
1402
- }
1403
- },
1404
- "required": [
1405
- "kind",
1406
- "storyType"
1407
- ]
1408
- },
1409
- {
1410
- "type": "object",
1411
- "properties": {
1412
- "kind": {
1413
- "const": "story",
1414
- "type": "string"
1415
- },
1416
- "storyType": {
1417
- "const": "headerFooterSlot",
1418
- "type": "string"
1419
- },
1420
- "section": {
1421
- "type": "object",
1422
- "properties": {
1423
- "kind": {
1424
- "const": "section",
1425
- "type": "string"
1426
- },
1427
- "sectionId": {
1428
- "type": "string"
1429
- }
1430
- },
1431
- "required": [
1432
- "kind",
1433
- "sectionId"
1434
- ]
1435
- },
1436
- "headerFooterKind": {
1437
- "enum": [
1438
- "header",
1439
- "footer"
1440
- ]
1441
- },
1442
- "variant": {
1443
- "enum": [
1444
- "default",
1445
- "first",
1446
- "even"
1447
- ]
1448
- },
1449
- "resolution": {
1450
- "enum": [
1451
- "effective",
1452
- "explicit"
1453
- ]
1454
- },
1455
- "onWrite": {
1456
- "enum": [
1457
- "materializeIfInherited",
1458
- "editResolvedPart",
1459
- "error"
1460
- ]
1461
- }
1462
- },
1463
- "required": [
1464
- "kind",
1465
- "storyType",
1466
- "section",
1467
- "headerFooterKind",
1468
- "variant"
1469
- ]
1470
- },
1471
- {
1472
- "type": "object",
1473
- "properties": {
1474
- "kind": {
1475
- "const": "story",
1476
- "type": "string"
1477
- },
1478
- "storyType": {
1479
- "const": "headerFooterPart",
1480
- "type": "string"
1481
- },
1482
- "refId": {
1483
- "type": "string"
1484
- }
1485
- },
1486
- "required": [
1487
- "kind",
1488
- "storyType",
1489
- "refId"
1490
- ]
1491
- },
1492
- {
1493
- "type": "object",
1494
- "properties": {
1495
- "kind": {
1496
- "const": "story",
1497
- "type": "string"
1498
- },
1499
- "storyType": {
1500
- "const": "footnote",
1501
- "type": "string"
1502
- },
1503
- "noteId": {
1504
- "type": "string"
1505
- }
1506
- },
1507
- "required": [
1508
- "kind",
1509
- "storyType",
1510
- "noteId"
1511
- ]
1512
- },
1513
- {
1514
- "type": "object",
1515
- "properties": {
1516
- "kind": {
1517
- "const": "story",
1518
- "type": "string"
1519
- },
1520
- "storyType": {
1521
- "const": "endnote",
1522
- "type": "string"
1523
- },
1524
- "noteId": {
1525
- "type": "string"
1526
- }
1527
- },
1528
- "required": [
1529
- "kind",
1530
- "storyType",
1531
- "noteId"
1532
- ]
1533
- }
1534
- ]
913
+ "enum": [
914
+ "heading",
915
+ "paragraph"
916
+ ],
917
+ "description": "The action to perform. One of: heading, paragraph."
918
+ },
919
+ "force": {
920
+ "type": "boolean",
921
+ "description": "Bypass confirmation checks."
922
+ },
923
+ "changeMode": {
924
+ "type": "string",
925
+ "enum": [
926
+ "direct",
927
+ "tracked"
928
+ ],
929
+ "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions."
930
+ },
931
+ "dryRun": {
932
+ "type": "boolean",
933
+ "description": "Preview the result without applying changes."
1535
934
  },
1536
935
  "at": {
1537
936
  "oneOf": [
@@ -1650,7 +1049,7 @@
1650
1049
  },
1651
1050
  "text": {
1652
1051
  "type": "string",
1653
- "description": "Paragraph text content."
1052
+ "description": "Paragraph text content. Each call creates ONE paragraph. For multiple items (e.g. list items), call superdoc_create separately for each item — do NOT use newlines to put multiple items in one paragraph."
1654
1053
  },
1655
1054
  "input": {
1656
1055
  "type": "object",
@@ -1686,14 +1085,6 @@
1686
1085
  ],
1687
1086
  "description": "The action to perform. One of: create, detach, indent, insert, outdent, set_level, set_type."
1688
1087
  },
1689
- "doc": {
1690
- "type": "string",
1691
- "description": "Document path. Optional when a session is already open."
1692
- },
1693
- "sessionId": {
1694
- "type": "string",
1695
- "description": "Session ID for multi-session workflows. Optional when only one session is open."
1696
- },
1697
1088
  "force": {
1698
1089
  "type": "boolean",
1699
1090
  "description": "Bypass confirmation checks."
@@ -1742,7 +1133,7 @@
1742
1133
  },
1743
1134
  "text": {
1744
1135
  "type": "string",
1745
- "description": "Text content for the new list item."
1136
+ "description": "Text content for the new list item. Only for action 'insert'. Omit for other actions."
1746
1137
  },
1747
1138
  "input": {
1748
1139
  "type": "object",
@@ -1754,7 +1145,7 @@
1754
1145
  },
1755
1146
  "mode": {
1756
1147
  "type": "string",
1757
- "description": "Required. Creation mode: 'empty' creates a new empty list at the paragraph specified by 'at'; 'fromParagraphs' converts existing paragraph(s) specified by 'target' into list items. Required for action 'create'.",
1148
+ "description": "Required. 'fromParagraphs' converts existing paragraphs into list items — each paragraph becomes one item, so create one paragraph per item first. 'empty' creates a new empty list at 'at'. Required for action 'create'.",
1758
1149
  "enum": [
1759
1150
  "empty",
1760
1151
  "fromParagraphs"
@@ -1780,7 +1171,7 @@
1780
1171
  "nodeType",
1781
1172
  "nodeId"
1782
1173
  ],
1783
- "description": "Required when mode is 'empty'. The paragraph to create the list at. Format: {kind:'block', nodeType:'paragraph', nodeId:'<id>'}."
1174
+ "description": "Required when mode is 'empty'. The paragraph to create the list at. Format: {kind:'block', nodeType:'paragraph', nodeId:'<id>'}. Only for action 'create'. Omit for other actions."
1784
1175
  },
1785
1176
  "kind": {
1786
1177
  "type": "string",
@@ -1796,7 +1187,7 @@
1796
1187
  },
1797
1188
  "preset": {
1798
1189
  "type": "string",
1799
- "description": "Predefined list style preset. Overrides 'kind' with a specific numbering or bullet format.",
1190
+ "description": "Predefined list style preset. Overrides 'kind' with a specific numbering or bullet format. Only for action 'create'. Omit for other actions.",
1800
1191
  "enum": [
1801
1192
  "decimal",
1802
1193
  "decimalParenthesis",
@@ -1879,7 +1270,8 @@
1879
1270
  "required": [
1880
1271
  "version",
1881
1272
  "levels"
1882
- ]
1273
+ ],
1274
+ "description": "Only for action 'create'. Omit for other actions."
1883
1275
  },
1884
1276
  "sequence": {
1885
1277
  "oneOf": [
@@ -1910,11 +1302,12 @@
1910
1302
  "mode"
1911
1303
  ]
1912
1304
  }
1913
- ]
1305
+ ],
1306
+ "description": "Only for action 'create'. Omit for other actions."
1914
1307
  },
1915
1308
  "continuity": {
1916
1309
  "type": "string",
1917
- "description": "Numbering continuity: 'preserve' keeps numbering; 'none' restarts.",
1310
+ "description": "Numbering continuity: 'preserve' keeps numbering; 'none' restarts. Only for action 'set_type'. Omit for other actions.",
1918
1311
  "enum": [
1919
1312
  "preserve",
1920
1313
  "none"
@@ -1944,14 +1337,6 @@
1944
1337
  ],
1945
1338
  "description": "The action to perform. One of: create, delete, get, list, update."
1946
1339
  },
1947
- "doc": {
1948
- "type": "string",
1949
- "description": "Document path. Optional when a session is already open."
1950
- },
1951
- "sessionId": {
1952
- "type": "string",
1953
- "description": "Session ID for multi-session workflows. Optional when only one session is open."
1954
- },
1955
1340
  "force": {
1956
1341
  "type": "boolean",
1957
1342
  "description": "Bypass confirmation checks."
@@ -1999,23 +1384,11 @@
1999
1384
  "blockId",
2000
1385
  "range"
2001
1386
  ],
2002
- "description": "Text range to anchor the comment: {kind:'text', blockId:'...', range:{start:N, end:N}}."
1387
+ "description": "Text range to anchor the comment: {kind:'text', blockId:'...', range:{start:N, end:N}}. Only for actions 'create', 'update'. Omit for other actions."
2003
1388
  },
2004
1389
  "parentId": {
2005
1390
  "type": "string",
2006
- "description": "Parent comment ID for creating a threaded reply."
2007
- },
2008
- "blockId": {
2009
- "type": "string",
2010
- "description": "Block ID of the target paragraph."
2011
- },
2012
- "start": {
2013
- "type": "number",
2014
- "description": "Start offset within the block (character index)."
2015
- },
2016
- "end": {
2017
- "type": "number",
2018
- "description": "End offset within the block (character index)."
1391
+ "description": "Parent comment ID for creating a threaded reply. Only for action 'create'. Omit for other actions."
2019
1392
  },
2020
1393
  "id": {
2021
1394
  "type": "string",
@@ -2023,26 +1396,26 @@
2023
1396
  },
2024
1397
  "status": {
2025
1398
  "type": "string",
2026
- "description": "Set comment status. Use 'resolved' to mark as resolved.",
1399
+ "description": "Set comment status. Use 'resolved' to mark as resolved. Only for action 'update'. Omit for other actions.",
2027
1400
  "enum": [
2028
1401
  "resolved"
2029
1402
  ]
2030
1403
  },
2031
1404
  "isInternal": {
2032
1405
  "type": "boolean",
2033
- "description": "When true, marks the comment as internal (hidden from external collaborators)."
1406
+ "description": "When true, marks the comment as internal (hidden from external collaborators). Only for action 'update'. Omit for other actions."
2034
1407
  },
2035
1408
  "includeResolved": {
2036
1409
  "type": "boolean",
2037
- "description": "When true, includes resolved comments in results. Default: false."
1410
+ "description": "When true, includes resolved comments in results. Default: false. Only for action 'list'. Omit for other actions."
2038
1411
  },
2039
1412
  "limit": {
2040
1413
  "type": "number",
2041
- "description": "Maximum number of comments to return."
1414
+ "description": "Maximum number of comments to return. Only for action 'list'. Omit for other actions."
2042
1415
  },
2043
1416
  "offset": {
2044
1417
  "type": "number",
2045
- "description": "Number of comments to skip for pagination."
1418
+ "description": "Number of comments to skip for pagination. Only for action 'list'. Omit for other actions."
2046
1419
  }
2047
1420
  },
2048
1421
  "required": [
@@ -2065,25 +1438,17 @@
2065
1438
  ],
2066
1439
  "description": "The action to perform. One of: decide, list."
2067
1440
  },
2068
- "doc": {
2069
- "type": "string",
2070
- "description": "Document path. Optional when a session is already open."
2071
- },
2072
- "sessionId": {
2073
- "type": "string",
2074
- "description": "Session ID for multi-session workflows. Optional when only one session is open."
2075
- },
2076
1441
  "limit": {
2077
1442
  "type": "number",
2078
- "description": "Maximum number of tracked changes to return."
1443
+ "description": "Maximum number of tracked changes to return. Only for action 'list'. Omit for other actions."
2079
1444
  },
2080
1445
  "offset": {
2081
1446
  "type": "number",
2082
- "description": "Number of tracked changes to skip for pagination."
1447
+ "description": "Number of tracked changes to skip for pagination. Only for action 'list'. Omit for other actions."
2083
1448
  },
2084
1449
  "type": {
2085
1450
  "type": "string",
2086
- "description": "Filter by change type: 'insert', 'delete', or 'format'.",
1451
+ "description": "Filter by change type: 'insert', 'delete', or 'format'. Only for action 'list'. Omit for other actions.",
2087
1452
  "enum": [
2088
1453
  "insert",
2089
1454
  "delete",
@@ -2092,7 +1457,7 @@
2092
1457
  },
2093
1458
  "force": {
2094
1459
  "type": "boolean",
2095
- "description": "Bypass confirmation checks."
1460
+ "description": "Bypass confirmation checks. Only for action 'decide'. Omit for other actions."
2096
1461
  },
2097
1462
  "changeMode": {
2098
1463
  "type": "string",
@@ -2100,7 +1465,7 @@
2100
1465
  "direct",
2101
1466
  "tracked"
2102
1467
  ],
2103
- "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions."
1468
+ "description": "Edit mode: \"direct\" applies changes immediately, \"tracked\" records as suggestions. Only for action 'decide'. Omit for other actions."
2104
1469
  },
2105
1470
  "decision": {
2106
1471
  "type": "string",
@@ -2152,160 +1517,6 @@
2152
1517
  "input_schema": {
2153
1518
  "type": "object",
2154
1519
  "properties": {
2155
- "doc": {
2156
- "type": "string",
2157
- "description": "Document path. Optional when a session is already open."
2158
- },
2159
- "sessionId": {
2160
- "type": "string",
2161
- "description": "Session ID for multi-session workflows. Optional when only one session is open."
2162
- },
2163
- "in": {
2164
- "oneOf": [
2165
- {
2166
- "type": "object",
2167
- "properties": {
2168
- "kind": {
2169
- "const": "story",
2170
- "type": "string"
2171
- },
2172
- "storyType": {
2173
- "const": "body",
2174
- "type": "string"
2175
- }
2176
- },
2177
- "required": [
2178
- "kind",
2179
- "storyType"
2180
- ]
2181
- },
2182
- {
2183
- "type": "object",
2184
- "properties": {
2185
- "kind": {
2186
- "const": "story",
2187
- "type": "string"
2188
- },
2189
- "storyType": {
2190
- "const": "headerFooterSlot",
2191
- "type": "string"
2192
- },
2193
- "section": {
2194
- "type": "object",
2195
- "properties": {
2196
- "kind": {
2197
- "const": "section",
2198
- "type": "string"
2199
- },
2200
- "sectionId": {
2201
- "type": "string"
2202
- }
2203
- },
2204
- "required": [
2205
- "kind",
2206
- "sectionId"
2207
- ]
2208
- },
2209
- "headerFooterKind": {
2210
- "enum": [
2211
- "header",
2212
- "footer"
2213
- ]
2214
- },
2215
- "variant": {
2216
- "enum": [
2217
- "default",
2218
- "first",
2219
- "even"
2220
- ]
2221
- },
2222
- "resolution": {
2223
- "enum": [
2224
- "effective",
2225
- "explicit"
2226
- ]
2227
- },
2228
- "onWrite": {
2229
- "enum": [
2230
- "materializeIfInherited",
2231
- "editResolvedPart",
2232
- "error"
2233
- ]
2234
- }
2235
- },
2236
- "required": [
2237
- "kind",
2238
- "storyType",
2239
- "section",
2240
- "headerFooterKind",
2241
- "variant"
2242
- ]
2243
- },
2244
- {
2245
- "type": "object",
2246
- "properties": {
2247
- "kind": {
2248
- "const": "story",
2249
- "type": "string"
2250
- },
2251
- "storyType": {
2252
- "const": "headerFooterPart",
2253
- "type": "string"
2254
- },
2255
- "refId": {
2256
- "type": "string"
2257
- }
2258
- },
2259
- "required": [
2260
- "kind",
2261
- "storyType",
2262
- "refId"
2263
- ]
2264
- },
2265
- {
2266
- "type": "object",
2267
- "properties": {
2268
- "kind": {
2269
- "const": "story",
2270
- "type": "string"
2271
- },
2272
- "storyType": {
2273
- "const": "footnote",
2274
- "type": "string"
2275
- },
2276
- "noteId": {
2277
- "type": "string"
2278
- }
2279
- },
2280
- "required": [
2281
- "kind",
2282
- "storyType",
2283
- "noteId"
2284
- ]
2285
- },
2286
- {
2287
- "type": "object",
2288
- "properties": {
2289
- "kind": {
2290
- "const": "story",
2291
- "type": "string"
2292
- },
2293
- "storyType": {
2294
- "const": "endnote",
2295
- "type": "string"
2296
- },
2297
- "noteId": {
2298
- "type": "string"
2299
- }
2300
- },
2301
- "required": [
2302
- "kind",
2303
- "storyType",
2304
- "noteId"
2305
- ]
2306
- }
2307
- ]
2308
- },
2309
1520
  "select": {
2310
1521
  "oneOf": [
2311
1522
  {
@@ -2469,163 +1680,9 @@
2469
1680
  ],
2470
1681
  "description": "The action to perform. One of: apply, preview."
2471
1682
  },
2472
- "doc": {
2473
- "type": "string",
2474
- "description": "Document path. Optional when a session is already open."
2475
- },
2476
- "sessionId": {
2477
- "type": "string",
2478
- "description": "Session ID for multi-session workflows. Optional when only one session is open."
2479
- },
2480
- "in": {
2481
- "oneOf": [
2482
- {
2483
- "type": "object",
2484
- "properties": {
2485
- "kind": {
2486
- "const": "story",
2487
- "type": "string"
2488
- },
2489
- "storyType": {
2490
- "const": "body",
2491
- "type": "string"
2492
- }
2493
- },
2494
- "required": [
2495
- "kind",
2496
- "storyType"
2497
- ]
2498
- },
2499
- {
2500
- "type": "object",
2501
- "properties": {
2502
- "kind": {
2503
- "const": "story",
2504
- "type": "string"
2505
- },
2506
- "storyType": {
2507
- "const": "headerFooterSlot",
2508
- "type": "string"
2509
- },
2510
- "section": {
2511
- "type": "object",
2512
- "properties": {
2513
- "kind": {
2514
- "const": "section",
2515
- "type": "string"
2516
- },
2517
- "sectionId": {
2518
- "type": "string"
2519
- }
2520
- },
2521
- "required": [
2522
- "kind",
2523
- "sectionId"
2524
- ]
2525
- },
2526
- "headerFooterKind": {
2527
- "enum": [
2528
- "header",
2529
- "footer"
2530
- ]
2531
- },
2532
- "variant": {
2533
- "enum": [
2534
- "default",
2535
- "first",
2536
- "even"
2537
- ]
2538
- },
2539
- "resolution": {
2540
- "enum": [
2541
- "effective",
2542
- "explicit"
2543
- ]
2544
- },
2545
- "onWrite": {
2546
- "enum": [
2547
- "materializeIfInherited",
2548
- "editResolvedPart",
2549
- "error"
2550
- ]
2551
- }
2552
- },
2553
- "required": [
2554
- "kind",
2555
- "storyType",
2556
- "section",
2557
- "headerFooterKind",
2558
- "variant"
2559
- ]
2560
- },
2561
- {
2562
- "type": "object",
2563
- "properties": {
2564
- "kind": {
2565
- "const": "story",
2566
- "type": "string"
2567
- },
2568
- "storyType": {
2569
- "const": "headerFooterPart",
2570
- "type": "string"
2571
- },
2572
- "refId": {
2573
- "type": "string"
2574
- }
2575
- },
2576
- "required": [
2577
- "kind",
2578
- "storyType",
2579
- "refId"
2580
- ]
2581
- },
2582
- {
2583
- "type": "object",
2584
- "properties": {
2585
- "kind": {
2586
- "const": "story",
2587
- "type": "string"
2588
- },
2589
- "storyType": {
2590
- "const": "footnote",
2591
- "type": "string"
2592
- },
2593
- "noteId": {
2594
- "type": "string"
2595
- }
2596
- },
2597
- "required": [
2598
- "kind",
2599
- "storyType",
2600
- "noteId"
2601
- ]
2602
- },
2603
- {
2604
- "type": "object",
2605
- "properties": {
2606
- "kind": {
2607
- "const": "story",
2608
- "type": "string"
2609
- },
2610
- "storyType": {
2611
- "const": "endnote",
2612
- "type": "string"
2613
- },
2614
- "noteId": {
2615
- "type": "string"
2616
- }
2617
- },
2618
- "required": [
2619
- "kind",
2620
- "storyType",
2621
- "noteId"
2622
- ]
2623
- }
2624
- ]
2625
- },
2626
1683
  "expectedRevision": {
2627
1684
  "type": "string",
2628
- "description": "Document revision for optimistic concurrency. Mutation fails if document was modified since this revision."
1685
+ "description": "Document revision for optimistic concurrency. Mutation fails if document was modified since this revision. Only for action 'preview'. Omit for other actions."
2629
1686
  },
2630
1687
  "atomic": {
2631
1688
  "type": "boolean",
@@ -4548,7 +3605,7 @@
4548
3605
  },
4549
3606
  "force": {
4550
3607
  "type": "boolean",
4551
- "description": "Bypass confirmation checks."
3608
+ "description": "Bypass confirmation checks. Only for action 'apply'. Omit for other actions."
4552
3609
  }
4553
3610
  },
4554
3611
  "required": [