diff --git a/browse/src/terminal-agent.ts b/browse/src/terminal-agent.ts
index c5417bd38..88e89a719 100644
--- a/browse/src/terminal-agent.ts
+++ b/browse/src/terminal-agent.ts
@@ -301,11 +301,12 @@ function buildTabAwarenessHint(stateDir: string): string {
     'You are running inside the gstack browser sidebar with live access to the user\'s browser tabs.',
     '',
     'Tab state files (kept fresh automatically by the extension):',
-    `  ${tabsFile}        — all open tabs (id, url, title, active, pinned)`,
-    `  ${activeFile}    — the currently active tab`,
-    'Read these any time the user asks about "tabs", "the current page", or anything multi-tab. Do NOT shell out to $B tabs just to learn what\'s open — read the file.',
+    `  ${tabsFile}        — all open tabs: tabs[] of {tabId, url, title, active, pinned, windowId}`,
+    `  ${activeFile}    — the currently active tab: {tabId, url, title}`,
+    'Read these any time the user asks about "tabs", "the current page", or anything multi-tab. They\'re kept current, so read them instead of running $B tabs when you only need to know what\'s open.',
     '',
     'Tab manipulation commands (via $B):',
+    '  ($B is the gstack browse CLI. This shell does not set it, so resolve it the way the /browse skill does: the project\'s .claude/skills/gstack/browse/dist/browse if present, else ~/.claude/skills/gstack/browse/dist/browse.)',
     '  $B tab <id>                 — switch to a tab',
     '  $B newtab [url]             — open a new tab',
     '  $B closetab [id]            — close a tab (current if no id)',