gogcli-mcp-docs 4.2.4 → 4.3.0

package/tests/tools/docs-extra.test.ts

@@ -3,6 +3,7 @@ import { registerExtraDocsTools } from '../../src/tools/docs-extra.js';
 import * as lib from '../../../gogcli-mcp/src/lib.js';
 import { createTestHarness } from '@chrischall/mcp-utils/test';
 import { rawTextResult } from '@chrischall/mcp-utils';
+import { pos } from '../../../gogcli-mcp/src/argv.js';
 
 vi.mock('../../../gogcli-mcp/src/lib.js', async (importOriginal) => {
   const actual = await importOriginal<typeof lib>();
@@ -23,7 +24,7 @@ describe('gog_docs_copy', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_copy', { docId: 'abc', title: 'My Copy' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'copy', 'abc', 'My Copy'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'copy', pos('abc'), pos('My Copy')], { account: undefined });
   });
 
   it('includes --parent when provided', async () => {
@@ -31,7 +32,7 @@ describe('gog_docs_copy', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_copy', { docId: 'abc', title: 'Copy', parent: 'folder123' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'copy', 'abc', 'Copy', '--parent=folder123'],
+      ['docs', 'copy', pos('abc'), pos('Copy'), '--parent=folder123'],
       { account: undefined },
     );
   });
@@ -40,14 +41,14 @@ describe('gog_docs_copy', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_copy', { docId: 'abc', title: 'Copy' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'copy', 'abc', 'Copy'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'copy', pos('abc'), pos('Copy')], { account: undefined });
   });
 
   it('forwards account override', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_copy', { docId: 'abc', title: 'Copy', account: 'other@gmail.com' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'copy', 'abc', 'Copy'], { account: 'other@gmail.com' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'copy', pos('abc'), pos('Copy')], { account: 'other@gmail.com' });
   });
 });
 
@@ -59,7 +60,7 @@ describe('gog_docs_delete', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_delete', { docId: 'abc', start: 5, end: 10 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'delete', '--start=5', '--end=10', 'abc'],
+      ['docs', 'delete', '--start=5', '--end=10', pos('abc')],
       { account: undefined },
     );
   });
@@ -70,7 +71,7 @@ describe('gog_docs_delete', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_delete', { docId: 'abc', at: 'TODO', occurrence: 2, matchCase: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'delete', 'abc', '--at=TODO', '--occurrence=2', '--match-case'],
+      ['docs', 'delete', pos('abc'), '--at=TODO', '--occurrence=2', '--match-case'],
       { account: undefined },
     );
   });
@@ -80,7 +81,7 @@ describe('gog_docs_delete', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_delete', { docId: 'abc', start: 1, end: 5, tabId: 'tab1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'delete', '--start=1', '--end=5', 'abc', '--tab-id=tab1'],
+      ['docs', 'delete', '--start=1', '--end=5', pos('abc'), '--tab-id=tab1'],
       { account: undefined },
     );
   });
@@ -90,7 +91,7 @@ describe('gog_docs_delete', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_delete', { docId: 'abc', start: 1, end: 5 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'delete', '--start=1', '--end=5', 'abc'],
+      ['docs', 'delete', '--start=1', '--end=5', pos('abc')],
       { account: undefined },
     );
   });
@@ -104,7 +105,7 @@ describe('gog_docs_edit', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_edit', { docId: 'abc', find: 'old', replace: 'new' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'edit', 'abc', 'old', 'new'],
+      ['docs', 'edit', pos('abc'), pos('old'), pos('new')],
       { account: undefined },
     );
   });
@@ -114,7 +115,7 @@ describe('gog_docs_edit', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_edit', { docId: 'abc', find: 'old', replace: 'new', matchCase: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'edit', 'abc', 'old', 'new', '--match-case'],
+      ['docs', 'edit', pos('abc'), pos('old'), pos('new'), '--match-case'],
       { account: undefined },
     );
   });
@@ -124,7 +125,7 @@ describe('gog_docs_edit', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_edit', { docId: 'abc', find: 'old', replace: 'new', matchCase: false });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'edit', 'abc', 'old', 'new'],
+      ['docs', 'edit', pos('abc'), pos('old'), pos('new')],
       { account: undefined },
     );
   });
@@ -137,7 +138,7 @@ describe('gog_docs_export', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_export', { docId: 'abc' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'export', 'abc'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'export', pos('abc')], { account: undefined });
   });
 
   it('includes --format when provided', async () => {
@@ -145,7 +146,7 @@ describe('gog_docs_export', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_export', { docId: 'abc', format: 'html' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'export', 'abc', '--format=html'],
+      ['docs', 'export', pos('abc'), '--format=html'],
       { account: undefined },
     );
   });
@@ -155,7 +156,7 @@ describe('gog_docs_export', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_export', { docId: 'abc', out: '/tmp/doc.pdf' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'export', 'abc', '--out=/tmp/doc.pdf'],
+      ['docs', 'export', pos('abc'), '--out=/tmp/doc.pdf'],
       { account: undefined },
     );
   });
@@ -165,7 +166,7 @@ describe('gog_docs_export', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_export', { docId: 'abc', format: 'txt', out: '/tmp/doc.txt' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'export', 'abc', '--format=txt', '--out=/tmp/doc.txt'],
+      ['docs', 'export', pos('abc'), '--format=txt', '--out=/tmp/doc.txt'],
       { account: undefined },
     );
   });
@@ -174,7 +175,7 @@ describe('gog_docs_export', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_export', { docId: 'abc' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'export', 'abc'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'export', pos('abc')], { account: undefined });
   });
 
   it('includes --overwrite when requested', async () => {
@@ -182,7 +183,7 @@ describe('gog_docs_export', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_export', { docId: 'abc', out: '/tmp/doc.pdf', overwrite: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'export', 'abc', '--out=/tmp/doc.pdf', '--overwrite'],
+      ['docs', 'export', pos('abc'), '--out=/tmp/doc.pdf', '--overwrite'],
       { account: undefined },
     );
   });
@@ -196,7 +197,7 @@ describe('gog_docs_insert', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert', { docId: 'abc', content: 'Hello world' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert', 'abc', 'Hello world'],
+      ['docs', 'insert', pos('abc'), pos('Hello world')],
       { account: undefined },
     );
   });
@@ -207,7 +208,7 @@ describe('gog_docs_insert', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert', { docId: 'abc', content: 'X', at: 'HERE', occurrence: 3, matchCase: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert', 'abc', 'X', '--at=HERE', '--occurrence=3', '--match-case'],
+      ['docs', 'insert', pos('abc'), pos('X'), '--at=HERE', '--occurrence=3', '--match-case'],
       { account: undefined },
     );
   });
@@ -217,7 +218,7 @@ describe('gog_docs_insert', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert', { docId: 'abc', content: 'text', index: 5 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert', 'abc', 'text', '--index=5'],
+      ['docs', 'insert', pos('abc'), pos('text'), '--index=5'],
       { account: undefined },
     );
   });
@@ -227,7 +228,7 @@ describe('gog_docs_insert', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert', { docId: 'abc', content: 'text', index: 0 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert', 'abc', 'text', '--index=0'],
+      ['docs', 'insert', pos('abc'), pos('text'), '--index=0'],
       { account: undefined },
     );
   });
@@ -237,7 +238,7 @@ describe('gog_docs_insert', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert', { docId: 'abc', file: '/tmp/text.txt' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert', 'abc', '--file=/tmp/text.txt'],
+      ['docs', 'insert', pos('abc'), '--file=/tmp/text.txt'],
       { account: undefined },
     );
   });
@@ -247,7 +248,7 @@ describe('gog_docs_insert', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert', { docId: 'abc', content: 'hi', tabId: 'tab1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert', 'abc', 'hi', '--tab-id=tab1'],
+      ['docs', 'insert', pos('abc'), pos('hi'), '--tab-id=tab1'],
       { account: undefined },
     );
   });
@@ -256,7 +257,7 @@ describe('gog_docs_insert', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert', { docId: 'abc' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'insert', 'abc'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'insert', pos('abc')], { account: undefined });
   });
 });
 
@@ -267,14 +268,14 @@ describe('gog_docs_list_tabs', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_list_tabs', { docId: 'abc' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'list-tabs', 'abc'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'list-tabs', pos('abc')], { account: undefined });
   });
 
   it('forwards account override', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_list_tabs', { docId: 'abc', account: 'other@gmail.com' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'list-tabs', 'abc'], { account: 'other@gmail.com' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'list-tabs', pos('abc')], { account: 'other@gmail.com' });
   });
 });
 
@@ -286,7 +287,7 @@ describe('gog_docs_sed', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_sed', { docId: 'abc', expression: 's/old/new/g' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'sed', 'abc', 's/old/new/g'],
+      ['docs', 'sed', pos('abc'), pos('s/old/new/g')],
       { account: undefined },
     );
   });
@@ -299,7 +300,7 @@ describe('gog_docs_sed', () => {
       expressions: ['s/foo/bar/g', 's/baz/qux/g'],
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'sed', 'abc', '--expressions=s/foo/bar/g', '--expressions=s/baz/qux/g'],
+      ['docs', 'sed', pos('abc'), '--expressions=s/foo/bar/g', '--expressions=s/baz/qux/g'],
       { account: undefined },
     );
   });
@@ -309,7 +310,7 @@ describe('gog_docs_sed', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_sed', { docId: 'abc', file: '/tmp/sed.txt' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'sed', 'abc', '--file=/tmp/sed.txt'],
+      ['docs', 'sed', pos('abc'), '--file=/tmp/sed.txt'],
       { account: undefined },
     );
   });
