@jobshimo/browser-link 0.8.2 → 0.9.0

package/dist/tools/server-instructions.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Build the MCP `initialize.instructions` payload from the structured `doc`
+ * blocks each tool definition carries. Keeping the per-tool copy beside the
+ * tool definition (in `browser-definitions.ts` and `map/tools.ts`) prevents
+ * drift between the schema and the human-facing documentation.
+ *
+ * `SERVER_INSTRUCTIONS` is computed once at module load and exported as a
+ * plain string so the existing consumers (`server.ts`, `bridge/server.ts`)
+ * keep working without changes.
+ */
+/** Generate the SERVER_INSTRUCTIONS string from the tool definitions.
+ * Exported for tests and for any future caller that needs to re-render
+ * the string after a hot-reload or runtime tool registration. */
+export declare function buildServerInstructions(): string;
 /** Usage protocol pushed to the MCP client on `initialize`. Plain string,
- * intentionally kept short. Edit here when the protocol changes. */
-export declare const SERVER_INSTRUCTIONS = "browser-link bridges Claude Code to the Chrome tabs the user has\nexplicitly connected through the companion extension, and ships a\npersistent UI map backed by a local SQLite DB. The data dir resolves\nper-OS via env-paths ($XDG_DATA_HOME/browser-link on Linux,\n~/Library/Application Support/browser-link on macOS, %APPDATA%/browser-link\non Windows). Override with $BROWSER_LINK_DATA_DIR. The map is private\nand per-machine; never persisted in any repo.\n\n## When operating on a tab\n\n1. Before doing anything on a tab whose URL you don't already know,\n   call `browser.map.recall` with { origin } (and optionally url) to load\n   selectors, flows and gotchas previously learned for that app.\n2. If recall returns entries with `failed_at` more recent than\n   `verified_at`, treat them as suspect: re-verify (snapshot / evaluate)\n   before reusing, or replace them.\n3. After every interaction that used a map entry, call\n   `browser.map.record_use` with { entry_id, ok }. ok=true updates\n   verified_at; ok=false updates failed_at. Keep the map honest.\n4. After a non-trivial flow that worked end-to-end, persist it with\n   `browser.map.save`. Three `kind` values:\n   - selector: { selector, evidence? } \u2014 a CSS selector tied to a purpose.\n   - flow: { steps: [...] } \u2014 an ordered list of actions to reach an outcome.\n   - gotcha: { body } \u2014 free-form note about something non-obvious.\n   Use `url_pattern` = pathname (exact). Promote to glob only if you have\n   evidence of a parametric route. Provide `purpose` as a stable, reusable\n   label (\"open task detail dialog\", not \"open IB0311 detail\").\n5. Never save selectors or flows you have not just successfully executed.\n6. Never store domain data (IDs, user names, dates, etc.). The map captures\n   UI structure only.\n\n## Identifying the app\n\n- `origin` = scheme://host:port of the tab.\n- `app_key` distinguishes apps that share an origin over time. On first\n  save you may omit it; it will be derived from the page title (slugified).\n  Use `browser.map.rename_app` if that initial guess is poor.\n\n## Sharing tabs with other agents\n\nThis primary may be serving several MCP clients at once (multi-agent mode).\nTo stop two agents fighting over the same Chrome tab there is a cooperative\nclaim layer:\n\n- `browser.list_tabs` includes `claimed_by` (null if free, otherwise the\n  agent that holds the claim) and `claimed_by_me` (boolean). Use it before\n  starting work on a tab whose state you don't already own.\n- `browser.my_tabs` returns YOUR active claims with timestamps. If the\n  user asks which tab you are using, this is the answer.\n- Action tools (`browser.click`, `browser.type`, `browser.navigate`,\n  `browser.evaluate`) auto-claim a free tab on first use and refresh\n  activity on subsequent calls. If another agent holds the tab, they\n  return an error naming the owner \u2014 do NOT retry blindly; ask the user\n  whose tab it should be, or use a different tab.\n- Read tools (`browser.snapshot`, `browser.console`, `browser.network`,\n  `browser.network_body`, `browser.events`, `browser.ping`) ignore claims.\n- `browser.claim_tab({ tab_id, ttl_minutes?, label? })` reserves a tab\n  explicitly. Provide a stable `label` (eg \"claude-code\", \"opencode\") so\n  other agents and the user see WHO holds the tab. The label is display\n  only \u2014 security relies on the IPC session id (kernel-vetted), not on\n  what an agent calls itself.\n- `browser.release_tab({ tab_id })` hands a tab back. Claims also auto-\n  release when an agent disconnects or after the inactivity TTL elapses\n  (default 10 minutes), so explicit release is only needed for early\n  hand-off.\n\nWhen you get a claim-conflict error: do NOT spin-retry. Either work on a\ndifferent tab from `list_tabs`, or surface the conflict to the user and\nlet them decide.\n\n## When something is wrong\n\n- A selector from recall fails \u2192 record_use({ok:false}), learn the new\n  one, save it (upsert on purpose).\n- A whole app got refactored \u2192 `browser.map.forget` the app_id and let\n  the map repopulate as you learn the new structure.\n- A tool call fails with \"Tab not connected: tab_X\" \u2192 call\n  `browser.events` to see whether the bridge changed primary (the\n  Chrome tab probably got a new tab_id after a reconnect). Look for a\n  `tab-renamed` event with previous=tab_X and resume on the current id.\n\nThe map is a cache of navigation, not a substitute for `browser.snapshot`.\nThe live snapshot is always the source of truth.";
+ * generated from the per-tool `doc` blocks at module load. */
+export declare const SERVER_INSTRUCTIONS: string;

