@superdoc-dev/sdk 1.8.0-next.4 → 1.8.0-next.6

package/dist/generated/intent-dispatch.generated.cjs

@@ -53,10 +53,15 @@ function dispatchIntentTool(toolName, args, execute) {
             switch (action) {
                 case 'insert': return execute('doc.lists.insert', rest);
                 case 'create': return execute('doc.lists.create', rest);
+                case 'attach': return execute('doc.lists.attach', rest);
                 case 'detach': return execute('doc.lists.detach', rest);
                 case 'indent': return execute('doc.lists.indent', rest);
                 case 'outdent': return execute('doc.lists.outdent', rest);
+                case 'merge': return execute('doc.lists.merge', rest);
+                case 'split': return execute('doc.lists.split', rest);
                 case 'set_level': return execute('doc.lists.setLevel', rest);
+                case 'set_value': return execute('doc.lists.setValue', rest);
+                case 'continue_previous': return execute('doc.lists.continuePrevious', rest);
                 case 'set_type': return execute('doc.lists.setType', rest);
                 default: throw new Error(`Unknown action for superdoc_list: ${action}`);
             }

package/dist/generated/intent-dispatch.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intent-dispatch.generated.d.ts","sourceRoot":"","sources":["../../src/generated/intent-dispatch.generated.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GACxE,OAAO,CA4FT"}
+{"version":3,"file":"intent-dispatch.generated.d.ts","sourceRoot":"","sources":["../../src/generated/intent-dispatch.generated.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GACxE,OAAO,CAiGT"}

package/dist/generated/intent-dispatch.generated.js

@@ -51,10 +51,15 @@ export function dispatchIntentTool(toolName, args, execute) {
             switch (action) {
                 case 'insert': return execute('doc.lists.insert', rest);
                 case 'create': return execute('doc.lists.create', rest);
+                case 'attach': return execute('doc.lists.attach', rest);
                 case 'detach': return execute('doc.lists.detach', rest);
                 case 'indent': return execute('doc.lists.indent', rest);
                 case 'outdent': return execute('doc.lists.outdent', rest);
+                case 'merge': return execute('doc.lists.merge', rest);
+                case 'split': return execute('doc.lists.split', rest);
                 case 'set_level': return execute('doc.lists.setLevel', rest);
+                case 'set_value': return execute('doc.lists.setValue', rest);
+                case 'continue_previous': return execute('doc.lists.continuePrevious', rest);
                 case 'set_type': return execute('doc.lists.setType', rest);
                 default: throw new Error(`Unknown action for superdoc_list: ${action}`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/sdk",
-  "version": "1.8.0-next.4",
+  "version": "1.8.0-next.6",
   "private": false,
   "type": "module",
   "main": "./dist/index.cjs",
@@ -26,11 +26,11 @@
     "typescript": "^5.9.2"
   },
   "optionalDependencies": {
-    "@superdoc-dev/sdk-darwin-arm64": "1.8.0-next.4",
-    "@superdoc-dev/sdk-linux-x64": "1.8.0-next.4",
-    "@superdoc-dev/sdk-linux-arm64": "1.8.0-next.4",
-    "@superdoc-dev/sdk-windows-x64": "1.8.0-next.4",
-    "@superdoc-dev/sdk-darwin-x64": "1.8.0-next.4"
+    "@superdoc-dev/sdk-darwin-x64": "1.8.0-next.6",
+    "@superdoc-dev/sdk-linux-x64": "1.8.0-next.6",
+    "@superdoc-dev/sdk-darwin-arm64": "1.8.0-next.6",
+    "@superdoc-dev/sdk-linux-arm64": "1.8.0-next.6",
+    "@superdoc-dev/sdk-windows-x64": "1.8.0-next.6"
   },
   "publishConfig": {
     "access": "public"

package/tools/catalog.json

@@ -1268,22 +1268,27 @@
     },
     {
       "toolName": "superdoc_list",
-      "description": "Create and manipulate bullet and numbered lists. To create a list: first create all paragraphs at the SAME location using superdoc_create (chain each using the previous nodeId as the \"at\" target). Then call action \"create\" with mode:\"fromParagraphs\", a preset (\"disc\" for bullet, \"decimal\" for numbered), and a range target: {from:{kind:\"block\", nodeType:\"paragraph\", nodeId:\"<first>\"}, to:{kind:\"block\", nodeType:\"paragraph\", nodeId:\"<last>\"}}. The range converts ALL paragraphs between from and to into list items. Make sure no other content exists between them. Action \"set_type\" converts between bullet and ordered (target any item in the list, kind:\"ordered\" or \"bullet\"). Action \"insert\" adds a new item before/after a target list item. Actions \"indent\" and \"outdent\" change nesting level; \"set_level\" jumps to a specific level (0-8). Action \"detach\" converts a list item back to a plain paragraph. Do NOT target paragraphs with indent/outdent/set_type; these actions require a listItem target.",
+      "description": "Create and manipulate bullet and numbered lists. Most actions require a list-item target: {kind:\"block\", nodeType:\"listItem\", nodeId:\"<id>\"}. Exceptions: \"create\" and \"attach\" operate on paragraph targets (they turn paragraphs into list items). Find nodeIds via superdoc_get_content({action:\"blocks\"}) — pick listItem blocks for most actions, paragraph blocks for create/attach.\n\nCREATE & CONVERT:\n• \"create\" — make a NEW list from paragraphs. Two modes: mode:\"empty\" with at:{kind:\"block\", nodeType:\"paragraph\", nodeId} converts a single paragraph; mode:\"fromParagraphs\" with target:{from:{...paragraph block address}, to:{...paragraph block address}} converts a range — ALL paragraphs between from and to become items, so make sure no other content sits between them. Pass a preset (\"disc\"|\"circle\"|\"square\"|\"dash\" for bullets; \"decimal\"|\"decimalParenthesis\"|\"lowerLetter\"|\"upperLetter\"|\"lowerRoman\"|\"upperRoman\" for ordered) or a custom style. Use \"create\" to start a fresh list — NOT to extend an existing one (use \"attach\" for that).\n• \"attach\" — add paragraphs to an EXISTING list, inheriting its numbering definition. Pass target:{paragraph block address} (or {from, to} range of paragraphs) + attachTo:{kind:\"block\", nodeType:\"listItem\", nodeId:\"<any item in destination list>\"} + optional level:0..8. Use this to extend a list or as the second half of a merge workflow (see \"join\" below).\n• \"set_type\" — convert an existing list between ordered and bullet. Pass target:{listItem} + kind:\"ordered\" or \"bullet\". Adjacent compatible sequences are merged automatically to preserve continuous numbering.\n• \"detach\" — convert a list item back to a plain paragraph. Pass target:{listItem}.\n\nITEMS & NESTING:\n• \"insert\" — add a new list item adjacent to an existing item in the same list. Pass target:{listItem} + position:\"before\"|\"after\" + optional text. Use this (NOT superdoc_create) to add items to an existing list.\n• \"indent\" / \"outdent\" — bump the target item's nesting level by one (0-8 range). Pass target:{listItem}.\n• \"set_level\" — jump the target item to an explicit level. Pass target:{listItem} + level:0..8.\n\nNUMBERING (ordered lists):\n• \"set_value\" — restart numbering at the target. Pass target:{listItem} + value:<number> (e.g. value:1 to start over) or value:null to clear a previous override. Mid-sequence targets are atomically split off into their own sequence.\n• \"continue_previous\" — make the target's sequence continue numbering from the nearest compatible previous sequence (same abstract definition). Pass target:{listItem of the sequence you want to renumber}. Fails with NO_COMPATIBLE_PREVIOUS or INCOMPATIBLE_DEFINITIONS if no matching prior sequence exists.\n\nSEQUENCE SHAPE (merge / split):\n• \"merge\" — merge the target's sequence with an adjacent one into one continuous list. Pass target:{listItem} + direction:\"withPrevious\" or \"withNext\". Absorbed items adopt the absorbing sequence's numbering definition, and empty paragraphs between the two sequences are removed so numbering flows continuously.\n• \"split\" — split the target's sequence at the target item into two independent lists. The target and everything after become a new sequence that restarts numbering at 1. Pass target:{listItem}; add restartNumbering:false to keep the count continuing instead of restarting.",
       "inputSchema": {
         "type": "object",
         "properties": {
           "action": {
             "type": "string",
             "enum": [
+              "attach",
+              "continue_previous",
               "create",
               "detach",
               "indent",
               "insert",
+              "merge",
               "outdent",
               "set_level",
-              "set_type"
+              "set_type",
+              "set_value",
+              "split"
             ],
-            "description": "The action to perform. One of: create, detach, indent, insert, outdent, set_level, set_type."
+            "description": "The action to perform. One of: attach, continue_previous, create, detach, indent, insert, merge, outdent, set_level, set_type, set_value, split."
           },
           "force": {
             "type": "boolean",
@@ -1321,7 +1326,7 @@
               "nodeType",
               "nodeId"
             ],
-            "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:'<id>'}. Required for actions 'insert', 'detach', 'indent', 'outdent', 'set_level', 'set_type'."
+            "description": "The target list item. For 'insert': the item to insert relative to. For 'create' with mode 'fromParagraphs': use nodeType 'paragraph' instead. Format: {kind:'block', nodeType:'listItem', nodeId:'<id>'}. Required for actions 'insert', 'attach', 'detach', 'indent', 'outdent', 'merge', 'split', 'set_level', 'set_value', 'continue_previous', 'set_type'."
           },
           "position": {
             "type": "string",
@@ -1505,6 +1510,44 @@
             ],
             "description": "Only for action 'create'. Omit for other actions."
           },
+          "attachTo": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "block",
+                "type": "string"
+              },
+              "nodeType": {
+                "const": "listItem",
+                "type": "string"
+              },
+              "nodeId": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "kind",
+              "nodeType",
+              "nodeId"
+            ],
+            "description": "Required for action 'attach'."
+          },
+          "direction": {
+            "type": "string",
+            "enum": [
+              "withPrevious",
+              "withNext"
+            ],
+            "description": "Required for action 'merge'."
+          },
+          "restartNumbering": {
+            "type": "boolean",
+            "description": "Only for action 'split'. Omit for other actions."
+          },
+          "value": {
+            "type": "object",
+            "description": "Required for action 'set_value'."
+          },
           "continuity": {
             "type": "string",
             "description": "Numbering continuity: 'preserve' keeps numbering; 'none' restarts. Only for action 'set_type'. Omit for other actions.",
@@ -1536,6 +1579,14 @@
             "mode"
           ]
         },
+        {
+          "operationId": "doc.lists.attach",
+          "intentAction": "attach",
+          "required": [
+            "target",
+            "attachTo"
+          ]
+        },
         {
           "operationId": "doc.lists.detach",
           "intentAction": "detach",
@@ -1557,6 +1608,21 @@
             "target"
           ]
         },
