chore: more document-api standardization and clean up

apps/docs/document-api/reference/_generated-manifest.json

@@ -119,5 +119,5 @@
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "71719d809aa97aaaf7d9200dedd1edf47dc16486b208b473cc009257667bed77"
+  "sourceHash": "ef0d931b0ccec18b0cc91efee5ed117a0d3328adc8406faaab4119e2f07b2ca5"
 }

apps/docs/document-api/reference/comments/create.mdx

@@ -72,7 +72,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
 

apps/docs/document-api/reference/comments/delete.mdx

@@ -61,7 +61,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 
 ## Non-applied failure codes

apps/docs/document-api/reference/comments/list.mdx

@@ -78,7 +78,7 @@ description: Reference for comments.list
 
 ## Pre-apply throws
 
-- None
+- `INVALID_INPUT`
 
 ## Non-applied failure codes
 

apps/docs/document-api/reference/comments/patch.mdx

@@ -74,7 +74,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
 - `INVALID_INPUT`

apps/docs/document-api/reference/create/heading.mdx

@@ -73,8 +73,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `COMMAND_UNAVAILABLE`
-- `TRACK_CHANGE_COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
 - `AMBIGUOUS_TARGET`

apps/docs/document-api/reference/create/paragraph.mdx

@@ -71,8 +71,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `COMMAND_UNAVAILABLE`
-- `TRACK_CHANGE_COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
 - `AMBIGUOUS_TARGET`

apps/docs/document-api/reference/delete.mdx

@@ -91,7 +91,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `TRACK_CHANGE_COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
 

apps/docs/document-api/reference/find.mdx

@@ -132,7 +132,8 @@ description: Reference for find
 
 ## Pre-apply throws
 
-- None
+- `CAPABILITY_UNAVAILABLE`
+- `INVALID_INPUT`
 
 ## Non-applied failure codes
 

apps/docs/document-api/reference/format/apply.mdx

@@ -96,8 +96,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `COMMAND_UNAVAILABLE`
-- `TRACK_CHANGE_COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
 - `INVALID_INPUT`

apps/docs/document-api/reference/insert.mdx

@@ -93,7 +93,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `TRACK_CHANGE_COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
 

apps/docs/document-api/reference/lists/exit.mdx

@@ -56,8 +56,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `COMMAND_UNAVAILABLE`
-- `TRACK_CHANGE_COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
 

apps/docs/document-api/reference/lists/indent.mdx

@@ -56,8 +56,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `COMMAND_UNAVAILABLE`
-- `TRACK_CHANGE_COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
 

apps/docs/document-api/reference/lists/insert.mdx

@@ -75,8 +75,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `COMMAND_UNAVAILABLE`
-- `TRACK_CHANGE_COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
 

apps/docs/document-api/reference/lists/list.mdx

@@ -85,6 +85,8 @@ description: Reference for lists.list
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
+- `INVALID_TARGET`
+- `INVALID_INPUT`
 
 ## Non-applied failure codes
 

apps/docs/document-api/reference/lists/outdent.mdx

@@ -56,8 +56,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `COMMAND_UNAVAILABLE`
-- `TRACK_CHANGE_COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
 

apps/docs/document-api/reference/lists/restart.mdx

@@ -56,8 +56,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `COMMAND_UNAVAILABLE`
-- `TRACK_CHANGE_COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
 

apps/docs/document-api/reference/lists/set-type.mdx