@@ -319,7 +320,7 @@ describe('gog_docs_sed', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_sed', { docId: 'abc', expression: 's/a/b/', tab: 'Notes' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'sed', 'abc', 's/a/b/', '--tab=Notes'],
+      ['docs', 'sed', pos('abc'), pos('s/a/b/'), '--tab=Notes'],
       { account: undefined },
     );
   });
@@ -328,7 +329,7 @@ describe('gog_docs_sed', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_sed', { docId: 'abc' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'sed', 'abc'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'sed', pos('abc')], { account: undefined });
   });
 });
 
@@ -340,7 +341,7 @@ describe('gog_docs_update', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_update', { docId: 'abc', text: 'Hello' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'update', 'abc', '--text=Hello'],
+      ['docs', 'update', pos('abc'), '--text=Hello'],
       { account: undefined },
     );
   });
@@ -351,7 +352,7 @@ describe('gog_docs_update', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_update', { docId: 'abc', text: 'New', at: 'OLD', occurrence: 1, matchCase: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'update', 'abc', '--text=New', '--at=OLD', '--occurrence=1', '--match-case'],
+      ['docs', 'update', pos('abc'), '--text=New', '--at=OLD', '--occurrence=1', '--match-case'],
       { account: undefined },
     );
   });
@@ -361,7 +362,7 @@ describe('gog_docs_update', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_update', { docId: 'abc', file: '/tmp/content.txt' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'update', 'abc', '--file=/tmp/content.txt'],
+      ['docs', 'update', pos('abc'), '--file=/tmp/content.txt'],
       { account: undefined },
     );
   });
@@ -371,7 +372,7 @@ describe('gog_docs_update', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_update', { docId: 'abc', text: 'hi', index: 10 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'update', 'abc', '--text=hi', '--index=10'],
+      ['docs', 'update', pos('abc'), '--text=hi', '--index=10'],
       { account: undefined },
     );
   });
@@ -381,7 +382,7 @@ describe('gog_docs_update', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_update', { docId: 'abc', text: 'hi', index: 0 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'update', 'abc', '--text=hi', '--index=0'],
+      ['docs', 'update', pos('abc'), '--text=hi', '--index=0'],
       { account: undefined },
     );
   });
@@ -391,7 +392,7 @@ describe('gog_docs_update', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_update', { docId: 'abc', text: 'hi', tabId: 'tab1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'update', 'abc', '--text=hi', '--tab-id=tab1'],
+      ['docs', 'update', pos('abc'), '--text=hi', '--tab-id=tab1'],
       { account: undefined },
     );
   });
@@ -401,7 +402,7 @@ describe('gog_docs_update', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_update', { docId: 'abc', pageless: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'update', 'abc', '--pageless'],
+      ['docs', 'update', pos('abc'), '--pageless'],
       { account: undefined },
     );
   });
@@ -411,7 +412,7 @@ describe('gog_docs_update', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_update', { docId: 'abc', pageless: false });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'update', 'abc'],
+      ['docs', 'update', pos('abc')],
       { account: undefined },
     );
   });
@@ -420,7 +421,7 @@ describe('gog_docs_update', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_update', { docId: 'abc' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'update', 'abc'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'update', pos('abc')], { account: undefined });
   });
 
   it('includes --replace-range when provided', async () => {
@@ -428,7 +429,7 @@ describe('gog_docs_update', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_update', { docId: 'abc', text: 'new', replaceRange: '25:40' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'update', 'abc', '--text=new', '--replace-range=25:40'],
+      ['docs', 'update', pos('abc'), '--text=new', '--replace-range=25:40'],
       { account: undefined },
     );
   });
@@ -438,7 +439,7 @@ describe('gog_docs_update', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_update', { docId: 'abc', text: '# Heading', markdown: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'update', 'abc', '--text=# Heading', '--markdown'],
+      ['docs', 'update', pos('abc'), '--text=# Heading', '--markdown'],
       { account: undefined },
     );
   });
@@ -448,7 +449,7 @@ describe('gog_docs_update', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_update', { docId: 'abc', text: 'hi', markdown: false });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'update', 'abc', '--text=hi'],
+      ['docs', 'update', pos('abc'), '--text=hi'],
       { account: undefined },
     );
   });
@@ -461,7 +462,7 @@ describe('gog_docs_comments_list', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_list', { docId: 'abc' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'list', 'abc'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'list', pos('abc')], { account: undefined });
   });
 
   it('includes --include-resolved when set', async () => {
@@ -469,7 +470,7 @@ describe('gog_docs_comments_list', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_list', { docId: 'abc', includeResolved: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'list', 'abc', '--include-resolved'],
+      ['docs', 'comments', 'list', pos('abc'), '--include-resolved'],
       { account: undefined },
     );
   });
@@ -478,7 +479,7 @@ describe('gog_docs_comments_list', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_list', { docId: 'abc', includeResolved: false });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'list', 'abc'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'list', pos('abc')], { account: undefined });
   });
 
   it('forwards account override', async () => {
@@ -486,7 +487,7 @@ describe('gog_docs_comments_list', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_list', { docId: 'abc', account: 'other@gmail.com' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'list', 'abc'],
+      ['docs', 'comments', 'list', pos('abc')],
       { account: 'other@gmail.com' },
     );
   });
@@ -499,7 +500,7 @@ describe('gog_docs_comments_list', () => {
       docId: 'abc', includeResolved: true, since: '2026-06-01T00:00:00Z', max: 10, page: 'tok', all: true,
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'list', 'abc', '--include-resolved', '--since=2026-06-01T00:00:00Z', '--max=10', '--page=tok', '--all'],
+      ['docs', 'comments', 'list', pos('abc'), '--include-resolved', '--since=2026-06-01T00:00:00Z', '--max=10', '--page=tok', '--all'],
       { account: undefined },
     );
   });
@@ -513,7 +514,7 @@ describe('gog_docs_comments_list', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_list', { docId: 'abc', locate: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'list', 'abc', '--locate'],
+      ['docs', 'comments', 'list', pos('abc'), '--locate'],
       { account: undefined },
     );
   });
@@ -522,7 +523,7 @@ describe('gog_docs_comments_list', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_list', { docId: 'abc', locate: false });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'list', 'abc'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'list', pos('abc')], { account: undefined });
   });
 
   it('includes --tab, which gog treats as implying --locate', async () => {
@@ -530,7 +531,7 @@ describe('gog_docs_comments_list', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_list', { docId: 'abc', tab: 'Notes' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'list', 'abc', '--tab=Notes'],
+      ['docs', 'comments', 'list', pos('abc'), '--tab=Notes'],
       { account: undefined },
     );
   });
@@ -541,7 +542,7 @@ describe('gog_docs_comments_list', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_list', { docId: 'abc', tab: '' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'list', 'abc'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'list', pos('abc')], { account: undefined });
   });
 
   it('combines --locate and --tab with the existing filters and pagination', async () => {
@@ -553,7 +554,7 @@ describe('gog_docs_comments_list', () => {
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
       [
-        'docs', 'comments', 'list', 'abc',
+        'docs', 'comments', 'list', pos('abc'),
         '--include-resolved',
         '--since=2026-06-01T00:00:00Z',
         '--locate',
@@ -589,7 +590,7 @@ describe('gog_docs_table_column_width', () => {
       docId: 'd1', col: 2, width: 120, tableIndex: 1, tab: 'Body',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'table-column-width', 'd1', '--col=2', '--width=120', '--table-index=1', '--tab=Body'],
+      ['docs', 'table-column-width', pos('d1'), '--col=2', '--width=120', '--table-index=1', '--tab=Body'],
       { account: undefined },
     );
   });
@@ -599,7 +600,7 @@ describe('gog_docs_table_column_width', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_table_column_width', { docId: 'd1', evenlyDistributed: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'table-column-width', 'd1', '--evenly-distributed'],
+      ['docs', 'table-column-width', pos('d1'), '--evenly-distributed'],
       { account: undefined },
     );
   });
@@ -609,7 +610,7 @@ describe('gog_docs_table_column_width', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_table_column_width', { docId: 'd1', col: 1, width: 80, account: 'other@gmail.com' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'table-column-width', 'd1', '--col=1', '--width=80'],
+      ['docs', 'table-column-width', pos('d1'), '--col=1', '--width=80'],
       { account: 'other@gmail.com' },
     );
   });
@@ -621,7 +622,7 @@ describe('gog_docs_find_range', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_find_range', { docId: 'd1', text: 'hello' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'find-range', 'd1', 'hello'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'find-range', pos('d1'), pos('hello')], { account: undefined });
   });
 
   it('passes all match flags', async () => {
@@ -631,7 +632,7 @@ describe('gog_docs_find_range', () => {
       docId: 'd1', text: 'hello', occurrence: 2, matchCase: true, normalizeWhitespace: true, all: true, failEmpty: true, tab: 'T',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'find-range', 'd1', 'hello', '--occurrence=2', '--match-case', '--normalize-whitespace', '--all', '--fail-empty', '--tab=T'],
+      ['docs', 'find-range', pos('d1'), pos('hello'), '--occurrence=2', '--match-case', '--normalize-whitespace', '--all', '--fail-empty', '--tab=T'],
       { account: undefined },
     );
   });