package/dist/tools/server-instructions.js

@@ -1,6 +1,19 @@
-/** Usage protocol pushed to the MCP client on `initialize`. Plain string,
- * intentionally kept short. Edit here when the protocol changes. */
-export const SERVER_INSTRUCTIONS = `browser-link bridges Claude Code to the Chrome tabs the user has
+/**
+ * Build the MCP `initialize.instructions` payload from the structured `doc`
+ * blocks each tool definition carries. Keeping the per-tool copy beside the
+ * tool definition (in `browser-definitions.ts` and `map/tools.ts`) prevents
+ * drift between the schema and the human-facing documentation.
+ *
+ * `SERVER_INSTRUCTIONS` is computed once at module load and exported as a
+ * plain string so the existing consumers (`server.ts`, `bridge/server.ts`)
+ * keep working without changes.
+ */
+import { BROWSER_TOOL_DEFINITIONS } from './browser-definitions.js';
+import { MAP_TOOL_DEFINITIONS } from '../map/tools.js';
+/** Stable preamble — explains what the bridge is, where state lives, and
+ * what the agent must NOT do. Lives here (not in a tool doc) because it is
+ * cross-cutting context, not tied to any one tool. */
+const PREAMBLE = `browser-link bridges Claude Code to the Chrome tabs the user has
 explicitly connected through the companion extension, and ships a
 persistent UI map backed by a local SQLite DB. The data dir resolves
 per-OS via env-paths ($XDG_DATA_HOME/browser-link on Linux,
@@ -8,79 +21,85 @@ per-OS via env-paths ($XDG_DATA_HOME/browser-link on Linux,
 on Windows). Override with $BROWSER_LINK_DATA_DIR. The map is private
 and per-machine; never persisted in any repo.
 
-## When operating on a tab
-
-1. Before doing anything on a tab whose URL you don't already know,
-   call \`browser.map.recall\` with { origin } (and optionally url) to load
-   selectors, flows and gotchas previously learned for that app.
-2. If recall returns entries with \`failed_at\` more recent than
-   \`verified_at\`, treat them as suspect: re-verify (snapshot / evaluate)
-   before reusing, or replace them.
-3. After every interaction that used a map entry, call
-   \`browser.map.record_use\` with { entry_id, ok }. ok=true updates
-   verified_at; ok=false updates failed_at. Keep the map honest.
-4. After a non-trivial flow that worked end-to-end, persist it with
-   \`browser.map.save\`. Three \`kind\` values:
-   - selector: { selector, evidence? } — a CSS selector tied to a purpose.
-   - flow: { steps: [...] } — an ordered list of actions to reach an outcome.
-   - gotcha: { body } — free-form note about something non-obvious.
-   Use \`url_pattern\` = pathname (exact). Promote to glob only if you have
-   evidence of a parametric route. Provide \`purpose\` as a stable, reusable
-   label ("open task detail dialog", not "open IB0311 detail").
-5. Never save selectors or flows you have not just successfully executed.
-6. Never store domain data (IDs, user names, dates, etc.). The map captures
-   UI structure only.
-
-## Identifying the app
+## Reflex protocol (ALWAYS ACTIVE)
 
-- \`origin\` = scheme://host:port of the tab.
-- \`app_key\` distinguishes apps that share an origin over time. On first
-  save you may omit it; it will be derived from the page title (slugified).
-  Use \`browser.map.rename_app\` if that initial guess is poor.
+Tools you have here see only Chrome tabs the user explicitly connected
+through the companion extension. Never reason about state you cannot
+see — call \`browser.list_tabs\` BEFORE answering when the user mentions
+a UI element, a web app, a URL, a broken layout, "the page", or asks
+"does X work". Take a \`browser.snapshot\` before suggesting any UI code
+change. If a call returns "Tab not connected", call \`browser.events\`
+to find the new tab_id before retrying. After a non-trivial flow worked
+end-to-end, persist UI structure (NEVER domain data) with
+\`browser.map.save\`.
 
-## Sharing tabs with other agents
+## Sharing tabs with other agents (multi-agent mode)
 
-This primary may be serving several MCP clients at once (multi-agent mode).
-To stop two agents fighting over the same Chrome tab there is a cooperative
-claim layer:
+Several MCP clients may share one bridge. To stop two agents fighting
+over the same Chrome tab, a cooperative claim layer is in place:
 
-- \`browser.list_tabs\` includes \`claimed_by\` (null if free, otherwise the
-  agent that holds the claim) and \`claimed_by_me\` (boolean). Use it before
-  starting work on a tab whose state you don't already own.
-- \`browser.my_tabs\` returns YOUR active claims with timestamps. If the
-  user asks which tab you are using, this is the answer.
 - Action tools (\`browser.click\`, \`browser.type\`, \`browser.navigate\`,
-  \`browser.evaluate\`) auto-claim a free tab on first use and refresh
-  activity on subsequent calls. If another agent holds the tab, they
-  return an error naming the owner — do NOT retry blindly; ask the user
-  whose tab it should be, or use a different tab.
+  \`browser.evaluate\`) auto-claim a free tab on first use. If another
+  agent holds the tab, they return an error naming the owner — do NOT
+  retry blindly; ask the user whose tab it should be, or use a
+  different tab.
 - Read tools (\`browser.snapshot\`, \`browser.console\`, \`browser.network\`,
-  \`browser.network_body\`, \`browser.events\`, \`browser.ping\`) ignore claims.
-- \`browser.claim_tab({ tab_id, ttl_minutes?, label? })\` reserves a tab
-  explicitly. Provide a stable \`label\` (eg "claude-code", "opencode") so
-  other agents and the user see WHO holds the tab. The label is display
-  only — security relies on the IPC session id (kernel-vetted), not on
-  what an agent calls itself.
-- \`browser.release_tab({ tab_id })\` hands a tab back. Claims also auto-
-  release when an agent disconnects or after the inactivity TTL elapses
-  (default 10 minutes), so explicit release is only needed for early
-  hand-off.
+  \`browser.network_body\`, \`browser.events\`, \`browser.ping\`) ignore
+  claims.
+- Use \`browser.claim_tab\` with a stable \`label\` ("claude-code",
+  "opencode") to reserve a tab before a multi-step flow; release with
+  \`browser.release_tab\` (or let the inactivity TTL handle it).
 
-When you get a claim-conflict error: do NOT spin-retry. Either work on a
-different tab from \`list_tabs\`, or surface the conflict to the user and
-let them decide.
+The label is display only — security relies on the IPC session id
+(kernel-vetted), not on what an agent calls itself. When you get a
+claim-conflict error: do NOT spin-retry. Either work on a different tab
+from \`list_tabs\`, or surface the conflict to the user.
 
-## When something is wrong
+## Identifying the app
 
-- A selector from recall fails → record_use({ok:false}), learn the new
-  one, save it (upsert on purpose).
-- A whole app got refactored → \`browser.map.forget\` the app_id and let
-  the map repopulate as you learn the new structure.
-- A tool call fails with "Tab not connected: tab_X" → call
-  \`browser.events\` to see whether the bridge changed primary (the
-  Chrome tab probably got a new tab_id after a reconnect). Look for a
-  \`tab-renamed\` event with previous=tab_X and resume on the current id.
+- \`origin\` = scheme://host:port of the tab.
+- \`app_key\` distinguishes apps that share an origin over time. On
+  first save you may omit it; it will be derived from the page title
+  (slugified). Use \`browser.map.rename_app\` if that initial guess is
+  poor.
 
-The map is a cache of navigation, not a substitute for \`browser.snapshot\`.
-The live snapshot is always the source of truth.`;
+The live snapshot is always the source of truth. The persistent map is
+a cache of navigation, not a substitute.`;
+/** Render a single tool's documentation as a markdown section. Skips
+ * tools without a `doc` block (the structured shape is opt-in for now
+ * so future contributors can stage the migration tool-by-tool). */
+function renderTool(def) {
+    if (!def.doc)
+        return null;
+    const { purpose, when_to_use, gotchas, example } = def.doc;
+    const lines = [`### ${def.name}`, '', purpose, '', '**When to use:**'];
+    for (const w of when_to_use)
+        lines.push(`- ${w}`);
+    if (gotchas && gotchas.length > 0) {
+        lines.push('', '**Gotchas:**');
+        for (const g of gotchas)
+            lines.push(`- ${g}`);
+    }
+    if (example !== undefined && example !== '') {
+        lines.push('', '**Example:**', '```', example, '```');
+    }
+    return lines.join('\n');
+}
+/** Generate the SERVER_INSTRUCTIONS string from the tool definitions.
+ * Exported for tests and for any future caller that needs to re-render
+ * the string after a hot-reload or runtime tool registration. */
+export function buildServerInstructions() {
+    const all = [...BROWSER_TOOL_DEFINITIONS, ...MAP_TOOL_DEFINITIONS];
+    const sections = [PREAMBLE, '', '## Tools'];
+    for (const def of all) {
+        const rendered = renderTool(def);
+        if (rendered) {
+            sections.push('', rendered);
+        }
+    }
+    return sections.join('\n');
+}
+/** Usage protocol pushed to the MCP client on `initialize`. Plain string,
+ * generated from the per-tool `doc` blocks at module load. */
+export const SERVER_INSTRUCTIONS = buildServerInstructions();
 //# sourceMappingURL=server-instructions.js.map