@@ -58,8 +58,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `COMMAND_UNAVAILABLE`
-- `TRACK_CHANGE_COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
 

apps/docs/document-api/reference/replace.mdx

@@ -93,7 +93,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `TRACK_CHANGE_COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_TARGET`
 

apps/docs/document-api/reference/track-changes/decide.mdx

@@ -65,7 +65,6 @@ _No fields._
 ## Pre-apply throws
 
 - `TARGET_NOT_FOUND`
-- `COMMAND_UNAVAILABLE`
 - `CAPABILITY_UNAVAILABLE`
 - `INVALID_INPUT`
 - `INVALID_TARGET`

apps/docs/document-api/reference/track-changes/list.mdx

@@ -78,7 +78,7 @@ description: Reference for trackChanges.list
 
 ## Pre-apply throws
 
-- None
+- `INVALID_INPUT`
 
 ## Non-applied failure codes
 

apps/mcp/src/__tests__/protocol.test.ts

@@ -155,15 +155,16 @@ describe('MCP protocol integration', () => {
     expect(textContent(result)).toContain('No open session');
   });
 
-  it('returns isError for invalid file path', async () => {
+  it('creates a blank document when file does not exist', async () => {
     await ready;
 
     const result = await client.callTool({
       name: 'superdoc_open',
       arguments: { path: '/nonexistent/file.docx' },
     });
 
-    expect(result).toHaveProperty('isError', true);
-    expect(textContent(result)).toContain('Failed to open document');
+    expect(result).not.toHaveProperty('isError');
+    const body = JSON.parse(textContent(result));
+    expect(body).toHaveProperty('session_id');
   });
 });

apps/mcp/src/tools/comments.ts

@@ -8,14 +8,14 @@ export function registerCommentTools(server: McpServer, sessions: SessionManager
     {
       title: 'Add Comment',
       description:
-        'Add a comment anchored to a text range in the document. Use superdoc_find with a text pattern first, then pass a TextAddress from context[].textRanges as the target.',
+        'Add a comment anchored to a text range in the document. Use superdoc_find with a text pattern first, then pass a TextAddress from items[].context.textRanges as the target.',
       inputSchema: {
         session_id: z.string().describe('Session ID from superdoc_open.'),
         text: z.string().describe('The comment text (question, concern, or feedback).'),
         target: z
           .string()
           .describe(
-            'JSON-encoded TextAddress: {"kind":"text","blockId":"...","range":{"start":N,"end":N}}. Get this from superdoc_find context[].textRanges, NOT from matches[].',
+            'JSON-encoded TextAddress: {"kind":"text","blockId":"...","range":{"start":N,"end":N}}. Get this from superdoc_find items[].context.textRanges.',
           ),
       },
       annotations: { readOnlyHint: false },

apps/mcp/src/tools/format.ts

@@ -16,14 +16,14 @@ export function registerFormatTools(server: McpServer, sessions: SessionManager)
     {
       title: 'Format Text',
       description:
-        "Apply formatting on a text range. Use superdoc_find with a text pattern first, then pass a TextAddress from the result's context[].textRanges as the target. Set suggest=true to format as a tracked change (suggestion).",
+        'Apply formatting on a text range. Use superdoc_find with a text pattern first, then pass a TextAddress from items[].context.textRanges as the target. Set suggest=true to format as a tracked change (suggestion).',
       inputSchema: {
         session_id: z.string().describe('Session ID from superdoc_open.'),
         style: z.enum(STYLES).describe('The formatting style to apply.'),
         target: z
           .string()
           .describe(
-            'JSON-encoded TextAddress: {"kind":"text","blockId":"...","range":{"start":N,"end":N}}. Get this from superdoc_find context[].textRanges, NOT from matches[].',
+            'JSON-encoded TextAddress: {"kind":"text","blockId":"...","range":{"start":N,"end":N}}. Get this from superdoc_find items[].context.textRanges.',
           ),
         suggest: z
           .boolean()

apps/mcp/src/tools/mutation.ts

@@ -12,14 +12,14 @@ export function registerMutationTools(server: McpServer, sessions: SessionManage
     {
       title: 'Insert Text',
       description:
-        "Insert text at a target position in the document. Use superdoc_find first, then pass a TextAddress from the result's context[].textRanges as the target. Set suggest=true to insert as a tracked change (suggestion) instead of a direct edit.",
+        'Insert text at a target position in the document. Use superdoc_find first, then pass a TextAddress from items[].context.textRanges as the target. Set suggest=true to insert as a tracked change (suggestion) instead of a direct edit.',
       inputSchema: {
         session_id: z.string().describe('Session ID from superdoc_open.'),
         text: z.string().describe('The text content to insert.'),
         target: z
           .string()
           .describe(
-            'JSON-encoded TextAddress: {"kind":"text","blockId":"...","range":{"start":N,"end":N}}. Get this from superdoc_find context[].textRanges, NOT from matches[].',
+            'JSON-encoded TextAddress: {"kind":"text","blockId":"...","range":{"start":N,"end":N}}. Get this from superdoc_find items[].context.textRanges.',
           ),
         suggest: z
           .boolean()
@@ -56,14 +56,14 @@ export function registerMutationTools(server: McpServer, sessions: SessionManage
     {
       title: 'Replace Text',
       description:
-        "Replace content at a target range with new text. Use superdoc_find with a text pattern first, then pass a TextAddress from the result's context[].textRanges as the target. Set suggest=true to make the replacement a tracked change (suggestion).",
+        'Replace content at a target range with new text. Use superdoc_find with a text pattern first, then pass a TextAddress from items[].context.textRanges as the target. Set suggest=true to make the replacement a tracked change (suggestion).',
       inputSchema: {
         session_id: z.string().describe('Session ID from superdoc_open.'),
         text: z.string().describe('The replacement text.'),
         target: z
           .string()
           .describe(
-            'JSON-encoded TextAddress: {"kind":"text","blockId":"...","range":{"start":N,"end":N}}. Get this from superdoc_find context[].textRanges, NOT from matches[].',
+            'JSON-encoded TextAddress: {"kind":"text","blockId":"...","range":{"start":N,"end":N}}. Get this from superdoc_find items[].context.textRanges.',
           ),
         suggest: z
           .boolean()
@@ -100,13 +100,13 @@ export function registerMutationTools(server: McpServer, sessions: SessionManage
     {
       title: 'Delete Content',
       description:
-        "Delete content at a target range. Use superdoc_find with a text pattern first, then pass a TextAddress from the result's context[].textRanges as the target. Set suggest=true to delete as a tracked change (suggestion).",
+        'Delete content at a target range. Use superdoc_find with a text pattern first, then pass a TextAddress from items[].context.textRanges as the target. Set suggest=true to delete as a tracked change (suggestion).',
       inputSchema: {
         session_id: z.string().describe('Session ID from superdoc_open.'),
         target: z
           .string()
           .describe(
-            'JSON-encoded TextAddress: {"kind":"text","blockId":"...","range":{"start":N,"end":N}}. Get this from superdoc_find context[].textRanges, NOT from matches[].',
+            'JSON-encoded TextAddress: {"kind":"text","blockId":"...","range":{"start":N,"end":N}}. Get this from superdoc_find items[].context.textRanges.',
           ),
         suggest: z
           .boolean()

apps/mcp/src/tools/query.ts

@@ -8,7 +8,7 @@ export function registerQueryTools(server: McpServer, sessions: SessionManager):
     {
       title: 'Find in Document',
       description:
-        'Search the document for nodes matching a type, text pattern, or both. For text searches, the result includes context[].textRanges — these are the TextAddress objects you pass as "target" to replace/insert/delete/format tools. Do NOT use matches[] as mutation targets (those are block addresses).',
+        'Search the document for nodes matching a type, text pattern, or both. For text searches, each item in items[] includes context.textRanges — these are the TextAddress objects you pass as "target" to replace/insert/delete/format tools.',
       inputSchema: {
         session_id: z.string().describe('Session ID from superdoc_open.'),
         type: z.string().optional().describe('Node type to filter by (e.g. "heading", "paragraph", "table", "image").'),

packages/document-api/scripts/check-overview-alignment.ts

@@ -42,15 +42,15 @@ const REQUIRED_PATTERNS = [
 
 const FORBIDDEN_PATTERNS = [
   {
-    label: 'legacy placeholder query API',
+    label: 'removed placeholder query API',
     pattern: /\bdoc\.query\s*\(/,
   },
   {
-    label: 'legacy placeholder table API',
+    label: 'removed placeholder table API',
     pattern: /\bdoc\.table\s*\(/,
   },
   {
-    label: 'legacy field-annotation selector example',
+    label: 'removed field-annotation selector example',
     pattern: /field-annotation/i,
   },
   {

packages/document-api/scripts/lib/contract-output-artifacts.ts

@@ -103,8 +103,6 @@ export function buildToolManifestArtifacts(): GeneratedFile[] {
 
 const DEFAULT_REMEDIATION_BY_CODE: Record<string, string> = {
   TARGET_NOT_FOUND: 'Refresh targets via find/get operations and retry with a fresh address or ID.',
-  COMMAND_UNAVAILABLE: 'Call capabilities.get and branch to a fallback when operation availability is false.',
-  TRACK_CHANGE_COMMAND_UNAVAILABLE: 'Verify track-changes support via capabilities.get before requesting tracked mode.',
   CAPABILITY_UNAVAILABLE: 'Check runtime capabilities and switch to supported mode or operation.',
   INVALID_TARGET: 'Confirm the target shape and operation compatibility, then retry with a valid target.',
   NO_OP: 'Treat as idempotent no-op and avoid retry loops unless inputs change.',