@@ -642,7 +643,7 @@ describe('gog_docs_comments_locate', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_locate', { docId: 'd1', commentId: 'c1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'locate', 'd1', 'c1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'locate', pos('d1'), pos('c1')], { account: undefined });
   });
 
   it('passes match flags', async () => {
@@ -650,7 +651,7 @@ describe('gog_docs_comments_locate', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_locate', { docId: 'd1', commentId: 'c1', matchCase: true, normalizeWhitespace: true, tab: 'T' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'locate', 'd1', 'c1', '--match-case', '--normalize-whitespace', '--tab=T'],
+      ['docs', 'comments', 'locate', pos('d1'), pos('c1'), '--match-case', '--normalize-whitespace', '--tab=T'],
       { account: undefined },
     );
   });
@@ -661,7 +662,7 @@ describe('gog_docs_comments_get', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_get', { docId: 'abc', commentId: 'c1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'get', 'abc', 'c1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'get', pos('abc'), pos('c1')], { account: undefined });
   });
 });
 
@@ -671,7 +672,7 @@ describe('gog_docs_comments_add', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_add', { docId: 'abc', content: 'Please review' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'add', 'abc', 'Please review'],
+      ['docs', 'comments', 'add', pos('abc'), pos('Please review')],
       { account: undefined },
     );
   });
@@ -683,7 +684,7 @@ describe('gog_docs_comments_add', () => {
       docId: 'abc', content: 'Typo here', quoted: 'teh',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'add', 'abc', 'Typo here', '--quoted=teh'],
+      ['docs', 'comments', 'add', pos('abc'), pos('Typo here'), '--quoted=teh'],
       { account: undefined },
     );
   });
@@ -693,7 +694,7 @@ describe('gog_docs_comments_add', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_add', { docId: 'abc', content: 'Nice' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'add', 'abc', 'Nice'],
+      ['docs', 'comments', 'add', pos('abc'), pos('Nice')],
       { account: undefined },
     );
   });
@@ -705,7 +706,7 @@ describe('gog_docs_comments_reply', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_reply', { docId: 'abc', commentId: 'c1', content: 'Done' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'reply', 'abc', 'c1', 'Done'],
+      ['docs', 'comments', 'reply', pos('abc'), pos('c1'), pos('Done')],
       { account: undefined },
     );
   });
@@ -717,7 +718,7 @@ describe('gog_docs_comments_resolve', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_resolve', { docId: 'abc', commentId: 'c1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'resolve', 'abc', 'c1'],
+      ['docs', 'comments', 'resolve', pos('abc'), pos('c1')],
       { account: undefined },
     );
   });
@@ -729,7 +730,7 @@ describe('gog_docs_comments_resolve', () => {
       docId: 'abc', commentId: 'c1', message: 'Fixed in v2',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'resolve', 'abc', 'c1', '--message=Fixed in v2'],
+      ['docs', 'comments', 'resolve', pos('abc'), pos('c1'), '--message=Fixed in v2'],
       { account: undefined },
     );
   });
@@ -739,7 +740,7 @@ describe('gog_docs_comments_resolve', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_resolve', { docId: 'abc', commentId: 'c1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'resolve', 'abc', 'c1'],
+      ['docs', 'comments', 'resolve', pos('abc'), pos('c1')],
       { account: undefined },
     );
   });
@@ -751,7 +752,7 @@ describe('gog_docs_comments_delete', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_delete', { docId: 'abc', commentId: 'c1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'delete', 'abc', 'c1', '--force'],
+      ['docs', 'comments', 'delete', pos('abc'), pos('c1'), '--force'],
       { account: undefined },
     );
   });
@@ -762,7 +763,7 @@ describe('gog_docs_trash', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_trash', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['drive', 'delete', 'd1', '--force'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['drive', 'delete', pos('d1'), '--force'], { account: undefined });
   });
 });
 
@@ -772,7 +773,7 @@ describe('gog_docs_append', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_append', { docId: 'd1', text: 'Hello' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'write', 'd1', '--append', '--text=Hello'],
+      ['docs', 'write', pos('d1'), '--append', '--text=Hello'],
       { account: undefined },
     );
   });
@@ -784,7 +785,7 @@ describe('gog_docs_append', () => {
       docId: 'd1', file: '/tmp/section.md', markdown: true, tab: 'Notes',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'write', 'd1', '--append', '--file=/tmp/section.md', '--markdown', '--tab=Notes'],
+      ['docs', 'write', pos('d1'), '--append', '--file=/tmp/section.md', '--markdown', '--tab=Notes'],
       { account: undefined },
     );
   });
@@ -817,14 +818,14 @@ describe('gog_docs_read', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('hello'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_read', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'cat', 'd1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'cat', pos('d1')], { account: undefined });
   });
 
   it('routes json format to gog docs raw --pretty', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_read', { docId: 'd1', format: 'json' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'raw', 'd1', '--pretty'], { account: undefined, lossless: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'raw', pos('d1'), '--pretty'], { account: undefined, lossless: true });
   });
 
   it('passes tab, allTabs, maxBytes in text mode', async () => {
@@ -832,7 +833,7 @@ describe('gog_docs_read', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_read', { docId: 'd1', tab: 'Section A', allTabs: true, maxBytes: 0 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'cat', 'd1', '--tab=Section A', '--all-tabs', '--max-bytes=0'],
+      ['docs', 'cat', pos('d1'), '--tab=Section A', '--all-tabs', '--max-bytes=0'],
       { account: undefined },
     );
   });
@@ -841,14 +842,14 @@ describe('gog_docs_read', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult(''));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_read', { docId: 'd1', chips: true });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'cat', 'd1', '--chips'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'cat', pos('d1'), '--chips'], { account: undefined });
   });
 
   it('ignores chips in json mode', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_read', { docId: 'd1', format: 'json', chips: true });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'raw', 'd1', '--pretty'], { account: undefined, lossless: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'raw', pos('d1'), '--pretty'], { account: undefined, lossless: true });
   });
 });
 
@@ -875,7 +876,7 @@ describe('gog_docs_format', () => {
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
       [
-        'docs', 'format', 'd1',
+        'docs', 'format', pos('d1'),
         '--match=Title',
         '--match-all',
         '--match-case',
@@ -906,7 +907,7 @@ describe('gog_docs_format', () => {
       noStrikethrough: true,
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'format', 'd1', '--no-bold', '--no-italic', '--no-underline', '--no-strikethrough'],
+      ['docs', 'format', pos('d1'), '--no-bold', '--no-italic', '--no-underline', '--no-strikethrough'],
       { account: undefined },
     );
   });
@@ -915,7 +916,7 @@ describe('gog_docs_format', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_format', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'format', 'd1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'format', pos('d1')], { account: undefined });
   });
 
   // gog 0.18.0
@@ -926,7 +927,7 @@ describe('gog_docs_format', () => {
       docId: 'd1', match: 'Intro', headingLevel: 1, namedStyle: 'HEADING_1',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'format', 'd1', '--match=Intro', '--heading-level=1', '--named-style=HEADING_1'],
+      ['docs', 'format', pos('d1'), '--match=Intro', '--heading-level=1', '--named-style=HEADING_1'],
       { account: undefined },
     );
   });
@@ -936,7 +937,7 @@ describe('gog_docs_format', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_format', { docId: 'd1', headingLevel: 0 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'format', 'd1', '--heading-level=0'],
+      ['docs', 'format', pos('d1'), '--heading-level=0'],
       { account: undefined },
     );
   });
@@ -947,7 +948,7 @@ describe('gog_docs_format', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_format', { docId: 'd1', match: 'snippet', code: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'format', 'd1', '--match=snippet', '--code'],
+      ['docs', 'format', pos('d1'), '--match=snippet', '--code'],
       { account: undefined },
     );
   });
@@ -958,7 +959,7 @@ describe('gog_docs_format', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_format', { docId: 'd1', match: 'see docs', link: 'https://example.com' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'format', 'd1', '--match=see docs', '--link=https://example.com'],
+      ['docs', 'format', pos('d1'), '--match=see docs', '--link=https://example.com'],
       { account: undefined },
     );
   });
@@ -968,7 +969,7 @@ describe('gog_docs_format', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_format', { docId: 'd1', match: 'linked', noLink: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'format', 'd1', '--match=linked', '--no-link'],
+      ['docs', 'format', pos('d1'), '--match=linked', '--no-link'],
       { account: undefined },
     );
   });
@@ -982,7 +983,7 @@ describe('gog_docs_insert_page_break', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_page_break', { docId: 'd1', index: 42 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-page-break', 'd1', '--index=42'],
+      ['docs', 'insert-page-break', pos('d1'), '--index=42'],
       { account: undefined },
     );
   });
@@ -993,7 +994,7 @@ describe('gog_docs_insert_page_break', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_page_break', { docId: 'd1', at: 'Chapter 2', occurrence: 1, matchCase: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-page-break', 'd1', '--at=Chapter 2', '--occurrence=1', '--match-case'],
+      ['docs', 'insert-page-break', pos('d1'), '--at=Chapter 2', '--occurrence=1', '--match-case'],
       { account: undefined },
     );
   });
@@ -1003,7 +1004,7 @@ describe('gog_docs_insert_page_break', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_page_break', { docId: 'd1', atEnd: true, tab: 'Body' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-page-break', 'd1', '--at-end', '--tab=Body'],
+      ['docs', 'insert-page-break', pos('d1'), '--at-end', '--tab=Body'],
       { account: undefined },
     );
   });