package/dist/tools/server-instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../../src/tools/server-instructions.ts"],"names":[],"mappings":"AAAA;oEACoE;AACpE,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iDAkFc,CAAC"}
+{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../../src/tools/server-instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAGvD;;sDAEsD;AACtD,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yCAmDwB,CAAC;AAE1C;;mEAEmE;AACnE,SAAS,UAAU,CAAC,GAAmB;IACrC,IAAI,CAAC,GAAG,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC;IAC3D,MAAM,KAAK,GAAa,CAAC,OAAO,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,kBAAkB,CAAC,CAAC;IACjF,KAAK,MAAM,CAAC,IAAI,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClD,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QAC5C,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;iEAEiE;AACjE,MAAM,UAAU,uBAAuB;IACrC,MAAM,GAAG,GAAqB,CAAC,GAAG,wBAAwB,EAAE,GAAG,oBAAoB,CAAC,CAAC;IACrF,MAAM,QAAQ,GAAa,CAAC,QAAQ,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC;IACtD,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED;8DAC8D;AAC9D,MAAM,CAAC,MAAM,mBAAmB,GAAG,uBAAuB,EAAE,CAAC"}

package/dist/tools/tab-claims.d.ts

@@ -52,7 +52,7 @@ export type ClaimEvent = {
     kind: 'tab-released';
     tab_id: string;
     agent_id: string;
-    reason: 'explicit' | 'agent-disconnect' | 'ttl';
+    reason: 'explicit' | 'agent-disconnect' | 'ttl' | 'reset';
 } | {
     kind: 'tab-claim-rejected';
     tab_id: string;
@@ -110,6 +110,10 @@ export declare class TabClaimRegistry {
     pruneStale(): TabClaim[];
     /** Test helper. Production callers should not need this. */
     size(): number;
+    /** Drop every claim, emitting one `tab-released` event per dropped claim
+     * (reason: 'reset'). Used by `browser.reset` to wipe ownership in one
+     * step without iterating from the caller side. */
+    releaseAll(): TabClaim[];
     private isExpired;
     private claimInternal;
 }

package/dist/tools/tab-claims.js

@@ -126,6 +126,23 @@ export class TabClaimRegistry {
     size() {
         return this.claims.size;
     }
+    /** Drop every claim, emitting one `tab-released` event per dropped claim
+     * (reason: 'reset'). Used by `browser.reset` to wipe ownership in one
+     * step without iterating from the caller side. */
+    releaseAll() {
+        const released = [];
+        for (const [tabId, claim] of this.claims) {
+            released.push(claim);
+            this.onEvent({
+                kind: 'tab-released',
+                tab_id: tabId,
+                agent_id: claim.agent_id,
+                reason: 'reset',
+            });
+        }
+        this.claims.clear();
+        return released;
+    }
     isExpired(claim) {
         return this.now() - claim.last_activity_at >= claim.ttl_ms;
     }

package/dist/tools/tab-claims.js.map

@@ -1 +1 @@
-{"version":3,"file":"tab-claims.js","sourceRoot":"","sources":["../../src/tools/tab-claims.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tab-claims.js","sourceRoot":"","sources":["../../src/tools/tab-claims.ts"],"names":[],"mappings":"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"}

package/dist/tools/types.d.ts

@@ -1,6 +1,31 @@
-/** Shape of an MCP tool definition for our ListToolsRequestSchema response. */
+/**
+ * Structured human-facing documentation co-located with each tool definition.
+ *
+ * Rendered into the MCP SERVER_INSTRUCTIONS string by
+ * `tools/server-instructions.ts`. The structured shape lets us keep the
+ * "what / when / gotchas / example" close to the tool itself instead of
+ * drifting in a big monolithic string, and lets tests assert per-tool
+ * completeness (purpose + when_to_use are mandatory).
+ */
+export interface ToolDoc {
+    /** What the tool is for, one sentence. */
+    purpose: string;
+    /** When the agent should reach for it — triggers in plain language. */
+    when_to_use: string[];
+    /** Non-obvious gotchas / contracts to honour. Optional. */
+    gotchas?: string[];
+    /** A short representative invocation snippet. Optional. */
+    example?: string;
+}
+/** Shape of an MCP tool definition for our ListToolsRequestSchema response.
+ *
+ * The optional `doc` field carries the structured documentation consumed by
+ * `buildServerInstructions()`. Tools that omit it are not surfaced in the
+ * generated instructions; tools that include it must provide non-empty
+ * `purpose` and `when_to_use` (asserted by tests). */
 export interface ToolDefinition {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
+    doc?: ToolDoc;
 }

package/dist/ui/app.js

@@ -1,11 +1,22 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useApp, useInput } from 'ink';
 import { useState } from 'react';
-import { AboutView, AgentInstructionsView, ClientPicker, DoctorView, ExtensionView, FreePortView, InstallResultView, LanguageView, MainMenu, MultiAgentView, PermissionsView, UpdatesView, WelcomeScreen, } from './screens/index.js';
+import { AboutView, AgentInstructionsView, ClientPicker, DoctorView, EmptyClientsView, ExtensionView, FreePortView, InstallResultView, LanguageView, MainMenu, MultiAgentView, PermissionsView, UpdatesView, WelcomeScreen, } from './screens/index.js';
 import { saveConfig } from '../config.js';
 import { installFor } from '../commands/install.js';
+import { statusAll } from '../commands/instructions.js';
 import { openUrl } from '../utils/open-url.js';
+import { INSTALLERS } from '../installers/index.js';
 const REPO_URL = 'https://github.com/jobshimo/browser-link';
+/* True when at least one of the supported MCP clients is detected on
+ * disk. When false, the register flow short-circuits to the
+ * EmptyClientsView instead of rendering a picker the user can't act on.
+ *
+ * `detect()` does a file existence check — cheap enough to run on every
+ * navigation to the picker, and accurate after a manual install. */
+function anyClientDetected() {
+    return INSTALLERS.some((i) => i.detect().installed);
+}
 export function App({ initialLanguage, skipWelcome }) {
     const { exit } = useApp();
     const [language, setLanguage] = useState(initialLanguage);
@@ -22,6 +33,17 @@ export function App({ initialLanguage, skipWelcome }) {
     const backToMenu = () => {
         setScreen({ kind: 'menu' });
     };
+    /* When the user picks Register from the menu, we route to either the
+     * full picker or the empty state depending on whether any client is
+     * actually present. The detection runs at navigation time so a user
+     * that installs Claude in another terminal and comes back doesn't get
+     * stuck on the empty screen forever. */
+    const enterPickClient = () => {
+        if (anyClientDetected())
+            setScreen({ kind: 'pick-client' });
+        else
+            setScreen({ kind: 'empty-clients' });
+    };
     switch (screen.kind) {
         case 'welcome':
             return (_jsx(WelcomeScreen, { language: language, hideDismiss: screen.hideDismiss, onAccept: () => {
@@ -33,9 +55,18 @@ export function App({ initialLanguage, skipWelcome }) {
         case 'menu':
             return (_jsx(MainMenu, { language: language, onSelect: (action) => {
                     if (action === 'register')
-                        setScreen({ kind: 'pick-client' });
-                    else if (action === 'instructions')
-                        setScreen({ kind: 'agent-instructions' });
+                        enterPickClient();
+                    else if (action === 'instructions') {
+                        // If at least one client is outdated, auto-focus the first one
+                        // so the next Enter refreshes it. The lookup is cheap (three
+                        // file stats); doing it here keeps the navigation contract
+                        // out of the menu screen and away from the installer module.
+                        const firstOutdated = statusAll().find((r) => r.state.kind === 'installed-outdated');
+                        setScreen({
+                            kind: 'agent-instructions',
+                            initialCursorClient: firstOutdated?.client,
+                        });
+                    }
                     else if (action === 'permissions')
                         setScreen({ kind: 'permissions' });
                     else if (action === 'multiAgent')
@@ -63,6 +94,10 @@ export function App({ initialLanguage, skipWelcome }) {
                     const report = installFor(id);
                     setScreen({ kind: 'install-result', report });
                 }, onBack: backToMenu }));
+        case 'empty-clients':
+            return (_jsx(EmptyClientsView, { language: language, onRescan: enterPickClient, onOpenRepo: () => {
+                    openUrl(REPO_URL);
+                }, onBack: backToMenu }));
         case 'install-result':
             return _jsx(InstallResultView, { language: language, report: screen.report, onBack: backToMenu });
         case 'permissions':
@@ -85,7 +120,7 @@ export function App({ initialLanguage, skipWelcome }) {
         case 'about':
             return _jsx(AboutView, { language: language, onBack: backToMenu });
         case 'agent-instructions':
-            return _jsx(AgentInstructionsView, { language: language, onBack: backToMenu });
+            return (_jsx(AgentInstructionsView, { language: language, onBack: backToMenu, initialCursorClient: screen.initialCursorClient }));
     }
 }
 //# sourceMappingURL=app.js.map

package/dist/ui/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/ui/app.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/ui/app.tsx"],"names":[],"mappings":"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"}

package/dist/ui/components.d.ts

@@ -1,14 +1,26 @@
 import type { ReactNode } from 'react';
 interface FrameProps {
-    title: string;
-    footer: string;
+    title: ReactNode;
+    /** Footer slot — typically a <FooterKeys> from primitives, but plain
+     * strings are still accepted for the few screens that interleave help
+     * text into the footer. */
+    footer: ReactNode;
+    /** Right-aligned tag rendered next to the title — e.g. "PRIMARY",
+     * "v0.9.0 · EN · single-agent". */
+    badge?: ReactNode;
+    /** Override the border color. Defaults to gray; error screens pass red. */
+    borderColor?: string;
     children: ReactNode;
 }
-export declare function Frame({ title, footer, children }: FrameProps): import("react/jsx-runtime").JSX.Element;
+export declare function Frame({ title, footer, badge, borderColor, children }: FrameProps): import("react/jsx-runtime").JSX.Element;
 interface MenuItem<V extends string> {
     value: V;
     label: string;
     hint?: string;
+    /** Optional single-character hotkey marker — rendered as `[h]` before
+     * the label. Screens that wire hotkeys via useInput should set this so
+     * the visual cue and the keyboard handler stay in sync. */
+    hotkey?: string;
 }
 interface MenuProps<V extends string> {
     items: MenuItem<V>[];

package/dist/ui/components.js

@@ -1,27 +1,47 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
 import { INSTALLERS } from '../installers/index.js';
-export function Frame({ title, footer, children }) {
-    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "gray", paddingX: 1, children: [_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsx(Text, { color: "cyan", bold: true, children: title }), _jsx(StatusBar, {})] }), _jsx(Box, { flexDirection: "column", children: children }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", dimColor: true, children: footer }) })] }));
+import { COLORS, GLYPHS } from './tokens.js';
+import { StatusBar } from './primitives/index.js';
+export function Frame({ title, footer, badge, borderColor = 'gray', children }) {
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: borderColor, paddingX: 1, children: [_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: COLORS.heading, bold: true, children: title }), badge !== undefined && (_jsx(Box, { marginLeft: 2, flexGrow: 1, justifyContent: "flex-end", children: badge }))] }), _jsx(LiveStatusBar, {})] }), _jsx(Box, { flexDirection: "column", children: children }), _jsx(Box, { marginTop: 1, children: typeof footer === 'string' ? _jsx(FooterText, { text: footer }) : footer })] }));
 }
-function StatusBar() {
-    return (_jsx(Box, { children: INSTALLERS.map((inst, i) => {
-            const d = inst.detect();
-            const { color, label } = !d.installed
-                ? { color: 'gray', label: 'not detected' }
-                : d.registered
-                    ? { color: 'green', label: 'registered' }
-                    : { color: 'yellow', label: 'not registered' };
-            return (_jsx(Box, { marginRight: i === INSTALLERS.length - 1 ? 0 : 3, children: _jsxs(Text, { children: [_jsx(Text, { bold: true, children: inst.displayName }), _jsx(Text, { color: "gray", children: " \u00B7 " }), _jsx(Text, { color: color, children: label })] }) }, inst.id));
-        }) }));
+function FooterText({ text }) {
+    return (_jsx(Text, { color: COLORS.muted, dimColor: true, children: text }));
+}
+/* Project the installer registry into the StatusBar primitive's input
+ * shape. Held inside this module so the rest of the UI doesn't reach
+ * into INSTALLERS just to render the header. */
+function LiveStatusBar() {
+    const items = INSTALLERS.map((inst) => {
+        const d = inst.detect();
+        let state;
+        let label;
+        if (!d.installed) {
+            state = 'not detected';
+            label = 'not detected';
+        }
+        else if (d.registered) {
+            state = 'registered';
+            label = 'registered';
+        }
+        else {
+            state = 'not registered';
+            label = 'not registered';
+        }
+        return { name: inst.displayName, state, label };
+    });
+    return _jsx(StatusBar, { items: items });
 }
 /* Pure render of a vertical menu — the App owns the selectedIndex state and
  * the key handling (we don't pull in ink-select-input so we can colour and
- * format hints exactly the way we want). */
+ * format hints exactly the way we want). Items with a `hotkey` render a
+ * `[h]` marker before the label; the keyboard binding itself is set up by
+ * the screen's `useInput`. */
 export function Menu({ items, selectedIndex }) {
     return (_jsx(Box, { flexDirection: "column", children: items.map((item, i) => {
             const isSel = i === selectedIndex;
-            return (_jsxs(Box, { children: [_jsx(Text, { color: isSel ? 'cyan' : 'gray', children: isSel ? '❯ ' : '  ' }), _jsx(Text, { color: isSel ? 'white' : 'gray', bold: isSel, children: item.label }), item.hint && (_jsxs(Text, { color: "gray", dimColor: true, children: ['  ', item.hint] }))] }, item.value));
+            return (_jsxs(Box, { children: [_jsx(Text, { color: isSel ? COLORS.focus : COLORS.muted, children: isSel ? `${GLYPHS.cursor} ` : '  ' }), item.hotkey !== undefined && item.hotkey !== '' && (_jsxs(Text, { children: [_jsx(Text, { color: COLORS.muted, children: "[" }), _jsx(Text, { color: isSel ? COLORS.focus : COLORS.primary, bold: isSel, underline: true, children: item.hotkey }), _jsx(Text, { color: COLORS.muted, children: "] " })] })), _jsx(Text, { color: isSel ? 'white' : COLORS.muted, bold: isSel, children: item.label }), item.hint !== undefined && item.hint !== '' && (_jsxs(Text, { color: COLORS.muted, dimColor: true, children: ['  ', item.hint] }))] }, item.value));
         }) }));
 }
 //# sourceMappingURL=components.js.map

package/dist/ui/components.js.map

@@ -1 +1 @@
-{"version":3,"file":"components.js","sourceRoot":"","sources":["../../src/ui/components.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,KAAK,CAAC;AAEhC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAapD,MAAM,UAAU,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAc;IAC3D,OAAO,CACL,MAAC,GAAG,IAAC,aAAa,EAAC,QAAQ,EAAC,WAAW,EAAC,OAAO,EAAC,WAAW,EAAC,MAAM,EAAC,QAAQ,EAAE,CAAC,aAC5E,MAAC,GAAG,IAAC,aAAa,EAAC,QAAQ,EAAC,YAAY,EAAE,CAAC,aACzC,KAAC,IAAI,IAAC,KAAK,EAAC,MAAM,EAAC,IAAI,kBACpB,KAAK,GACD,EACP,KAAC,SAAS,KAAG,IACT,EACN,KAAC,GAAG,IAAC,aAAa,EAAC,QAAQ,YAAE,QAAQ,GAAO,EAC5C,KAAC,GAAG,IAAC,SAAS,EAAE,CAAC,YACf,KAAC,IAAI,IAAC,KAAK,EAAC,MAAM,EAAC,QAAQ,kBACxB,MAAM,GACF,GACH,IACF,CACP,CAAC;AACJ,CAAC;AAED,SAAS,SAAS;IAChB,OAAO,CACL,KAAC,GAAG,cACD,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;YAC1B,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACxB,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,SAAS;gBACnC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE;gBAC1C,CAAC,CAAC,CAAC,CAAC,UAAU;oBACZ,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE;oBACzC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;YACnD,OAAO,CACL,KAAC,GAAG,IAAe,WAAW,EAAE,CAAC,KAAK,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YACjE,MAAC,IAAI,eACH,KAAC,IAAI,IAAC,IAAI,kBAAE,IAAI,CAAC,WAAW,GAAQ,EACpC,KAAC,IAAI,IAAC,KAAK,EAAC,MAAM,yBAAW,EAC7B,KAAC,IAAI,IAAC,KAAK,EAAE,KAAK,YAAG,KAAK,GAAQ,IAC7B,IALC,IAAI,CAAC,EAAE,CAMX,CACP,CAAC;QACJ,CAAC,CAAC,GACE,CACP,CAAC;AACJ,CAAC;AAaD;;4CAE4C;AAC5C,MAAM,UAAU,IAAI,CAAmB,EAAE,KAAK,EAAE,aAAa,EAAgB;IAC3E,OAAO,CACL,KAAC,GAAG,IAAC,aAAa,EAAC,QAAQ,YACxB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;YACrB,MAAM,KAAK,GAAG,CAAC,KAAK,aAAa,CAAC;YAClC,OAAO,CACL,MAAC,GAAG,eACF,KAAC,IAAI,IAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,YAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAQ,EAClE,KAAC,IAAI,IAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,YAC/C,IAAI,CAAC,KAAK,GACN,EACN,IAAI,CAAC,IAAI,IAAI,CACZ,MAAC,IAAI,IAAC,KAAK,EAAC,MAAM,EAAC,QAAQ,mBACxB,IAAI,EACJ,IAAI,CAAC,IAAI,IACL,CACR,KAVO,IAAI,CAAC,KAAK,CAWd,CACP,CAAC;QACJ,CAAC,CAAC,GACE,CACP,CAAC;AACJ,CAAC"}
+{"version":3,"file":"components.js","sourceRoot":"","sources":["../../src/ui/components.tsx"],"names":[],"mappings":"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"}

package/dist/ui/hooks/use-update-check.d.ts

@@ -0,0 +1,16 @@
+export interface UpdateCheckState {
+    /** Latest version on the npm registry, or null when we have not been
+     * able to fetch it (offline, registry down, first-call still in flight). */
+    latest: string | null;
+    /** True only when latest > current. The banner consumer renders only
+     * when this is true, so failures collapse to "no banner". */
+    isNewer: boolean;
+}
+interface HookOptions {
+    /** Override the underlying check call. Tests inject a stub here. */
+    runCheck?: () => Promise<UpdateCheckState>;
+    /** Override the interval. Tests pass a tiny value to fast-forward. */
+    intervalMs?: number;
+}
+export declare function useBackgroundUpdateCheck(opts?: HookOptions): UpdateCheckState;
+export {};

package/dist/ui/hooks/use-update-check.js

@@ -0,0 +1,48 @@
+import { useEffect, useState } from 'react';
+import { checkForUpdates } from '../../commands/update-check.js';
+/**
+ * React hook that runs a background update check on mount and again every
+ * six hours while the TUI is open. The lookup is silent on failure — when
+ * the npm registry is unreachable the hook simply returns null, which the
+ * banner consumer interprets as "no banner".
+ *
+ * The 6h cadence matches the on-disk cache TTL in `commands/update-check`
+ * so the cheap path (cache hit) is the one that actually fires within a
+ * single TUI session.
+ *
+ * A test seam (`runCheck`) lets the unit suite inject a synthetic check
+ * function — see `use-update-check.test.tsx`. Production callers should
+ * leave it undefined.
+ */
+const SIX_HOURS_MS = 6 * 60 * 60 * 1000;
+export function useBackgroundUpdateCheck(opts = {}) {
+    const { runCheck, intervalMs = SIX_HOURS_MS } = opts;
+    const [state, setState] = useState({ latest: null, isNewer: false });
+    useEffect(() => {
+        let cancelled = false;
+        const doCheck = async () => {
+            try {
+                const next = runCheck
+                    ? await runCheck()
+                    : await checkForUpdates().then((r) => ({ latest: r.latest, isNewer: r.isNewer }));
+                if (!cancelled)
+                    setState(next);
+            }
+            catch {
+                // Passive banner — failure is silent. Leave the previous state in
+                // place (so a stale-but-still-useful "update available" survives
+                // a transient network hiccup).
+            }
+        };
+        void doCheck();
+        const timer = setInterval(() => {
+            void doCheck();
+        }, intervalMs);
+        return () => {
+            cancelled = true;
+            clearInterval(timer);
+        };
+    }, [runCheck, intervalMs]);
+    return state;
+}
+//# sourceMappingURL=use-update-check.js.map

package/dist/ui/hooks/use-update-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-update-check.js","sourceRoot":"","sources":["../../../src/ui/hooks/use-update-check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEjE;;;;;;;;;;;;;GAaG;AAEH,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAkBxC,MAAM,UAAU,wBAAwB,CAAC,OAAoB,EAAE;IAC7D,MAAM,EAAE,QAAQ,EAAE,UAAU,GAAG,YAAY,EAAE,GAAG,IAAI,CAAC;IACrD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAmB,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IAEvF,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,MAAM,OAAO,GAAG,KAAK,IAAmB,EAAE;YACxC,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,QAAQ;oBACnB,CAAC,CAAC,MAAM,QAAQ,EAAE;oBAClB,CAAC,CAAC,MAAM,eAAe,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;gBACpF,IAAI,CAAC,SAAS;oBAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;YACjC,CAAC;YAAC,MAAM,CAAC;gBACP,kEAAkE;gBAClE,iEAAiE;gBACjE,+BAA+B;YACjC,CAAC;QACH,CAAC,CAAC;QACF,KAAK,OAAO,EAAE,CAAC;QACf,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC7B,KAAK,OAAO,EAAE,CAAC;QACjB,CAAC,EAAE,UAAU,CAAC,CAAC;QACf,OAAO,GAAG,EAAE;YACV,SAAS,GAAG,IAAI,CAAC;YACjB,aAAa,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC;IAE3B,OAAO,KAAK,CAAC;AACf,CAAC"}