+        {
+          "operationId": "doc.lists.merge",
+          "intentAction": "merge",
+          "required": [
+            "target",
+            "direction"
+          ]
+        },
+        {
+          "operationId": "doc.lists.split",
+          "intentAction": "split",
+          "required": [
+            "target"
+          ]
+        },
         {
           "operationId": "doc.lists.setLevel",
           "intentAction": "set_level",
@@ -1565,6 +1631,21 @@
             "level"
           ]
         },
+        {
+          "operationId": "doc.lists.setValue",
+          "intentAction": "set_value",
+          "required": [
+            "target",
+            "value"
+          ]
+        },
+        {
+          "operationId": "doc.lists.continuePrevious",
+          "intentAction": "continue_previous",
+          "required": [
+            "target"
+          ]
+        },
         {
           "operationId": "doc.lists.setType",
           "intentAction": "set_type",

package/tools/intent_dispatch_generated.py

@@ -79,14 +79,24 @@ def dispatch_intent_tool(
             return execute('doc.lists.insert', rest)
         elif action == 'create':
             return execute('doc.lists.create', rest)
+        elif action == 'attach':
+            return execute('doc.lists.attach', rest)
         elif action == 'detach':
             return execute('doc.lists.detach', rest)
         elif action == 'indent':
             return execute('doc.lists.indent', rest)
         elif action == 'outdent':
             return execute('doc.lists.outdent', rest)
+        elif action == 'merge':
+            return execute('doc.lists.merge', rest)
+        elif action == 'split':
+            return execute('doc.lists.split', rest)
         elif action == 'set_level':
             return execute('doc.lists.setLevel', rest)
+        elif action == 'set_value':
+            return execute('doc.lists.setValue', rest)
+        elif action == 'continue_previous':
+            return execute('doc.lists.continuePrevious', rest)
         elif action == 'set_type':
             return execute('doc.lists.setType', rest)
         else:

package/tools/prompt-templates/system-prompt-core.md

@@ -160,6 +160,94 @@ Use preset "disc" for bullets, "decimal" for numbered. WARNING: the range conver
 
 3. To change a bullet list to numbered: `superdoc_list({action: "set_type", target: {kind: "block", nodeType: "listItem", nodeId: "<anyItemId>"}, kind: "ordered"})`
 
+### Add items to an existing list
+
+To add a new item adjacent to an existing list item, use `superdoc_list({action: "insert"})`, NOT `superdoc_create({action: "paragraph"})` — the latter creates a standalone paragraph that is not part of the list:
+
+```
+superdoc_get_content({action: "blocks"})  // find the listItem nodeId you want to insert next to
+superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}, position: "after", text: "New item text"})
+```
+
+**Level inheritance.** The new item inherits the target's nesting level. Insert after a level-0 item → new item is level 0. Insert after a level-2 item → new item is level 2. To change the level, chain `indent` / `outdent` / `set_level` on the nodeId returned in the insert response.
+
+**Use the nodeId from the response directly.** `superdoc_list({action: "insert"})` returns `{item: {nodeId: "<id>"}}` — that id is ready for subsequent `indent`, `outdent`, `set_level`, or text edits. You do NOT need to re-fetch blocks between the insert and the follow-up operation.
+
+### Add a sub-point under an existing item
+
+Insert a peer, then indent it one level:
+
+```
+// 1. Insert a peer item after the parent — new item is at the parent's level
+const resp = superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<parentItemId>"}, position: "after", text: "Sub-point"})
+
+// 2. Indent using the nodeId from resp.item.nodeId
+superdoc_list({action: "indent", target: {kind: "block", nodeType: "listItem", nodeId: "<resp.item.nodeId>"}})
+```
+
+### Build a nested list with mixed levels
+
+`lists.create` produces a flat list. Add nesting by chaining `insert` + `indent` / `set_level`, using the nodeId returned by each insert to target the next step:
+
+```
+// Starting point: a list item at level 0 ("Parent" with nodeId <parent>)
+
+// Sibling at level 0
+const r1 = superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<parent>"}, position: "after", text: "Sibling"})
+
+// Child at level 1 (insert after r1, then indent)
+const r2 = superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<r1.item.nodeId>"}, position: "after", text: "Child"})
+superdoc_list({action: "indent", target: {kind: "block", nodeType: "listItem", nodeId: "<r2.item.nodeId>"}})
+
+// Grandchild at level 3 (insert after r2, then jump to level 3 directly)
+const r3 = superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<r2.item.nodeId>"}, position: "after", text: "Deep"})
+superdoc_list({action: "set_level", target: {kind: "block", nodeType: "listItem", nodeId: "<r3.item.nodeId>"}, level: 3})
+```
+
+`indent` bumps the level by one (bounded 0–8). `set_level` jumps directly to any level 0–8. Markers update automatically based on the list's definition for each level (e.g. `1.` / `a.` / `i.` for an ordered list).
+
+### Merge two adjacent lists into one
+
+Use `merge` — it handles the common case where two ordered or bulleted lists sit next to each other and should become one continuous list. Absorbed items adopt the absorbing sequence's definition, and any empty paragraphs between the two lists are removed so numbering flows continuously.
+
+```
+superdoc_get_content({action: "blocks"})  // find a listItem in either sequence
+// To merge with the previous sequence:
+superdoc_list({action: "merge", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}, direction: "withPrevious"})
+// Or with the next sequence:
+superdoc_list({action: "merge", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}, direction: "withNext"})
+```
+
+### Split a list into two
+
+Use `split` to break one list into two independent lists at a specific item. The target and everything after become a new sequence that restarts numbering at 1:
+
+```
+superdoc_list({action: "split", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}})
+```
+
+Pass `restartNumbering: false` if you want the new half to keep counting from where the original left off.
+
+### Restart numbering at a specific item
+
+For ordered lists. To make item N restart from a chosen number (commonly 1):
+
+```
+superdoc_list({action: "set_value", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}, value: 1})
+```
+
+Pass `value: null` to clear a previously-set restart override and let the item resume natural numbering.
+
+### Continue numbering across a break
+
+For ordered lists. When two sibling sequences should be numbered as one (e.g. numbering jumps back to 1 and you want it to continue from where the previous list left off), target the FIRST item of the second sequence:
+
+```
+superdoc_list({action: "continue_previous", target: {kind: "block", nodeType: "listItem", nodeId: "<firstItemOfSecondList>"}})
+```
+
+Fails with `NO_COMPATIBLE_PREVIOUS` or `INCOMPATIBLE_DEFINITIONS` if no prior sequence shares the same abstract definition. In that case, use `merge` instead — it handles mismatched definitions, removes empty gap paragraphs, and produces one continuous list.
+
 ### Insert content into a document (new or existing)
 
 Markdown insert creates block structure but uses default formatting. You MUST follow up with formatting so inserted content looks like it belongs in the document.

package/tools/system-prompt-mcp.md

@@ -209,6 +209,94 @@ Use preset "disc" for bullets, "decimal" for numbered. WARNING: the range conver
 
 3. To change a bullet list to numbered: `superdoc_list({action: "set_type", target: {kind: "block", nodeType: "listItem", nodeId: "<anyItemId>"}, kind: "ordered"})`
 
+### Add items to an existing list
+
+To add a new item adjacent to an existing list item, use `superdoc_list({action: "insert"})`, NOT `superdoc_create({action: "paragraph"})` — the latter creates a standalone paragraph that is not part of the list:
+
+```
+superdoc_get_content({action: "blocks"})  // find the listItem nodeId you want to insert next to
+superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}, position: "after", text: "New item text"})
+```
+
+**Level inheritance.** The new item inherits the target's nesting level. Insert after a level-0 item → new item is level 0. Insert after a level-2 item → new item is level 2. To change the level, chain `indent` / `outdent` / `set_level` on the nodeId returned in the insert response.
+
+**Use the nodeId from the response directly.** `superdoc_list({action: "insert"})` returns `{item: {nodeId: "<id>"}}` — that id is ready for subsequent `indent`, `outdent`, `set_level`, or text edits. You do NOT need to re-fetch blocks between the insert and the follow-up operation.
+
+### Add a sub-point under an existing item
+
+Insert a peer, then indent it one level:
+
+```
+// 1. Insert a peer item after the parent — new item is at the parent's level
+const resp = superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<parentItemId>"}, position: "after", text: "Sub-point"})
+
+// 2. Indent using the nodeId from resp.item.nodeId
+superdoc_list({action: "indent", target: {kind: "block", nodeType: "listItem", nodeId: "<resp.item.nodeId>"}})
+```
+
+### Build a nested list with mixed levels
+
+`lists.create` produces a flat list. Add nesting by chaining `insert` + `indent` / `set_level`, using the nodeId returned by each insert to target the next step:
+
+```
+// Starting point: a list item at level 0 ("Parent" with nodeId <parent>)
+
+// Sibling at level 0
+const r1 = superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<parent>"}, position: "after", text: "Sibling"})
+
+// Child at level 1 (insert after r1, then indent)
+const r2 = superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<r1.item.nodeId>"}, position: "after", text: "Child"})
+superdoc_list({action: "indent", target: {kind: "block", nodeType: "listItem", nodeId: "<r2.item.nodeId>"}})
+
+// Grandchild at level 3 (insert after r2, then jump to level 3 directly)
+const r3 = superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<r2.item.nodeId>"}, position: "after", text: "Deep"})
+superdoc_list({action: "set_level", target: {kind: "block", nodeType: "listItem", nodeId: "<r3.item.nodeId>"}, level: 3})
+```
+
+`indent` bumps the level by one (bounded 0–8). `set_level` jumps directly to any level 0–8. Markers update automatically based on the list's definition for each level (e.g. `1.` / `a.` / `i.` for an ordered list).
+
+### Merge two adjacent lists into one
+
+Use `merge` — it handles the common case where two ordered or bulleted lists sit next to each other and should become one continuous list. Absorbed items adopt the absorbing sequence's definition, and any empty paragraphs between the two lists are removed so numbering flows continuously.
+
+```
+superdoc_get_content({action: "blocks"})  // find a listItem in either sequence
+// To merge with the previous sequence:
+superdoc_list({action: "merge", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}, direction: "withPrevious"})
+// Or with the next sequence:
+superdoc_list({action: "merge", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}, direction: "withNext"})
+```
+
+### Split a list into two
+
+Use `split` to break one list into two independent lists at a specific item. The target and everything after become a new sequence that restarts numbering at 1:
+
+```
+superdoc_list({action: "split", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}})
+```
+
+Pass `restartNumbering: false` if you want the new half to keep counting from where the original left off.
+
+### Restart numbering at a specific item
+
+For ordered lists. To make item N restart from a chosen number (commonly 1):
+
+```
+superdoc_list({action: "set_value", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}, value: 1})
+```
+
+Pass `value: null` to clear a previously-set restart override and let the item resume natural numbering.
+
+### Continue numbering across a break
+
+For ordered lists. When two sibling sequences should be numbered as one (e.g. numbering jumps back to 1 and you want it to continue from where the previous list left off), target the FIRST item of the second sequence:
+
+```
+superdoc_list({action: "continue_previous", target: {kind: "block", nodeType: "listItem", nodeId: "<firstItemOfSecondList>"}})
+```
+
+Fails with `NO_COMPATIBLE_PREVIOUS` or `INCOMPATIBLE_DEFINITIONS` if no prior sequence shares the same abstract definition. In that case, use `merge` instead — it handles mismatched definitions, removes empty gap paragraphs, and produces one continuous list.
+
 ### Insert content into a document (new or existing)
 
 Markdown insert creates block structure but uses default formatting. You MUST follow up with formatting so inserted content looks like it belongs in the document.

package/tools/system-prompt.md

@@ -164,6 +164,94 @@ Use preset "disc" for bullets, "decimal" for numbered. WARNING: the range conver
 
 3. To change a bullet list to numbered: `superdoc_list({action: "set_type", target: {kind: "block", nodeType: "listItem", nodeId: "<anyItemId>"}, kind: "ordered"})`
 
+### Add items to an existing list
+
+To add a new item adjacent to an existing list item, use `superdoc_list({action: "insert"})`, NOT `superdoc_create({action: "paragraph"})` — the latter creates a standalone paragraph that is not part of the list:
+
+```
+superdoc_get_content({action: "blocks"})  // find the listItem nodeId you want to insert next to
+superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}, position: "after", text: "New item text"})
+```
+
+**Level inheritance.** The new item inherits the target's nesting level. Insert after a level-0 item → new item is level 0. Insert after a level-2 item → new item is level 2. To change the level, chain `indent` / `outdent` / `set_level` on the nodeId returned in the insert response.
+
+**Use the nodeId from the response directly.** `superdoc_list({action: "insert"})` returns `{item: {nodeId: "<id>"}}` — that id is ready for subsequent `indent`, `outdent`, `set_level`, or text edits. You do NOT need to re-fetch blocks between the insert and the follow-up operation.
+
+### Add a sub-point under an existing item
+
+Insert a peer, then indent it one level:
+
+```
+// 1. Insert a peer item after the parent — new item is at the parent's level
+const resp = superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<parentItemId>"}, position: "after", text: "Sub-point"})
+
+// 2. Indent using the nodeId from resp.item.nodeId
+superdoc_list({action: "indent", target: {kind: "block", nodeType: "listItem", nodeId: "<resp.item.nodeId>"}})
+```
+
+### Build a nested list with mixed levels
+
+`lists.create` produces a flat list. Add nesting by chaining `insert` + `indent` / `set_level`, using the nodeId returned by each insert to target the next step:
+
+```
+// Starting point: a list item at level 0 ("Parent" with nodeId <parent>)
+
+// Sibling at level 0
+const r1 = superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<parent>"}, position: "after", text: "Sibling"})
+
+// Child at level 1 (insert after r1, then indent)
+const r2 = superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<r1.item.nodeId>"}, position: "after", text: "Child"})
+superdoc_list({action: "indent", target: {kind: "block", nodeType: "listItem", nodeId: "<r2.item.nodeId>"}})
+
+// Grandchild at level 3 (insert after r2, then jump to level 3 directly)
+const r3 = superdoc_list({action: "insert", target: {kind: "block", nodeType: "listItem", nodeId: "<r2.item.nodeId>"}, position: "after", text: "Deep"})
+superdoc_list({action: "set_level", target: {kind: "block", nodeType: "listItem", nodeId: "<r3.item.nodeId>"}, level: 3})
+```
+
+`indent` bumps the level by one (bounded 0–8). `set_level` jumps directly to any level 0–8. Markers update automatically based on the list's definition for each level (e.g. `1.` / `a.` / `i.` for an ordered list).
+
+### Merge two adjacent lists into one
+
+Use `merge` — it handles the common case where two ordered or bulleted lists sit next to each other and should become one continuous list. Absorbed items adopt the absorbing sequence's definition, and any empty paragraphs between the two lists are removed so numbering flows continuously.
+
+```
+superdoc_get_content({action: "blocks"})  // find a listItem in either sequence
+// To merge with the previous sequence:
+superdoc_list({action: "merge", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}, direction: "withPrevious"})
+// Or with the next sequence:
+superdoc_list({action: "merge", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}, direction: "withNext"})
+```
+
+### Split a list into two
+
+Use `split` to break one list into two independent lists at a specific item. The target and everything after become a new sequence that restarts numbering at 1:
+
+```
+superdoc_list({action: "split", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}})
+```
+
+Pass `restartNumbering: false` if you want the new half to keep counting from where the original left off.
+
+### Restart numbering at a specific item
+
+For ordered lists. To make item N restart from a chosen number (commonly 1):
+
+```
+superdoc_list({action: "set_value", target: {kind: "block", nodeType: "listItem", nodeId: "<itemId>"}, value: 1})
+```
+
+Pass `value: null` to clear a previously-set restart override and let the item resume natural numbering.
+
+### Continue numbering across a break
+
+For ordered lists. When two sibling sequences should be numbered as one (e.g. numbering jumps back to 1 and you want it to continue from where the previous list left off), target the FIRST item of the second sequence:
+
+```
+superdoc_list({action: "continue_previous", target: {kind: "block", nodeType: "listItem", nodeId: "<firstItemOfSecondList>"}})
+```
+
+Fails with `NO_COMPATIBLE_PREVIOUS` or `INCOMPATIBLE_DEFINITIONS` if no prior sequence shares the same abstract definition. In that case, use `merge` instead — it handles mismatched definitions, removes empty gap paragraphs, and produces one continuous list.
+
 ### Insert content into a document (new or existing)
 
 Markdown insert creates block structure but uses default formatting. You MUST follow up with formatting so inserted content looks like it belongs in the document.

package/tools/tools-policy.json

@@ -39,5 +39,5 @@
       "mutates": true
     }
   ],
-  "contractHash": "5d8801b835a962bf9b7ed0586312e317d1d515dc58d3a5d8ec195a56bdf7c3d4"
+  "contractHash": "0bb50c2977e652d32a4c3dd591c774e7d164c013b53f2c951de8573911ecdef6"
 }