@@ -1013,7 +1014,7 @@ describe('gog_docs_insert_page_break', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_page_break', { docId: 'd1', index: 1 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-page-break', 'd1', '--index=1'],
+      ['docs', 'insert-page-break', pos('d1'), '--index=1'],
       { account: undefined },
     );
   });
@@ -1025,7 +1026,7 @@ describe('gog_docs_page_layout', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_page_layout', { docId: 'd1', layout: 'pages' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'page-layout', 'd1', '--layout=pages'],
+      ['docs', 'page-layout', pos('d1'), '--layout=pages'],
       { account: undefined },
     );
   });
@@ -1034,7 +1035,7 @@ describe('gog_docs_page_layout', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_page_layout', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'page-layout', 'd1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'page-layout', pos('d1')], { account: undefined });
   });
 
   it('passes --page-size, page dimensions and all margins', async () => {
@@ -1045,7 +1046,7 @@ describe('gog_docs_page_layout', () => {
       marginTop: '1in', marginBottom: '1in', marginLeft: '0.75in', marginRight: '0.75in',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'page-layout', 'd1', '--layout=pages', '--page-size=A4', '--page-width=8.5in',
+      ['docs', 'page-layout', pos('d1'), '--layout=pages', '--page-size=A4', '--page-width=8.5in',
         '--page-height=11in', '--margin-top=1in', '--margin-bottom=1in', '--margin-left=0.75in', '--margin-right=0.75in'],
       { account: undefined },
     );
@@ -1059,7 +1060,7 @@ describe('gog_docs_page_layout', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_page_layout', { docId: 'd1', pageSize: 'A3' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'page-layout', 'd1', '--page-size=A3'],
+      ['docs', 'page-layout', pos('d1'), '--page-size=A3'],
       { account: undefined },
     );
   });
@@ -1071,7 +1072,7 @@ describe('gog_docs_cell_update', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_cell_update', { docId: 'd1', row: 2, col: 3, content: 'hi' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'cell-update', 'd1', '--row=2', '--col=3', '--content=hi'],
+      ['docs', 'cell-update', pos('d1'), '--row=2', '--col=3', '--content=hi'],
       { account: undefined },
     );
   });
@@ -1084,7 +1085,7 @@ describe('gog_docs_cell_update', () => {
       format: 'plain', tableIndex: -1, tab: 'Tab2',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'cell-update', 'd1', '--row=1', '--col=1', '--content=',
+      ['docs', 'cell-update', pos('d1'), '--row=1', '--col=1', '--content=',
         '--append', '--format=plain', '--table-index=-1', '--tab=Tab2'],
       { account: undefined },
     );
@@ -1097,7 +1098,7 @@ describe('gog_docs_cell_update', () => {
       docId: 'd1', row: 1, col: 1, contentFile: '/tmp/c.md',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'cell-update', 'd1', '--row=1', '--col=1', '--content-file=/tmp/c.md'],
+      ['docs', 'cell-update', pos('d1'), '--row=1', '--col=1', '--content-file=/tmp/c.md'],
       { account: undefined },
     );
   });
@@ -1133,7 +1134,7 @@ describe('gog_docs_cell_update', () => {
     const big = 'c'.repeat(lib.PAYLOAD_INLINE_MAX + 1);
     await harness.callTool('gog_docs_cell_update', { docId: 'd1', row: 2, col: 3, content: big });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'cell-update', 'd1', '--row=2', '--col=3',
+      ['docs', 'cell-update', pos('d1'), '--row=2', '--col=3',
         { kind: 'file', flag: 'content-file', contents: big, ext: 'md' }],
       { account: undefined },
     );
@@ -1144,7 +1145,7 @@ describe('gog_docs_cell_update', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_cell_update', { docId: 'd1', row: 1, col: 2, account: 'a@b.com' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'cell-update', 'd1', '--row=1', '--col=2'],
+      ['docs', 'cell-update', pos('d1'), '--row=1', '--col=2'],
       { account: 'a@b.com' },
     );
   });
@@ -1156,7 +1157,7 @@ describe('gog_docs_cell_style', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_cell_style', { docId: 'd1', row: 0, col: 0 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'cell-style', 'd1', '--row=0', '--col=0'],
+      ['docs', 'cell-style', pos('d1'), '--row=0', '--col=0'],
       { account: undefined },
     );
   });
@@ -1169,7 +1170,7 @@ describe('gog_docs_cell_style', () => {
       textColor: '#111', bold: true, italic: true, underline: true, tableIndex: 1, tab: 'T',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'cell-style', 'd1', '--row=1', '--col=2', '--row-span=2', '--col-span=3',
+      ['docs', 'cell-style', pos('d1'), '--row=1', '--col=2', '--row-span=2', '--col-span=3',
         '--background-color=#eee', '--text-color=#111', '--bold', '--italic', '--underline',
         '--table-index=1', '--tab=T'],
       { account: undefined },
@@ -1181,7 +1182,7 @@ describe('gog_docs_cell_style', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_cell_style', { docId: 'd1', row: 0, col: 0, bold: false, italic: false, underline: false });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'cell-style', 'd1', '--row=0', '--col=0'],
+      ['docs', 'cell-style', pos('d1'), '--row=0', '--col=0'],
       { account: undefined },
     );
   });
@@ -1196,7 +1197,7 @@ describe('gog_docs_cell_style', () => {
       contentAlign: 'middle',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'cell-style', 'd1', '--row=0', '--col=0',
+      ['docs', 'cell-style', pos('d1'), '--row=0', '--col=0',
         '--border-all=1pt,#000,DASH', '--border-top=2pt', '--border-bottom=2pt', '--border-left=1pt', '--border-right=1pt',
         '--padding-all=5', '--padding-top=6pt', '--padding-bottom=6pt', '--padding-left=4mm', '--padding-right=4mm',
         '--content-align=middle'],
@@ -1211,7 +1212,7 @@ describe('gog_docs_insert_image', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_image', { docId: 'd1', file: '/tmp/pic.png' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-image', 'd1', '--file=/tmp/pic.png', '--force'],
+      ['docs', 'insert-image', pos('d1'), '--file=/tmp/pic.png', '--force'],
       { account: undefined },
     );
   });
@@ -1224,7 +1225,7 @@ describe('gog_docs_insert_image', () => {
       name: 'logo.png', parent: 'folder1', onRestricted: 'link', tab: 'T',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-image', 'd1', '--file=/tmp/pic.png', '--at={{logo}}', '--width=200',
+      ['docs', 'insert-image', pos('d1'), '--file=/tmp/pic.png', '--at={{logo}}', '--width=200',
         '--height=100', '--name=logo.png', '--parent=folder1', '--on-restricted=link', '--tab=T', '--force'],
       { account: undefined },
     );
@@ -1237,7 +1238,7 @@ describe('gog_docs_insert_image', () => {
       docId: 'd1', url: 'https://x.test/i.png', before: 'Intro', after: 'Outro',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-image', 'd1', '--url=https://x.test/i.png', '--before=Intro', '--after=Outro'],
+      ['docs', 'insert-image', pos('d1'), '--url=https://x.test/i.png', '--before=Intro', '--after=Outro'],
       { account: undefined },
     );
   });
@@ -1249,7 +1250,7 @@ describe('gog_docs_insert_person', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_person', { docId: 'd1', email: 'a@b.com' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-person', 'd1', '--email=a@b.com'],
+      ['docs', 'insert-person', pos('d1'), '--email=a@b.com'],
       { account: undefined },
     );
   });
@@ -1260,7 +1261,7 @@ describe('gog_docs_insert_person', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_person', { docId: 'd1', email: 'a@b.com', at: '@alice', occurrence: 1, matchCase: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-person', 'd1', '--email=a@b.com', '--at=@alice', '--occurrence=1', '--match-case'],
+      ['docs', 'insert-person', pos('d1'), '--email=a@b.com', '--at=@alice', '--occurrence=1', '--match-case'],
       { account: undefined },
     );
   });
@@ -1270,7 +1271,7 @@ describe('gog_docs_insert_person', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_person', { docId: 'd1', email: 'a@b.com', index: 0, atEnd: true, tab: 'T' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-person', 'd1', '--email=a@b.com', '--index=0', '--at-end', '--tab=T'],
+      ['docs', 'insert-person', pos('d1'), '--email=a@b.com', '--index=0', '--at-end', '--tab=T'],
       { account: undefined },
     );
   });
@@ -1281,7 +1282,7 @@ describe('gog_docs_insert_date_chip', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_date_chip', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'insert-date-chip', 'd1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'insert-date-chip', pos('d1')], { account: undefined });
   });
 
   it('passes --date, --format, --index and --at-end', async () => {
@@ -1289,7 +1290,7 @@ describe('gog_docs_insert_date_chip', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_date_chip', { docId: 'd1', date: '2026-06-01', format: 'iso', index: 5, atEnd: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-date-chip', 'd1', '--date=2026-06-01', '--format=iso', '--index=5', '--at-end'],
+      ['docs', 'insert-date-chip', pos('d1'), '--date=2026-06-01', '--format=iso', '--index=5', '--at-end'],
       { account: undefined },
     );
   });
@@ -1301,7 +1302,7 @@ describe('gog_docs_insert_table', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_table', { docId: 'd1', rows: 3, cols: 2 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-table', 'd1', '--rows=3', '--cols=2'],
+      ['docs', 'insert-table', pos('d1'), '--rows=3', '--cols=2'],
       { account: undefined },
     );
   });
@@ -1314,7 +1315,7 @@ describe('gog_docs_insert_table', () => {
       docId: 'd1', rows: 2, cols: 2, index: 10, valuesJson: vj, tab: 'Body',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-table', 'd1', '--rows=2', '--cols=2', '--index=10', `--values-json=${vj}`, '--tab=Body'],
+      ['docs', 'insert-table', pos('d1'), '--rows=2', '--cols=2', '--index=10', `--values-json=${vj}`, '--tab=Body'],
       { account: undefined },
     );
   });
@@ -1324,7 +1325,7 @@ describe('gog_docs_insert_table', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_table', { docId: 'd1', rows: 1, cols: 1, atEnd: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-table', 'd1', '--rows=1', '--cols=1', '--at-end'],
+      ['docs', 'insert-table', pos('d1'), '--rows=1', '--cols=1', '--at-end'],
       { account: undefined },
     );
   });
@@ -1336,7 +1337,7 @@ describe('gog_docs_comments_reopen', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_reopen', { docId: 'd1', commentId: 'c1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'reopen', 'd1', 'c1'],
+      ['docs', 'comments', 'reopen', pos('d1'), pos('c1')],
       { account: undefined },
     );
   });
@@ -1346,7 +1347,7 @@ describe('gog_docs_comments_reopen', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_comments_reopen', { docId: 'd1', commentId: 'c1', account: 'a@b.com' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'comments', 'reopen', 'd1', 'c1'],
+      ['docs', 'comments', 'reopen', pos('d1'), pos('c1')],
       { account: 'a@b.com' },
     );
   });
@@ -1359,7 +1360,7 @@ describe('gog_docs_add_tab', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_add_tab', { docId: 'abc' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'add-tab', 'abc'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'add-tab', pos('abc')], { account: undefined });
   });
 
   it('includes all flags when provided', async () => {
@@ -1374,7 +1375,7 @@ describe('gog_docs_add_tab', () => {
       account: 'a@b.com',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'add-tab', 'abc', '--title=Notes', '--index=2', '--parent-tab=Intro', '--icon-emoji=📌'],
+      ['docs', 'add-tab', pos('abc'), '--title=Notes', '--index=2', '--parent-tab=Intro', '--icon-emoji=📌'],
       { account: 'a@b.com' },
     );
   });
@@ -1384,7 +1385,7 @@ describe('gog_docs_add_tab', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_add_tab', { docId: 'abc', index: 0 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'add-tab', 'abc', '--index=0'],
+      ['docs', 'add-tab', pos('abc'), '--index=0'],
       { account: undefined },
     );
   });
@@ -1398,7 +1399,7 @@ describe('gog_docs_rename_tab', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_rename_tab', { docId: 'abc', tab: 'Old', title: 'New' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'rename-tab', 'abc', '--tab=Old', '--title=New'],
+      ['docs', 'rename-tab', pos('abc'), '--tab=Old', '--title=New'],
       { account: undefined },
     );
   });
@@ -1408,7 +1409,7 @@ describe('gog_docs_rename_tab', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_rename_tab', { docId: 'abc', tab: 't1', title: 'New', account: 'a@b.com' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'rename-tab', 'abc', '--tab=t1', '--title=New'],
+      ['docs', 'rename-tab', pos('abc'), '--tab=t1', '--title=New'],
       { account: 'a@b.com' },
     );
   });
@@ -1422,7 +1423,7 @@ describe('gog_docs_delete_tab', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_delete_tab', { docId: 'abc', tab: 'Old' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'delete-tab', 'abc', '--tab=Old', '--force'],
+      ['docs', 'delete-tab', pos('abc'), '--tab=Old', '--force'],
       { account: undefined },
     );
   });
@@ -1432,7 +1433,7 @@ describe('gog_docs_delete_tab', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_delete_tab', { docId: 'abc', tab: 't1', account: 'a@b.com' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'delete-tab', 'abc', '--tab=t1', '--force'],
+      ['docs', 'delete-tab', pos('abc'), '--tab=t1', '--force'],
       { account: 'a@b.com' },
     );
   });
@@ -1445,14 +1446,14 @@ describe('gog_docs_clear', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_clear', { docId: 'abc' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'clear', 'abc'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'clear', pos('abc')], { account: undefined });
   });
 
   it('forwards account override', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_clear', { docId: 'abc', account: 'a@b.com' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'clear', 'abc'], { account: 'a@b.com' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'clear', pos('abc')], { account: 'a@b.com' });
   });
 });
 
@@ -1466,7 +1467,7 @@ describe('gog_docs_table_row_insert', () => {
       docId: 'd1', table: '2', at: 'end', valuesJson: '["A","B"]', tab: 'T',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'table-row', 'insert', 'd1', '--table=2', '--at=end', '--values-json=["A","B"]', '--tab=T'],
+      ['docs', 'table-row', 'insert', pos('d1'), '--table=2', '--at=end', '--values-json=["A","B"]', '--tab=T'],
       { account: undefined },
     );
   });
@@ -1475,7 +1476,7 @@ describe('gog_docs_table_row_insert', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_table_row_insert', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'table-row', 'insert', 'd1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'table-row', 'insert', pos('d1')], { account: undefined });
   });
 });
 
@@ -1485,7 +1486,7 @@ describe('gog_docs_table_row_delete', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_table_row_delete', { docId: 'd1', row: -1, table: 'Budget' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'table-row', 'delete', 'd1', '--row=-1', '--table=Budget'],
+      ['docs', 'table-row', 'delete', pos('d1'), '--row=-1', '--table=Budget'],
       { account: undefined },
     );
   });
@@ -1497,7 +1498,7 @@ describe('gog_docs_table_column_insert', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_table_column_insert', { docId: 'd1', at: '3', table: '*', tab: 'T' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'table-column', 'insert', 'd1', '--at=3', '--table=*', '--tab=T'],
+      ['docs', 'table-column', 'insert', pos('d1'), '--at=3', '--table=*', '--tab=T'],
       { account: undefined },
     );
   });
@@ -1509,7 +1510,7 @@ describe('gog_docs_table_column_delete', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_table_column_delete', { docId: 'd1', col: 2 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'table-column', 'delete', 'd1', '--col=2'],
+      ['docs', 'table-column', 'delete', pos('d1'), '--col=2'],
       { account: undefined },
     );
   });
@@ -1521,7 +1522,7 @@ describe('gog_docs_table_merge', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_table_merge', { docId: 'd1', range: '1,1:2,3', table: '1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'table-merge', 'd1', '--range=1,1:2,3', '--table=1'],
+      ['docs', 'table-merge', pos('d1'), '--range=1,1:2,3', '--table=1'],
       { account: undefined },
     );
   });
@@ -1533,7 +1534,7 @@ describe('gog_docs_table_unmerge', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_table_unmerge', { docId: 'd1', cell: '1,1', tab: 'T' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'table-unmerge', 'd1', '--cell=1,1', '--tab=T'],
+      ['docs', 'table-unmerge', pos('d1'), '--cell=1,1', '--tab=T'],
       { account: undefined },
     );
   });
@@ -1547,7 +1548,7 @@ describe('gog_docs_named_range_create', () => {
       docId: 'd1', name: 'intro', at: 'Introduction', occurrence: 1, matchCase: true,
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'named-range', 'create', 'd1', '--name=intro', '--at=Introduction', '--occurrence=1', '--match-case'],
+      ['docs', 'named-range', 'create', pos('d1'), '--name=intro', '--at=Introduction', '--occurrence=1', '--match-case'],
       { account: undefined },
     );
   });
@@ -1557,7 +1558,7 @@ describe('gog_docs_named_range_create', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_named_range_create', { docId: 'd1', name: 'intro', start: 5, end: 20, tab: 'T' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'named-range', 'create', 'd1', '--name=intro', '--start=5', '--end=20', '--tab=T'],
+      ['docs', 'named-range', 'create', pos('d1'), '--name=intro', '--start=5', '--end=20', '--tab=T'],
       { account: undefined },
     );
   });
@@ -1569,7 +1570,7 @@ describe('gog_docs_named_range_list', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_named_range_list', { docId: 'd1', name: 'intro' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'named-range', 'list', 'd1', '--name=intro'],
+      ['docs', 'named-range', 'list', pos('d1'), '--name=intro'],
       { account: undefined },
     );
   });
@@ -1581,7 +1582,7 @@ describe('gog_docs_named_range_delete', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_named_range_delete', { docId: 'd1', nameOrId: 'intro' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'named-range', 'delete', 'd1', 'intro'],
+      ['docs', 'named-range', 'delete', pos('d1'), pos('intro')],
       { account: undefined },
     );
   });
@@ -1593,7 +1594,7 @@ describe('gog_docs_named_range_replace', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_named_range_replace', { docId: 'd1', nameOrId: 'intro', text: 'New intro', tab: 'T' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'named-range', 'replace', 'd1', 'intro', '--text=New intro', '--tab=T'],
+      ['docs', 'named-range', 'replace', pos('d1'), pos('intro'), '--text=New intro', '--tab=T'],
       { account: undefined },
     );
   });
@@ -1603,7 +1604,7 @@ describe('gog_docs_named_range_replace', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_named_range_replace', { docId: 'd1', nameOrId: 'kix.abc', file: '/tmp/intro.txt' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'named-range', 'replace', 'd1', 'kix.abc', '--file=/tmp/intro.txt'],
+      ['docs', 'named-range', 'replace', pos('d1'), pos('kix.abc'), '--file=/tmp/intro.txt'],
       { account: undefined },
     );
   });
@@ -1614,7 +1615,7 @@ describe('gog_docs_tables_list', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_tables_list', { docId: 'd1', tab: 'T' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'tables', 'list', 'd1', '--tab=T'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'tables', 'list', pos('d1'), '--tab=T'], { account: undefined });
   });
 });
 
@@ -1623,7 +1624,7 @@ describe('gog_docs_images_list', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_images_list', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'images', 'list', 'd1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'images', 'list', pos('d1')], { account: undefined });
   });
 });
 
@@ -1632,7 +1633,7 @@ describe('gog_docs_headings_list', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_headings_list', { docId: 'd1', level: 2 });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'headings', 'list', 'd1', '--level=2'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'headings', 'list', pos('d1'), '--level=2'], { account: undefined });
   });
 });
 
@@ -1642,7 +1643,7 @@ describe('gog_docs_paragraphs_list', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_paragraphs_list', { docId: 'd1', style: 'HEADING_2', tab: 'T' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'paragraphs', 'list', 'd1', '--style=HEADING_2', '--tab=T'],
+      ['docs', 'paragraphs', 'list', pos('d1'), '--style=HEADING_2', '--tab=T'],
       { account: undefined },
     );
   });
@@ -1654,7 +1655,7 @@ describe('gog_docs_insert_image url mode', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_image', { docId: 'd1', url: 'https://x.test/i.png', at: '{{logo}}' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-image', 'd1', '--url=https://x.test/i.png', '--at={{logo}}'],
+      ['docs', 'insert-image', pos('d1'), '--url=https://x.test/i.png', '--at={{logo}}'],
       { account: undefined },
     );
   });
@@ -1665,14 +1666,14 @@ describe('gog_docs_read json tab targeting', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_read', { docId: 'd1', format: 'json', tab: 'T' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'raw', 'd1', '--pretty', '--tab=T'], { account: undefined, lossless: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'raw', pos('d1'), '--pretty', '--tab=T'], { account: undefined, lossless: true });
   });
 
   it('passes --all-tabs through to docs raw in json mode', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_read', { docId: 'd1', format: 'json', allTabs: true });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'raw', 'd1', '--pretty', '--all-tabs'], { account: undefined, lossless: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'raw', pos('d1'), '--pretty', '--all-tabs'], { account: undefined, lossless: true });
   });
 });
 
@@ -1704,7 +1705,7 @@ describe('batch lifecycle tools', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_batch_end', { batchId: 'b1', autoSplit: true, continueOnError: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['batch', 'end', 'b1', '--auto-split', '--continue-on-error'],
+      ['batch', 'end', pos('b1'), '--auto-split', '--continue-on-error'],
       { account: undefined },
     );
   });
@@ -1714,7 +1715,7 @@ describe('batch lifecycle tools', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_batch_end', { batchId: 'b1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['batch', 'end', 'b1'],
+      ['batch', 'end', pos('b1')],
       { account: undefined },
     );
   });
@@ -1723,7 +1724,7 @@ describe('batch lifecycle tools', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_batch_abort', { batchId: 'b1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['batch', 'abort', 'b1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['batch', 'abort', pos('b1')], { account: undefined });
   });
 
   it('gog_batch_list / gog_batch_show read batch state', async () => {
@@ -1732,7 +1733,7 @@ describe('batch lifecycle tools', () => {
     await harness.callTool('gog_batch_list', {});
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['batch', 'list'], { account: undefined });
     await harness.callTool('gog_batch_show', { batchId: 'b1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['batch', 'show', 'b1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['batch', 'show', pos('b1')], { account: undefined });
   });
 
   it('gog_batch_prune deletes stale batches', async () => {
@@ -1755,23 +1756,23 @@ describe('batch param on docs mutation tools (gog 0.25.0)', () => {
   // batch instead of submitting when batch is supplied.
   const cases: Array<{ tool: string; input: Record<string, unknown>; expected: string[] }> = [
     { tool: 'gog_docs_insert', input: { docId: 'd1', content: 'X', batch: 'b1' },
-      expected: ['docs', 'insert', 'd1', 'X', '--batch=b1'] },
+      expected: ['docs', 'insert', pos('d1'), pos('X'), '--batch=b1'] },
     { tool: 'gog_docs_delete', input: { docId: 'd1', start: 1, end: 5, batch: 'b1' },
-      expected: ['docs', 'delete', '--start=1', '--end=5', 'd1', '--batch=b1'] },
+      expected: ['docs', 'delete', '--start=1', '--end=5', pos('d1'), '--batch=b1'] },
     { tool: 'gog_docs_update', input: { docId: 'd1', text: 'T', batch: 'b1' },
-      expected: ['docs', 'update', 'd1', '--text=T', '--batch=b1'] },
+      expected: ['docs', 'update', pos('d1'), '--text=T', '--batch=b1'] },
     { tool: 'gog_docs_format', input: { docId: 'd1', match: 'm', bold: true, batch: 'b1' },
-      expected: ['docs', 'format', 'd1', '--match=m', '--bold', '--batch=b1'] },
+      expected: ['docs', 'format', pos('d1'), '--match=m', '--bold', '--batch=b1'] },
     { tool: 'gog_docs_insert_page_break', input: { docId: 'd1', atEnd: true, batch: 'b1' },
-      expected: ['docs', 'insert-page-break', 'd1', '--at-end', '--batch=b1'] },
+      expected: ['docs', 'insert-page-break', pos('d1'), '--at-end', '--batch=b1'] },
     { tool: 'gog_docs_insert_person', input: { docId: 'd1', email: 'a@b.com', batch: 'b1' },
-      expected: ['docs', 'insert-person', 'd1', '--email=a@b.com', '--batch=b1'] },
+      expected: ['docs', 'insert-person', pos('d1'), '--email=a@b.com', '--batch=b1'] },
     { tool: 'gog_docs_insert_date_chip', input: { docId: 'd1', batch: 'b1' },
-      expected: ['docs', 'insert-date-chip', 'd1', '--batch=b1'] },
+      expected: ['docs', 'insert-date-chip', pos('d1'), '--batch=b1'] },
     { tool: 'gog_docs_table_column_width', input: { docId: 'd1', col: 1, width: 80, batch: 'b1' },
-      expected: ['docs', 'table-column-width', 'd1', '--col=1', '--width=80', '--batch=b1'] },
+      expected: ['docs', 'table-column-width', pos('d1'), '--col=1', '--width=80', '--batch=b1'] },
     { tool: 'gog_docs_cell_style', input: { docId: 'd1', row: 0, col: 0, bold: true, batch: 'b1' },
-      expected: ['docs', 'cell-style', 'd1', '--row=0', '--col=0', '--bold', '--batch=b1'] },
+      expected: ['docs', 'cell-style', pos('d1'), '--row=0', '--col=0', '--bold', '--batch=b1'] },
   ];
 
   for (const { tool, input, expected } of cases) {
@@ -1789,23 +1790,23 @@ describe('batch param on docs mutation tools (gog 0.25.0)', () => {
 describe('tab/table selector branch coverage', () => {
   const cases: Array<{ tool: string; input: Record<string, unknown>; expected: string[] }> = [
     { tool: 'gog_docs_table_row_delete', input: { docId: 'd1', row: 1, tab: 'T' },
-      expected: ['docs', 'table-row', 'delete', 'd1', '--row=1', '--tab=T'] },
+      expected: ['docs', 'table-row', 'delete', pos('d1'), '--row=1', '--tab=T'] },
     { tool: 'gog_docs_table_column_delete', input: { docId: 'd1', col: 1, table: '2', tab: 'T' },
-      expected: ['docs', 'table-column', 'delete', 'd1', '--col=1', '--table=2', '--tab=T'] },
+      expected: ['docs', 'table-column', 'delete', pos('d1'), '--col=1', '--table=2', '--tab=T'] },
     { tool: 'gog_docs_table_merge', input: { docId: 'd1', range: '1,1:2,2', tab: 'T' },
-      expected: ['docs', 'table-merge', 'd1', '--range=1,1:2,2', '--tab=T'] },
+      expected: ['docs', 'table-merge', pos('d1'), '--range=1,1:2,2', '--tab=T'] },
     { tool: 'gog_docs_table_unmerge', input: { docId: 'd1', cell: '1,1', table: 'Budget' },
-      expected: ['docs', 'table-unmerge', 'd1', '--cell=1,1', '--table=Budget'] },
+      expected: ['docs', 'table-unmerge', pos('d1'), '--cell=1,1', '--table=Budget'] },
     { tool: 'gog_docs_named_range_list', input: { docId: 'd1', tab: 'T' },
-      expected: ['docs', 'named-range', 'list', 'd1', '--tab=T'] },
+      expected: ['docs', 'named-range', 'list', pos('d1'), '--tab=T'] },
     { tool: 'gog_docs_named_range_delete', input: { docId: 'd1', nameOrId: 'nr', tab: 'T' },
-      expected: ['docs', 'named-range', 'delete', 'd1', 'nr', '--tab=T'] },
+      expected: ['docs', 'named-range', 'delete', pos('d1'), pos('nr'), '--tab=T'] },
     { tool: 'gog_docs_images_list', input: { docId: 'd1', tab: 'T' },
-      expected: ['docs', 'images', 'list', 'd1', '--tab=T'] },
+      expected: ['docs', 'images', 'list', pos('d1'), '--tab=T'] },
     { tool: 'gog_docs_headings_list', input: { docId: 'd1', tab: 'T' },
-      expected: ['docs', 'headings', 'list', 'd1', '--tab=T'] },
+      expected: ['docs', 'headings', 'list', pos('d1'), '--tab=T'] },
     { tool: 'gog_docs_insert_date_chip', input: { docId: 'd1', tab: 'T' },
-      expected: ['docs', 'insert-date-chip', 'd1', '--tab=T'] },
+      expected: ['docs', 'insert-date-chip', pos('d1'), '--tab=T'] },
   ];
   for (const { tool, input, expected } of cases) {
     it(`${tool} passes its tab/table selectors`, async () => {
@@ -1820,11 +1821,11 @@ describe('tab/table selector branch coverage', () => {
 describe('bare-call branch coverage (no optional flags)', () => {
   const cases: Array<{ tool: string; input: Record<string, unknown>; expected: string[] }> = [
     { tool: 'gog_docs_table_column_insert', input: { docId: 'd1' },
-      expected: ['docs', 'table-column', 'insert', 'd1'] },
+      expected: ['docs', 'table-column', 'insert', pos('d1')] },
     { tool: 'gog_docs_tables_list', input: { docId: 'd1' },
-      expected: ['docs', 'tables', 'list', 'd1'] },
+      expected: ['docs', 'tables', 'list', pos('d1')] },
     { tool: 'gog_docs_paragraphs_list', input: { docId: 'd1' },
-      expected: ['docs', 'paragraphs', 'list', 'd1'] },
+      expected: ['docs', 'paragraphs', 'list', pos('d1')] },
   ];
   for (const { tool, input, expected } of cases) {
     it(`${tool} with no optional flags`, async () => {
@@ -1846,7 +1847,7 @@ describe('segment targeting (gog 0.30)', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert', { docId: 'd1', content: 'hi', segment: 'kix.h1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert', 'd1', 'hi', '--segment=kix.h1'],
+      ['docs', 'insert', pos('d1'), pos('hi'), '--segment=kix.h1'],
       { account: undefined },
     );
   });
@@ -1856,7 +1857,7 @@ describe('segment targeting (gog 0.30)', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_update', { docId: 'd1', text: 'hi', segment: 'kix.f1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'update', 'd1', '--text=hi', '--segment=kix.f1'],
+      ['docs', 'update', pos('d1'), '--text=hi', '--segment=kix.f1'],
       { account: undefined },
     );
   });
@@ -1866,7 +1867,7 @@ describe('segment targeting (gog 0.30)', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_delete', { docId: 'd1', start: 1, end: 5, segment: 'kix.h1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'delete', '--start=1', '--end=5', 'd1', '--segment=kix.h1'],
+      ['docs', 'delete', '--start=1', '--end=5', pos('d1'), '--segment=kix.h1'],
       { account: undefined },
     );
   });
@@ -1876,7 +1877,7 @@ describe('segment targeting (gog 0.30)', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_find_range', { docId: 'd1', text: 'Heading', segment: 'kix.h1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'find-range', 'd1', 'Heading', '--segment=kix.h1'],
+      ['docs', 'find-range', pos('d1'), pos('Heading'), '--segment=kix.h1'],
       { account: undefined },
     );
   });
@@ -1892,7 +1893,7 @@ describe('gog_docs_format paragraph list / indent / spacing / keep (gog 0.30)',
       keepLinesTogether: true, keepWithNext: true, segment: 'kix.h1',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'format', 'd1', '--bullets', '--bullet-preset=BULLET_DISC_CIRCLE_SQUARE',
+      ['docs', 'format', pos('d1'), '--bullets', '--bullet-preset=BULLET_DISC_CIRCLE_SQUARE',
         '--indent-start=18', '--indent-end=6', '--indent-first-line=36', '--space-above=4', '--space-below=8',
         '--keep-lines-together', '--keep-with-next', '--segment=kix.h1'],
       { account: undefined },
@@ -1906,7 +1907,7 @@ describe('gog_docs_format paragraph list / indent / spacing / keep (gog 0.30)',
       docId: 'd1', ordered: true, noBullets: true, keepLinesTogether: false, keepWithNext: false,
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'format', 'd1', '--ordered', '--no-bullets', '--no-keep-lines-together', '--no-keep-with-next'],
+      ['docs', 'format', pos('d1'), '--ordered', '--no-bullets', '--no-keep-lines-together', '--no-keep-with-next'],
       { account: undefined },
     );
   });
@@ -1921,7 +1922,7 @@ describe('gog_docs_insert_footnote', () => {
       at: 'word', occurrence: 2, matchCase: true, tab: 'T',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-footnote', 'd1', '--text=note', '--file=/tmp/n.txt', '--index=5', '--at-end',
+      ['docs', 'insert-footnote', pos('d1'), '--text=note', '--file=/tmp/n.txt', '--index=5', '--at-end',
         '--at=word', '--occurrence=2', '--match-case', '--tab=T'],
       { account: undefined },
     );
@@ -1931,7 +1932,7 @@ describe('gog_docs_insert_footnote', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_footnote', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'insert-footnote', 'd1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'insert-footnote', pos('d1')], { account: undefined });
   });
 });
 
@@ -1944,7 +1945,7 @@ describe('gog_docs_insert_section_break', () => {
       occurrence: 1, matchCase: true, tab: 'T', batch: 'b1',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-section-break', 'd1', '--type=continuous', '--index=3', '--at-end',
+      ['docs', 'insert-section-break', pos('d1'), '--type=continuous', '--index=3', '--at-end',
         '--at=x', '--occurrence=1', '--match-case', '--tab=T', '--batch=b1'],
       { account: undefined },
     );
@@ -1954,7 +1955,7 @@ describe('gog_docs_insert_section_break', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_section_break', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'insert-section-break', 'd1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'insert-section-break', pos('d1')], { account: undefined });
   });
 });
 
@@ -1966,7 +1967,7 @@ describe('gog_docs_insert_horizontal_rule', () => {
       docId: 'd1', index: 2, atEnd: true, at: 'x', occurrence: 1, matchCase: true, tab: 'T', batch: 'b1',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'insert-horizontal-rule', 'd1', '--index=2', '--at-end', '--at=x',
+      ['docs', 'insert-horizontal-rule', pos('d1'), '--index=2', '--at-end', '--at=x',
         '--occurrence=1', '--match-case', '--tab=T', '--batch=b1'],
       { account: undefined },
     );
@@ -1976,7 +1977,7 @@ describe('gog_docs_insert_horizontal_rule', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_insert_horizontal_rule', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'insert-horizontal-rule', 'd1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'insert-horizontal-rule', pos('d1')], { account: undefined });
   });
 });
 
@@ -1989,7 +1990,7 @@ describe('gog_docs_section_columns', () => {
       at: 'x', occurrence: 1, matchCase: true, tab: 'T', batch: 'b1',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'section-columns', 'd1', '--count=2', '--separator=between', '--index=4', '--at-end',
+      ['docs', 'section-columns', pos('d1'), '--count=2', '--separator=between', '--index=4', '--at-end',
         '--at=x', '--occurrence=1', '--match-case', '--tab=T', '--batch=b1'],
       { account: undefined },
     );
@@ -1999,7 +2000,7 @@ describe('gog_docs_section_columns', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_section_columns', { docId: 'd1', count: 1 });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'section-columns', 'd1', '--count=1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'section-columns', pos('d1'), '--count=1'], { account: undefined });
   });
 });
 
@@ -2008,14 +2009,14 @@ describe('gog_docs header lifecycle', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_header_list', { docId: 'd1', tab: 'T' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'header', 'list', 'd1', '--tab=T'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'header', 'list', pos('d1'), '--tab=T'], { account: undefined });
   });
 
   it('header_list bare', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_header_list', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'header', 'list', 'd1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'header', 'list', pos('d1')], { account: undefined });
   });
 
   it('header_create passes text and anchor flags', async () => {
@@ -2026,7 +2027,7 @@ describe('gog_docs header lifecycle', () => {
       at: 'x', occurrence: 1, matchCase: true, tab: 'T',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'header', 'create', 'd1', '--text=Title', '--file=/tmp/h.txt', '--index=1', '--at-end',
+      ['docs', 'header', 'create', pos('d1'), '--text=Title', '--file=/tmp/h.txt', '--index=1', '--at-end',
         '--at=x', '--occurrence=1', '--match-case', '--tab=T'],
       { account: undefined },
     );
@@ -2036,21 +2037,21 @@ describe('gog_docs header lifecycle', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_header_create', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'header', 'create', 'd1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'header', 'create', pos('d1')], { account: undefined });
   });
 
   it('header_delete passes id and --tab', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_header_delete', { docId: 'd1', headerId: 'kix.h1', tab: 'T' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'header', 'delete', 'd1', 'kix.h1', '--tab=T', '--force'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'header', 'delete', pos('d1'), pos('kix.h1'), '--tab=T', '--force'], { account: undefined });
   });
 
   it('header_delete bare', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_header_delete', { docId: 'd1', headerId: 'kix.h1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'header', 'delete', 'd1', 'kix.h1', '--force'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'header', 'delete', pos('d1'), pos('kix.h1'), '--force'], { account: undefined });
   });
 });
 
@@ -2059,14 +2060,14 @@ describe('gog_docs footer lifecycle', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_footer_list', { docId: 'd1', tab: 'T' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'footer', 'list', 'd1', '--tab=T'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'footer', 'list', pos('d1'), '--tab=T'], { account: undefined });
   });
 
   it('footer_list bare', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_footer_list', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'footer', 'list', 'd1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'footer', 'list', pos('d1')], { account: undefined });
   });
 
   it('footer_create passes text and anchor flags', async () => {
@@ -2077,7 +2078,7 @@ describe('gog_docs footer lifecycle', () => {
       at: 'x', occurrence: 1, matchCase: true, tab: 'T',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'footer', 'create', 'd1', '--text=Foot', '--file=/tmp/f.txt', '--index=1', '--at-end',
+      ['docs', 'footer', 'create', pos('d1'), '--text=Foot', '--file=/tmp/f.txt', '--index=1', '--at-end',
         '--at=x', '--occurrence=1', '--match-case', '--tab=T'],
       { account: undefined },
     );
@@ -2087,21 +2088,21 @@ describe('gog_docs footer lifecycle', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_footer_create', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'footer', 'create', 'd1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'footer', 'create', pos('d1')], { account: undefined });
   });
 
   it('footer_delete passes id and --tab', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_footer_delete', { docId: 'd1', footerId: 'kix.f1', tab: 'T' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'footer', 'delete', 'd1', 'kix.f1', '--tab=T', '--force'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'footer', 'delete', pos('d1'), pos('kix.f1'), '--tab=T', '--force'], { account: undefined });
   });
 
   it('footer_delete bare', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_footer_delete', { docId: 'd1', footerId: 'kix.f1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'footer', 'delete', 'd1', 'kix.f1', '--force'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'footer', 'delete', pos('d1'), pos('kix.f1'), '--force'], { account: undefined });
   });
 });
 
@@ -2113,7 +2114,7 @@ describe('gog_docs_replace_image', () => {
       docId: 'd1', url: 'https://x.test/i.png', objectId: 'kix.img1', tab: 'T',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'replace-image', 'd1', '--url=https://x.test/i.png', '--object-id=kix.img1', '--tab=T'],
+      ['docs', 'replace-image', pos('d1'), '--url=https://x.test/i.png', '--object-id=kix.img1', '--tab=T'],
       { account: undefined },
     );
   });
@@ -2125,7 +2126,7 @@ describe('gog_docs_replace_image', () => {
       docId: 'd1', file: '/tmp/i.png', matchAlt: 'logo', name: 'new.png', parent: 'folder1',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'replace-image', 'd1', '--file=/tmp/i.png', '--match-alt=logo', '--name=new.png', '--parent=folder1', '--force'],
+      ['docs', 'replace-image', pos('d1'), '--file=/tmp/i.png', '--match-alt=logo', '--name=new.png', '--parent=folder1', '--force'],
       { account: undefined },
     );
   });
@@ -2137,7 +2138,7 @@ describe('gog_docs_table_row_pin_header', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_table_row_pin_header', { docId: 'd1', rows: 2, table: '1', tab: 'T' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'table-row', 'pin-header', 'd1', '--rows=2', '--table=1', '--tab=T'],
+      ['docs', 'table-row', 'pin-header', pos('d1'), '--rows=2', '--table=1', '--tab=T'],
       { account: undefined },
     );
   });
@@ -2147,7 +2148,7 @@ describe('gog_docs_table_row_pin_header', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_table_row_pin_header', { docId: 'd1', rows: 0 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'table-row', 'pin-header', 'd1', '--rows=0'],
+      ['docs', 'table-row', 'pin-header', pos('d1'), '--rows=0'],
       { account: undefined },
     );
   });
@@ -2161,7 +2162,7 @@ describe('gog_docs_table_row_style', () => {
       docId: 'd1', row: 1, minHeight: '20pt', preventOverflow: true, table: '1', tab: 'T',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'table-row', 'style', 'd1', '--row=1', '--min-height=20pt', '--prevent-overflow', '--table=1', '--tab=T'],
+      ['docs', 'table-row', 'style', pos('d1'), '--row=1', '--min-height=20pt', '--prevent-overflow', '--table=1', '--tab=T'],
       { account: undefined },
     );
   });
@@ -2171,7 +2172,7 @@ describe('gog_docs_table_row_style', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_table_row_style', { docId: 'd1', preventOverflow: false });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'table-row', 'style', 'd1', '--no-prevent-overflow'],
+      ['docs', 'table-row', 'style', pos('d1'), '--no-prevent-overflow'],
       { account: undefined },
     );
   });
@@ -2183,7 +2184,7 @@ describe('gog_docs_table_row_style overflow-unset branch', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_table_row_style', { docId: 'd1', row: 2, minHeight: '30pt' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'table-row', 'style', 'd1', '--row=2', '--min-height=30pt'],
+      ['docs', 'table-row', 'style', pos('d1'), '--row=2', '--min-height=30pt'],
       { account: undefined },
     );
   });
@@ -2196,7 +2197,7 @@ describe('gog_docs_suggestions_list', () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_suggestions_list', { docId: 'd1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'suggestions', 'list', 'd1'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'suggestions', 'list', pos('d1')], { account: undefined });
   });
 
   it('includes --tab when provided', async () => {
@@ -2204,7 +2205,7 @@ describe('gog_docs_suggestions_list', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_suggestions_list', { docId: 'd1', tab: 'Notes' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'suggestions', 'list', 'd1', '--tab=Notes'],
+      ['docs', 'suggestions', 'list', pos('d1'), '--tab=Notes'],
       { account: undefined },
     );
   });
@@ -2214,7 +2215,7 @@ describe('gog_docs_suggestions_list', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_suggestions_list', { docId: 'd1', account: 'other@gmail.com' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'suggestions', 'list', 'd1'],
+      ['docs', 'suggestions', 'list', pos('d1')],
       { account: 'other@gmail.com' },
     );
   });
@@ -2230,7 +2231,7 @@ describe('gog_docs_format spacingMode', () => {
       docId: 'd1', spaceAbove: 6, spaceBelow: 12, spacingMode: 'COLLAPSE_LISTS',
     });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'format', 'd1', '--space-above=6', '--space-below=12', '--spacing-mode=COLLAPSE_LISTS'],
+      ['docs', 'format', pos('d1'), '--space-above=6', '--space-below=12', '--spacing-mode=COLLAPSE_LISTS'],
       { account: undefined },
     );
   });
@@ -2240,7 +2241,7 @@ describe('gog_docs_format spacingMode', () => {
     const harness = await setupHandlers();
     await harness.callTool('gog_docs_format', { docId: 'd1', spaceAbove: 6 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
-      ['docs', 'format', 'd1', '--space-above=6'],
+      ['docs', 'format', pos('d1'), '--space-above=6'],
       { account: undefined },
     );
   });
@@ -2272,3 +2273,49 @@ describe('server-side file params never advertise stdin as usable', () => {
     expect(desc).toMatch(/hang|never writes/i);
   });
 });
+
+// SEC-3/SEC-4: every model-supplied server path must resolve inside an
+// operator-configured root (GOG_FILE_ROOTS). The suite runs with '/' so the
+// arg-shape tests can use any path; these narrow it.
+async function withFileRoots<T>(roots: string, fn: () => Promise<T>): Promise<T> {
+  const prev = process.env.GOG_FILE_ROOTS;
+  process.env.GOG_FILE_ROOTS = roots;
+  try {
+    return await fn();
+  } finally {
+    process.env.GOG_FILE_ROOTS = prev;
+  }
+}
+
+describe('server paths are confined to GOG_FILE_ROOTS', () => {
+  it.each([
+    ['gog_docs_export', {"docId": "d1", "out": "/Users/me/.zshrc"}, 'out'],
+    ['gog_docs_insert', {"docId": "d1", "file": "/etc/passwd"}, 'file'],
+    ['gog_docs_append', {"docId": "d1", "file": "/etc/passwd"}, 'file'],
+    ['gog_docs_sed', {"docId": "d1", "file": "/etc/passwd"}, 'file'],
+    ['gog_docs_update', {"docId": "d1", "file": "/etc/passwd"}, 'file'],
+    ['gog_docs_named_range_replace', {"docId": "d1", "nameOrId": "n", "file": "/etc/passwd"}, 'file'],
+    ['gog_docs_cell_update', {"docId": "d1", "table": 1, "row": 1, "col": 1, "contentFile": "/etc/passwd"}, 'contentFile'],
+    ['gog_docs_insert_image', {"docId": "d1", "file": "/etc/passwd"}, 'file'],
+    ['gog_docs_insert_footnote', {"docId": "d1", "file": "/etc/passwd"}, 'file'],
+    ['gog_docs_header_create', {"docId": "d1", "file": "/etc/passwd"}, 'file'],
+    ['gog_docs_footer_create', {"docId": "d1", "file": "/etc/passwd"}, 'file'],
+    ['gog_docs_replace_image', {"docId": "d1", "file": "/etc/passwd"}, 'file'],
+  ] as Array<[string, Record<string, unknown>, string]>)('%s refuses %j outside the roots', async (tool, args, param) => {
+    const h = await setupHandlers();
+    const result = await withFileRoots('/srv/gog-files', () => h.callTool(tool, args));
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toMatch(new RegExp(`${param} ".*" is outside the directories`));
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+
+  // Clients auto-approve readOnlyHint tools; these write (and can overwrite)
+  // files on the gog host, so they must not claim to be read-only.
+  it.each(["gog_docs_export"])('%s is not advertised as read-only and is marked destructive', async (name) => {
+    const h = await setupHandlers();
+    const { tools } = await h.client.listTools();
+    const tool = tools.find((t) => t.name === name)!;
+    expect(tool.annotations?.readOnlyHint).not.toBe(true);
+    expect(tool.annotations?.destructiveHint).toBe(true);
+  });
+});