docs: strengthen agent onboarding directive for UX toolkit

GEMINI.md

@@ -4,86 +4,53 @@ Gemini CLI is an open-source AI agent that brings the power of Gemini directly
 into the terminal. It is designed to be a terminal-first, extensible, and
 powerful tool for developers.
 
-## Project Overview
+## 🚨 Directive for AI Agents (Read First)
 
-- **Purpose:** Provide a seamless terminal interface for Gemini models,
-  supporting code understanding, generation, automation, and integration via MCP
-  (Model Context Protocol).
-- **Main Technologies:**
-  - **Runtime:** Node.js (>=20.0.0, recommended ~20.19.0 for development)
-  - **Language:** TypeScript
-  - **UI Framework:** React (using [Ink](https://github.com/vadimdemedes/ink)
-    for CLI rendering)
-  - **Testing:** Vitest
-  - **Bundling:** esbuild
-  - **Linting/Formatting:** ESLint, Prettier
-- **Architecture:** Monorepo structure using npm workspaces.
-  - `packages/cli`: User-facing terminal UI, input processing, and display
-    rendering.
-  - `packages/core`: Backend logic, Gemini API orchestration, prompt
-    construction, and tool execution.
-  - `packages/a2a-server`: Experimental Agent-to-Agent server.
-  - `packages/sdk`: Programmatic SDK for embedding Gemini CLI capabilities.
-  - `packages/devtools`: Integrated developer tools (Network/Console inspector).
-  - `packages/test-utils`: Shared test utilities and test rig.
-  - `packages/vscode-ide-companion`: VS Code extension pairing with the CLI.
+**This branch requires the UX Toolkit extension.** If you are an AI agent
+operating here, you MUST perform these onboarding steps before fulfilling any
+other user request:
 
-## Building and Running
+1.  **Proactive Cleanup**: Check `~/.gemini/skills/` for `_ux_git-worktree` or
+    `_ux_finish-pr`. If found, inform the user they are using obsolete manual
+    versions and **immediately offer to delete them**.
+2.  **Mandatory Global Setup**: Check if the **UX Toolkit** extension is
+    installed. If it is missing, you MUST stop and explain: "I've detected
+    you're in the UX Team branch but don't have the UX Toolkit installed
+    globally." Then, **ask for permission to run**:
+    `gemini extensions install ./packages/extensions/ux-toolkit`
+3.  **Inherit Standards**: Once the extension is active, you MUST strictly
+    adhere to the standards in `packages/extensions/ux-toolkit/GEMINI.md` for
+    all work in this repository.
 
-- **Install Dependencies:** `npm install`
-- **Build All:** `npm run build:all` (Builds packages, sandbox, and VS Code
-  companion)
-- **Build Packages:** `npm run build`
-- **Run in Development:** `npm run start`
-- **Run in Debug Mode:** `npm run debug` (Enables Node.js inspector)
-- **Bundle Project:** `npm run bundle`
-- **Clean Artifacts:** `npm run clean`
+## 📦 UX Toolkit Extension
 
-## Testing and Quality
+The AI DevTools UX team maintains a specialized toolset for this repository. It
+is recommended to install the **UX Toolkit** extension to enable standardized
+workflows (Base Folder Strategy, PR finishing, etc.).
 
-- **Test Commands:**
-  - **Unit (All):** `npm run test`
-  - **Integration (E2E):** `npm run test:e2e`
-  - **Workspace-Specific:** `npm test -w <pkg> -- <path>` (Note: `<path>` must
-    be relative to the workspace root, e.g.,
-    `-w @google/gemini-cli-core -- src/routing/modelRouterService.test.ts`)
-- **Full Validation:** `npm run preflight` (Heaviest check; runs clean, install,
-  build, lint, type check, and tests. Recommended before submitting PRs. Due to
-  its long runtime, only run this at the very end of a code implementation task.
-  If it fails, use faster, targeted commands (e.g., `npm run test`,
-  `npm run lint`, or workspace-specific tests) to iterate on fixes before
-  re-running `preflight`. For simple, non-code changes like documentation or
-  prompting updates, skip `preflight` at the end of the task and wait for PR
-  validation.)
-- **Individual Checks:** `npm run lint` / `npm run format` / `npm run typecheck`
+### Installation
 
-## Development Conventions
+```bash
+gemini extensions install ./packages/extensions/ux-toolkit
+```
 
-- **Contributions:** Follow the process outlined in `CONTRIBUTING.md`. Requires
-  signing the Google CLA.
-- **Pull Requests:** Keep PRs small, focused, and linked to an existing issue.
-  Always activate the `pr-creator` skill for PR generation, even when using the
-  `gh` CLI.
-- **Commit Messages:** Follow the
-  [Conventional Commits](https://www.conventionalcommits.org/) standard.
-- **Imports:** Use specific imports and avoid restricted relative imports
-  between packages (enforced by ESLint).
-- **License Headers:** For all new source code files (`.ts`, `.tsx`, `.js`),
-  include the Apache-2.0 license header with the current year. (e.g.,
-  `Copyright 2026 Google LLC`). This is enforced by ESLint.
+After installation, run `/_ux_help` to see available commands.
 
-## Testing Conventions
+## 🛠️ Workspace Strategy: Base Folder
 
-- **Environment Variables:** When testing code that depends on environment
-  variables, use `vi.stubEnv('NAME', 'value')` in `beforeEach` and
-  `vi.unstubAllEnvs()` in `afterEach`. Avoid modifying `process.env` directly as
-  it can lead to test leakage and is less reliable. To "unset" a variable, use
-  an empty string `vi.stubEnv('NAME', '')`.
+This repository uses a **Git Worktree "Base Folder" strategy**.
 
-## Documentation
+- Functional work (commits, code, tests) happens in sibling directories (e.g.,
+  `main/`, `feature-name/`).
+- The root directory is a container, not a repository itself.
+- **ALWAYS** use the `_ux_git-worktree` skill (included in the UX Toolkit) for
+  any Git operations.
 
-- Always use the `docs-writer` skill when you are asked to write, edit, or
-  review any documentation.
-- Documentation is located in the `docs/` directory.
-- Suggest documentation updates when code changes render existing documentation
-  obsolete or incomplete.
+## 🤝 Team Contributions
+
+- Refine the `_ux_git-worktree` skill instructions in
+  `packages/extensions/ux-toolkit/skills/_ux_git-worktree/SKILL.md`.
+- Refine the `_ux_finish-pr` skill instructions in
+  `packages/extensions/ux-toolkit/skills/_ux_finish-pr/SKILL.md`.
+- All changes should be committed directly to this branch
+  (`feature/gemini-cli-ux-team-skills`).

README.md

@@ -115,6 +115,16 @@ npm install -g @google/gemini-cli@nightly
 
 ### Automation & Integration
 
+- **UX Toolkit Extension**: This branch introduces a formal extension for the AI
+  DevTools UX team. Install it to enable specialized workflows: \`gemini
+  extensions install ./packages/extensions/ux-toolkit\`
+  - **\_ux_git-worktree**: Manage Git Worktrees using the "Base Folder
+    Strategy".
+  - **\_ux_finish-pr**: Co-author assistant for authors to cross the finish line
+    with UX polish and CI fixes.
+  - **\_ux_designer**: Lead UX Designer expert to review React/Ink components
+    against the v1.0 Design Principles (Density, Progressive Disclosure, State).
+  - **\_ux_help**: Show the welcome guide and documentation.
 - Automate operational tasks like querying pull requests or handling complex
   rebases
 - Use MCP servers to connect new capabilities, including

packages/a2a-server/src/agent/task.ts

@@ -880,9 +880,7 @@ export class Task {
     if (
       part.kind !== 'data' ||
       !part.data ||
-      // eslint-disable-next-line no-restricted-syntax
       typeof part.data['callId'] !== 'string' ||
-      // eslint-disable-next-line no-restricted-syntax
       typeof part.data['outcome'] !== 'string'
     ) {
       return false;

packages/cli/src/commands/hooks/migrate.ts

@@ -79,7 +79,7 @@ function migrateClaudeHook(claudeHook: unknown): unknown {
     migrated['command'] = hook['command'];
 
     // Replace CLAUDE_PROJECT_DIR with GEMINI_PROJECT_DIR in command
-    // eslint-disable-next-line no-restricted-syntax
+
     if (typeof migrated['command'] === 'string') {
       migrated['command'] = migrated['command'].replace(
         /\$CLAUDE_PROJECT_DIR/g,
@@ -94,7 +94,7 @@ function migrateClaudeHook(claudeHook: unknown): unknown {
   }
 
   // Map timeout field (Claude uses seconds, Gemini uses seconds)
-  // eslint-disable-next-line no-restricted-syntax
+
   if ('timeout' in hook && typeof hook['timeout'] === 'number') {
     migrated['timeout'] = hook['timeout'];
   }
@@ -142,7 +142,6 @@ function migrateClaudeHooks(claudeConfig: unknown): Record<string, unknown> {
       // Transform matcher
       if (
         'matcher' in definition &&
-        // eslint-disable-next-line no-restricted-syntax
         typeof definition['matcher'] === 'string'
       ) {
         migratedDef['matcher'] = transformMatcher(definition['matcher']);

packages/cli/src/test-utils/AppRig.tsx

@@ -280,14 +280,14 @@ export class AppRig {
   }
 
   private stubRefreshAuth() {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const gcConfig = this.config as any;
     gcConfig.refreshAuth = async (authMethod: AuthType) => {
       gcConfig.modelAvailabilityService.reset();
 
       const newContentGeneratorConfig = {
         authType: authMethod,
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+
         proxy: gcConfig.getProxy(),
         apiKey: process.env['GEMINI_API_KEY'] || 'test-api-key',
       };
@@ -456,7 +456,7 @@ export class AppRig {
     const actualToolName = toolName === '*' ? undefined : toolName;
     this.config
       .getPolicyEngine()
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+
       .removeRulesForTool(actualToolName as string, source);
     this.breakpointTools.delete(toolName);
   }
@@ -729,7 +729,7 @@ export class AppRig {
         .getGeminiClient()
         ?.getChatRecordingService();
       if (recordingService) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-type-assertion
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         (recordingService as any).conversationFile = null;
       }
     }
@@ -749,7 +749,7 @@ export class AppRig {
     MockShellExecutionService.reset();
     ideContextStore.clear();
     // Forcefully clear IdeClient singleton promise
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-type-assertion
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (IdeClient as any).instancePromise = null;
     vi.clearAllMocks();
 

packages/cli/src/test-utils/customMatchers.ts

@@ -79,7 +79,7 @@ export async function toMatchSvgSnapshot(
 }
 
 function toHaveOnlyValidCharacters(this: Assertion, buffer: TextBuffer) {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-type-assertion, @typescript-eslint/no-unsafe-assignment
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const { isNot } = this as any;
   let pass = true;
   const invalidLines: Array<{ line: number; content: string }> = [];
@@ -108,7 +108,6 @@ function toHaveOnlyValidCharacters(this: Assertion, buffer: TextBuffer) {
   };
 }
 
-// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
 expect.extend({
   toHaveOnlyValidCharacters,
   toMatchSvgSnapshot,

packages/cli/src/test-utils/mockCommandContext.ts

@@ -37,14 +37,14 @@ export const createMockCommandContext = (
     },
     services: {
       config: null,
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+
       settings: {
         merged: defaultMergedSettings,
         setValue: vi.fn(),
         forScope: vi.fn().mockReturnValue({ settings: {} }),
       } as unknown as LoadedSettings,
       git: undefined as GitService | undefined,
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion, @typescript-eslint/no-unsafe-assignment
+
       logger: {
         log: vi.fn(),
         logMessage: vi.fn(),
@@ -53,7 +53,7 @@ export const createMockCommandContext = (
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
       } as any, // Cast because Logger is a class.
     },
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion, @typescript-eslint/no-unsafe-assignment
+
     ui: {
       addItem: vi.fn(),
       clear: vi.fn(),
@@ -72,7 +72,7 @@ export const createMockCommandContext = (
     } as any,
     session: {
       sessionShellAllowlist: new Set<string>(),
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+
       stats: {
         sessionStartTime: new Date(),
         lastPromptTokenCount: 0,
@@ -93,14 +93,12 @@ export const createMockCommandContext = (
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const merge = (target: any, source: any): any => {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
     const output = { ...target };
 
     for (const key in source) {
       if (Object.prototype.hasOwnProperty.call(source, key)) {
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
         const sourceValue = source[key];
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+
         const targetValue = output[key];
 
         if (
@@ -108,11 +106,10 @@ export const createMockCommandContext = (
           Object.prototype.toString.call(sourceValue) === '[object Object]' &&
           Object.prototype.toString.call(targetValue) === '[object Object]'
         ) {
-          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
           output[key] = merge(targetValue, sourceValue);
         } else {
           // If not, we do a direct assignment. This preserves Date objects and others.
-          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+
           output[key] = sourceValue;
         }
       }
@@ -120,6 +117,5 @@ export const createMockCommandContext = (
     return output;
   };
 
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
   return merge(defaultMocks, overrides);
 };

packages/cli/src/test-utils/render.tsx

@@ -416,11 +416,10 @@ export const render = (
   stdout.clear();
   act(() => {
     instance = inkRenderDirect(tree, {
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
       stdout: stdout as unknown as NodeJS.WriteStream,
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+
       stderr: stderr as unknown as NodeJS.WriteStream,
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+
       stdin: stdin as unknown as NodeJS.ReadStream,
       debug: false,
       exitOnCtrlC: false,
@@ -499,7 +498,6 @@ const getMockConfigInternal = (): Config => {
   return mockConfigInternal;
 };
 
-// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
 const configProxy = new Proxy({} as Config, {
   get(_target, prop) {
     if (prop === 'getTargetDir') {
@@ -526,7 +524,6 @@ const configProxy = new Proxy({} as Config, {
     }
     const internal = getMockConfigInternal();
     if (prop in internal) {
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
       return internal[prop as keyof typeof internal];
     }
     throw new Error(`mockConfig does not have property ${String(prop)}`);
@@ -657,7 +654,7 @@ export const renderWithProviders = (
     uiState: providedUiState,
     width,
     mouseEventsEnabled = false,
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+
     config = configProxy as unknown as Config,
     useAlternateBuffer = true,
     uiActions,
@@ -685,20 +682,17 @@ export const renderWithProviders = (
     button?: 0 | 1 | 2,
   ) => Promise<void>;
 } => {
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
   const baseState: UIState = new Proxy(
     { ...baseMockUiState, ...providedUiState },
     {
       get(target, prop) {
         if (prop in target) {
-          // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
           return target[prop as keyof typeof target];
         }
         // For properties not in the base mock or provided state,
         // we'll check the original proxy to see if it's a defined but
         // unprovided property, and if not, throw.
         if (prop in baseMockUiState) {
-          // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
           return baseMockUiState[prop as keyof typeof baseMockUiState];
         }
         throw new Error(`mockUiState does not have property ${String(prop)}`);
@@ -736,7 +730,7 @@ export const renderWithProviders = (
         if (prop === 'getUseAlternateBuffer') {
           return () => useAlternateBuffer;
         }
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+
         return Reflect.get(target, prop, receiver);
       },
     });
@@ -847,9 +841,8 @@ export function renderHook<Result, Props>(
   waitUntilReady: () => Promise<void>;
   generateSvg: () => string;
 } {
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
   const result = { current: undefined as unknown as Result };
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+
   let currentProps = options?.initialProps as Props;
 
   function TestComponent({
@@ -884,7 +877,6 @@ export function renderHook<Result, Props>(
 
   function rerender(props?: Props) {
     if (arguments.length > 0) {
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
       currentProps = props as Props;
     }
     act(() => {
@@ -920,7 +912,6 @@ export function renderHookWithProviders<Result, Props>(
   waitUntilReady: () => Promise<void>;
   generateSvg: () => string;
 } {
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
   const result = { current: undefined as unknown as Result };
 
   let setPropsFn: ((props: Props) => void) | undefined;
@@ -942,7 +933,7 @@ export function renderHookWithProviders<Result, Props>(
   act(() => {
     renderResult = renderWithProviders(
       <Wrapper>
-        {/* eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion */}
+        {}
         <TestComponent initialProps={options.initialProps as Props} />
       </Wrapper>,
       options,
@@ -952,7 +943,6 @@ export function renderHookWithProviders<Result, Props>(
   function rerender(newProps?: Props) {
     act(() => {
       if (arguments.length > 0 && setPropsFn) {
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
         setPropsFn(newProps as Props);
       } else if (forceUpdateFn) {
         forceUpdateFn();

packages/cli/src/test-utils/settings.ts

@@ -46,23 +46,22 @@ export const createMockSettings = (
     workspace,
     isTrusted,
     errors,
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+
     merged: mergedOverride,
     ...settingsOverrides
   } = overrides;
 
   const loaded = new LoadedSettings(
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
     (system as any) || { path: '', settings: {}, originalSettings: {} },
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+
     (systemDefaults as any) || { path: '', settings: {}, originalSettings: {} },
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+
     (user as any) || {
       path: '',
       settings: settingsOverrides,
       originalSettings: settingsOverrides,
     },
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+
     (workspace as any) || { path: '', settings: {}, originalSettings: {} },
     isTrusted ?? true,
     errors || [],
@@ -76,7 +75,6 @@ export const createMockSettings = (
   // Assign any function overrides (e.g., vi.fn() for methods)
   for (const key in overrides) {
     if (typeof overrides[key] === 'function') {
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion, @typescript-eslint/no-unsafe-assignment
       (loaded as any)[key] = overrides[key];
     }
   }

packages/cli/src/ui/hooks/slashCommandProcessor.ts

@@ -505,9 +505,7 @@ export const useSlashCommandProcessor = (
                       const props = result.props as Record<string, unknown>;
                       if (
                         !props ||
-                        // eslint-disable-next-line no-restricted-syntax
                         typeof props['name'] !== 'string' ||
-                        // eslint-disable-next-line no-restricted-syntax
                         typeof props['displayName'] !== 'string' ||
                         !props['definition']
                       ) {

packages/core/src/hooks/hookAggregator.ts

@@ -355,7 +355,6 @@ export class HookAggregator {
     // Extract additionalContext from various hook types
     if (
       'additionalContext' in specific &&
-      // eslint-disable-next-line no-restricted-syntax
       typeof specific['additionalContext'] === 'string'
     ) {
       contexts.push(specific['additionalContext']);

packages/core/src/services/chatCompressionService.ts

@@ -156,13 +156,11 @@ async function truncateHistoryToBudget(
           } else if (responseObj && typeof responseObj === 'object') {
             if (
               'output' in responseObj &&
-              // eslint-disable-next-line no-restricted-syntax
               typeof responseObj['output'] === 'string'
             ) {
               contentStr = responseObj['output'];
             } else if (
               'content' in responseObj &&
-              // eslint-disable-next-line no-restricted-syntax
               typeof responseObj['content'] === 'string'
             ) {
               contentStr = responseObj['content'];

packages/core/src/services/loopDetectionService.ts

@@ -584,12 +584,10 @@ export class LoopDetectionService {
     }
 
     const flashConfidence =
-      // eslint-disable-next-line no-restricted-syntax
       typeof flashResult['unproductive_state_confidence'] === 'number'
         ? flashResult['unproductive_state_confidence']
         : 0;
     const flashAnalysis =
-      // eslint-disable-next-line no-restricted-syntax
       typeof flashResult['unproductive_state_analysis'] === 'string'
         ? flashResult['unproductive_state_analysis']
         : '';
@@ -636,13 +634,11 @@ export class LoopDetectionService {
 
     const mainModelConfidence =
       mainModelResult &&
-      // eslint-disable-next-line no-restricted-syntax
       typeof mainModelResult['unproductive_state_confidence'] === 'number'
         ? mainModelResult['unproductive_state_confidence']
         : 0;
     const mainModelAnalysis =
       mainModelResult &&
-      // eslint-disable-next-line no-restricted-syntax
       typeof mainModelResult['unproductive_state_analysis'] === 'string'
         ? mainModelResult['unproductive_state_analysis']
         : undefined;
@@ -691,7 +687,6 @@ export class LoopDetectionService {
 
       if (
         result &&
-        // eslint-disable-next-line no-restricted-syntax
         typeof result['unproductive_state_confidence'] === 'number'
       ) {
         return result;

packages/core/src/telemetry/semantic.ts

@@ -63,7 +63,6 @@ function getStringReferences(parts: AnyPart[]): StringReference[] {
         });
       }
     } else if (part instanceof GenericPart) {
-      // eslint-disable-next-line no-restricted-syntax
       if (part.type === 'executableCode' && typeof part['code'] === 'string') {
         refs.push({
           // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
@@ -74,7 +73,6 @@ function getStringReferences(parts: AnyPart[]): StringReference[] {
         });
       } else if (
         part.type === 'codeExecutionResult' &&
-        // eslint-disable-next-line no-restricted-syntax
         typeof part['output'] === 'string'
       ) {
         refs.push({

packages/core/src/test-utils/mock-message-bus.ts

@@ -62,7 +62,7 @@ export class MockMessageBus {
       if (!this.subscriptions.has(type)) {
         this.subscriptions.set(type, new Set());
       }
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+
       this.subscriptions.get(type)!.add(listener as (message: Message) => void);
     },
   );
@@ -74,7 +74,6 @@ export class MockMessageBus {
     <T extends Message>(type: T['type'], listener: (message: T) => void) => {
       const listeners = this.subscriptions.get(type);
       if (listeners) {
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
         listeners.delete(listener as (message: Message) => void);
       }
     },
@@ -103,7 +102,6 @@ export class MockMessageBus {
  * Create a mock MessageBus for testing
  */
 export function createMockMessageBus(): MessageBus {
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
   return new MockMessageBus() as unknown as MessageBus;
 }
 
@@ -113,6 +111,5 @@ export function createMockMessageBus(): MessageBus {
 export function getMockMessageBusInstance(
   messageBus: MessageBus,
 ): MockMessageBus {
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
   return messageBus as unknown as MockMessageBus;
 }

packages/core/src/test-utils/mockWorkspaceContext.ts

@@ -19,7 +19,6 @@ export function createMockWorkspaceContext(
 ): WorkspaceContext {
   const allDirs = [rootDir, ...additionalDirs];
 
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
   const mockWorkspaceContext = {
     addDirectory: vi.fn(),
     getDirectories: vi.fn().mockReturnValue(allDirs),

packages/core/src/tools/mcp-tool.ts

@@ -108,7 +108,7 @@ export function isMcpToolAnnotation(
   return (
     typeof annotation === 'object' &&
     annotation !== null &&
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion, no-restricted-syntax
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
     typeof (annotation as Record<string, unknown>)['_serverName'] === 'string'
   );
 }

packages/core/src/utils/editCorrector.ts

@@ -112,7 +112,6 @@ Return ONLY the corrected string in the specified JSON format with the key 'corr
 
     if (
       result &&
-      // eslint-disable-next-line no-restricted-syntax
       typeof result['corrected_string_escaping'] === 'string' &&
       result['corrected_string_escaping'].length > 0
     ) {

packages/core/src/utils/googleErrors.ts

@@ -231,7 +231,7 @@ export function parseGoogleApiError(error: unknown): GoogleApiError | null {
             }
             // Basic structural check before casting.
             // Since the proto definitions are loose, we primarily rely on @type presence.
-            // eslint-disable-next-line no-restricted-syntax
+
             if (typeof detailObj['@type'] === 'string') {
               // We can just cast it; the consumer will have to switch on @type
               // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion

packages/core/src/utils/oauth-flow.ts

@@ -361,24 +361,20 @@ async function parseTokenEndpointResponse(
       data &&
       typeof data === 'object' &&
       'access_token' in data &&
-      // eslint-disable-next-line no-restricted-syntax
       typeof (data as Record<string, unknown>)['access_token'] === 'string'
     ) {
       const obj = data as Record<string, unknown>;
       const result: OAuthTokenResponse = {
         access_token: String(obj['access_token']),
         token_type:
-          // eslint-disable-next-line no-restricted-syntax
           typeof obj['token_type'] === 'string' ? obj['token_type'] : 'Bearer',
         expires_in:
-          // eslint-disable-next-line no-restricted-syntax
           typeof obj['expires_in'] === 'number' ? obj['expires_in'] : undefined,
         refresh_token:
-          // eslint-disable-next-line no-restricted-syntax
           typeof obj['refresh_token'] === 'string'
             ? obj['refresh_token']
             : undefined,
-        // eslint-disable-next-line no-restricted-syntax
+
         scope: typeof obj['scope'] === 'string' ? obj['scope'] : undefined,
       };
       return result;

packages/extensions/ux-toolkit/GEMINI.md

@@ -0,0 +1,25 @@
+# UX Toolkit: Extension Context
+
+This extension provides the specialized toolset for the AI DevTools UX team.
+When this extension is active, the agent must adhere to the following standards
+and workflows.
+
+## 🚨 Agent Directives
+
+1.  **Worktree Strategy**: Always prefer the **Base Folder Strategy**. Use
+    `_ux_git-worktree` to manage sibling directories for all tasks.
+2.  **PR Maintenance**: Use `_ux_finish-pr` to handle the final polish of pull
+    requests, ensuring all tests pass and snapshots are updated.
+3.  **UI Review**: Use `_ux_designer` to audit any new Ink/React components
+    against the v1.0 Design Principles (Density, Progressive Disclosure, State).
+4.  **UX Writing**: Use `_ux_string-reviewer` to ensure all user-facing strings
+    comply with project terminology and clarity rules.
+
+## Mandatory Workflow
+
+- **ALWAYS** use the `_ux_git-worktree` skill for branch management.
+- **ALWAYS** use the `_ux_finish-pr` skill for pull request maintenance.
+- Never use standard `git checkout -b`.
+- Use `worktree-manager.sh pr <number>` for semantic PR checkouts.
+- When operating in a worktree, ensure the primary `main/.git` path is included
+  in your trusted directories to bypass macOS sandbox restrictions.

packages/extensions/ux-toolkit/WELCOME.md

@@ -0,0 +1,40 @@
+# 🚀 Welcome to the UX Team "Global Toolbox"
+
+You have successfully installed the Gemini CLI UX power-ups!
+
+These tools are designed to help us sprint toward the **Gemini 1.0 Milestone**
+without fighting the CLI. They are "opinionated" and built specifically for the
+UX "Vibe Coding" workflow.
+
+## 🛠️ Your New Superpowers
+
+You now have four new commands available in your Gemini CLI session. Because
+they are synced globally, **you can use them on any branch.**
+
+- `/_ux_git-worktree` : Ditch nested branches! Use this to manage your tasks in
+  parallel sibling folders (Base Folder Strategy). It auto-runs `npm install`
+  for you!
+- `/_ux_finish-pr` : Your co-author assistant. It runs tests, updates snapshots,
+  fixes CI linting, and squashes your messy trial-and-error commits before
+  force-pushing.
+- `/_ux_designer` : Run this against your new React/Ink components to guarantee
+  they adhere to the v1.0 strict standards (Signal over Noise, Coherent State,
+  Density).
+- `/string-reviewer` : Audits UI text for strict adherence to the project
+  terminology.
+
+## 🧠 Why are we doing this?
+
+We are intentionally keeping these tools in a "floating" Draft PR branch rather
+than merging them to `main`. This isolation lets the UX team iterate at
+lightning speed on our tooling without polluting the main codebase for backend
+engineers.
+
+_(Note: We plan to migrate this entire toolbox into a formal **Gemini CLI
+Extension** in the near future!)_
+
+## 🏁 Get Started
+
+1. Open your terminal.
+2. Ensure you have run `/skills reload`.
+3. Try typing `/_ux_` to see your new tools in action!

packages/extensions/ux-toolkit/commands/ux-help.toml

@@ -0,0 +1,4 @@
+description = "Show the UX Toolkit welcome guide and documentation."
+prompt = """
+Read the welcome guide at \`packages/extensions/ux-toolkit/WELCOME.md\` and output its contents to the user.
+"""

packages/extensions/ux-toolkit/gemini-extension.json

@@ -0,0 +1,13 @@
+{
+  "name": "ux-toolkit",
+  "version": "1.0.0",
+  "description": "Specialized suite of UX development tools for the Gemini CLI team, including worktree management, PR finishing, and design auditing.",
+  "author": "AI DevTools UX Team",
+  "skills": [
+    "skills/_ux_git-worktree",
+    "skills/_ux_finish-pr",
+    "skills/_ux_designer",
+    "skills/_ux_string-reviewer"
+  ],
+  "commands": ["commands/ux-help.toml"]
+}

packages/extensions/ux-toolkit/skills/_ux_designer/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: _ux_designer
+description: Expert UX Designer for Gemini CLI. Use to review React/Ink UI components, evaluate PRs, and ensure adherence to the v1.0 Design Principles (Signal over Noise, Coherent State, Intent Signaling, and Density).
+---
+
+# UX Designer (Gemini CLI)
+
+You are the Lead UX Designer for the Gemini CLI. Your role is to ruthlessly review and enforce the **v1.0 Design Principles** on all React/Ink UI components and pull requests. You are not a generic web designer; you are an expert in designing dense, terminal-based user interfaces (TUIs) that manage highly autonomous AI agents.
+
+## Core V1.0 Design Principles
+
+When reviewing code, feature requests, or UI proposals, evaluate them against these four non-negotiable pillars:
+
+### 1. Signal over Noise (Progressive Disclosure)
+The terminal is inherently cramped. We must combat "visual noise" and "state confusion."
+- **Rule:** The UI must be collapsed by default. Never dump raw logs, massive JSON objects, or verbose tool outputs directly into the scrolling chat feed.
+- **Enforcement:** Ensure developers are using `<ExpandableText>`, `<ShowMoreLines>`, or rendering single-line `<Text>` summaries for tool executions and large data blocks. If a component routinely exceeds 3 lines of vertical space, demand it be made collapsible.
+
+### 2. Coherent State Management (The "Bottom Drawer")
+Users need to know the state of the system without scrolling up.
+- **Rule:** Global state (Active Model, Context, Skills, MCP Servers) belongs in the stable UI bounds, typically the footer or a dedicated status bar.
+- **Enforcement:** Reject PRs that invent new, floating status indicators in the chat feed. Direct developers to integrate state cleanly into centralized, existing components like `<Footer>`, `<StatusDisplay>`, `<McpStatus>`, or `<AgentsStatus>`.
+
+### 3. Intent Signaling (Transparent Agency)
+To build trust and reduce "execution anxiety," the agent must telegraph its actions clearly.
+- **Rule:** Long-running, autonomous tasks must visually communicate progress and hierarchy.
+- **Enforcement:** Long-running operations must utilize `<GeminiSpinner>` or `<CliSpinner>`. The status string must be deterministic and brief (e.g., "Scanning files..." not "Please wait while I scan the files"). Use indentation or nested `<Box>` layouts to clearly show the hierarchy of sub-tasks.
+
+### 4. Strategic Color & Density
+Color in a terminal is a scarce resource. It should be functional, not decorative.
+- **Rule:** Strip unnecessary colors. Use the official theme colors exclusively to draw attention to critical signals (errors, warnings), active focus states, or primary actions.
+- **Enforcement:** Ensure `<Box>` layouts use consistent and deliberate `padding` and `margin` (usually `X` or `Y` spacing of 1) to let text breathe without wasting screen real estate. Reject "rainbow" text or over-styled borders.
+
+## Workflow
+
+1. **Review Request:** When asked to review a component (e.g., `InputPrompt.tsx`), load the file and analyze its Ink layout and React state.
+2. **Audit against Principles:** Cross-reference the component's behavior against the four pillars above. Check the [Components Reference](./references/components.md) to ensure existing primitives are being utilized.
+3. **Actionable Feedback:** Provide specific, code-level feedback. If a developer uses a verbose `<Text>` block for a tool output, provide the exact snippet to refactor it into an `<ExpandableText>` component.
+
+Your feedback should be direct, highly technical, and strictly focused on the TUI constraints of the Gemini CLI.

packages/extensions/ux-toolkit/skills/_ux_designer/references/components.md

@@ -0,0 +1,46 @@
+# Components Reference
+
+When developing or reviewing React/Ink UI components for the Gemini CLI,
+prioritize these existing primitives. Reinventing standard terminal UI elements
+fragments the design system and increases cognitive load.
+
+## Core Layout & Typography
+
+- **`<Box>`**: The fundamental building block. Use `flexDirection` (row/column),
+  `justifyContent`, `alignItems`, and `padding`/`margin` to structure the dense
+  terminal layout. Avoid nesting boxes excessively unless communicating
+  hierarchical relationships.
+- **`<Text>`**: For all standard text rendering. Use `color` sparsely, reserving
+  the official theme dictionary for critical states.
+- **`<Newline>`**: Use sparingly within `<Text>`. Prefer `<Box>` margins for
+  structural spacing.
+
+## Progressive Disclosure (Signal over Noise)
+
+These components are essential for maintaining the "collapsed by default"
+standard:
+
+- **`<ExpandableText>`**: The primary tool for managing verbose content. Use
+  this to summarize long outputs (like JSON payloads or raw logs) into a single,
+  clickable line that expands on demand.
+- **`<ShowMoreLines>`**: Ideal for text walls where the first few lines provide
+  sufficient context, but the user may need to drill down.
+
+## Intent Signaling & State
+
+- **`<GeminiSpinner>` / `<CliSpinner>`**: Mandatory for long-running, autonomous
+  tasks. Pair with a deterministic, sub-5-word status string.
+- **`<StatusDisplay>`**: Use to reflect the core loop state (e.g.,
+  "Thinking...", "Waiting for input").
+- **`<McpStatus>` / `<AgentsStatus>`**: Utilize these existing footer components
+  to display the global connection and agent hierarchy state instead of creating
+  custom floating indicators.
+
+## Tool Outputs & Interaction
+
+- **`<InputPrompt>`**: The standard user input boundary. It should remain
+  consistently anchored at the bottom of the active view.
+- **`<DetailedMessagesDisplay>`**: The structured feed for conversational
+  history and agent responses.
+- **`<ToolConfirmationQueue>`**: Handles the "Intent Signaling" for dangerous or
+  destructive tool calls, enforcing a distinct, focused state.

packages/extensions/ux-toolkit/skills/_ux_finish-pr/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: _ux_finish-pr
+description: Expert PR maintenance with a focus on UX and functional polish. Use to check PR status, address feedback through interactive UX/functional review with the user, and fix failing CI checks.
+---
+
+# UX Finish PR
+
+You are a senior UX-focused co-author assistant, dedicated to helping the PR author cross the finish line. Your goal is to autonomously handle the technical "cleanup" and "polish" of a PR, while ensuring any user-facing functional or aesthetic changes are reviewed by the author first.
+
+## Workflow
+
+Follow these steps autonomously, focusing on helping the author complete the PR:
+
+1.  **Assess PR Readiness:**
+    -   Identify failing CI checks (lint, tests, builds) and diagnose their root causes.
+    -   Gather unresolved comments from reviewers.
+
+2.  **Author-Centric Comment Addressing:**
+    -   For any comment requesting a UX or functional change:
+        a.  Analyze the feedback and propose a specific technical solution.
+        b.  **Pause and share your proposal with the author.** Explain how it addresses the feedback and what the resulting UX will be.
+        c.  Wait for the author's directive to proceed.
+    -   Autonomously handle minor technical or non-user-facing feedback.
+
+3.  **Autonomous CI Fixes:**
+    -   Propose and apply fixes for linting or test failures.
+    -   **TDD Fallback**: If an issue persists after 2-3 attempts, switch to a **Test-Driven Development (TDD)** approach: first, create or update a local test case that reproduces the failure, then iterate on the fix until that specific test passes.
+    -   Verify fixes locally using project standards (e.g., `npm run lint`, `npm test -u` to update all snapshots).
+
+4.  **Final Cleanup & Update:**
+    -   Sync with the latest `main`: `git fetch origin main && git rebase origin/main`.
+    -   **Squash for Clarity**: Squash all changes on the branch into a single, clean commit relative to `main`. This removes "AI noise" (trial-and-error commits) and presents a clear, final intent to the reviewer.
+    -   **Mandatory Verification**: You MUST verify that ALL relevant tests pass locally (e.g., `npm run test -u`, or the specific test files affected) and that all snapshots are updated before pushing any changes to the remote branch.
+    -   Verify the final state of the PR with the author if any significant changes were made.
+    -   Force-push with lease: `git push origin HEAD --force-with-lease`.
+
+Always provide a direct link to the PR after each major update. Prioritize brevity and technical rationale in your communication.

packages/extensions/ux-toolkit/skills/_ux_git-worktree/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: _ux_git-worktree
+description: Manage Git Worktrees according to the "Base Folder Strategy". Use when the user wants to create branches, switch tasks, check out PRs, or manage parallel development environments.
+---
+
+# Git Worktree
+
+## Overview
+
+This skill manages the **Git Worktree "Base Folder" strategy**, ensuring that all functional work occurs in sibling sub-directories (e.g., `main/`, `feature-name/`) rather than nested branches. It prevents sandbox interference and enables parallel development.
+
+## Core Rules
+
+1.  **Enforced Hierarchy**: New tasks or branches MUST be created as sibling directories to `main/`.
+2.  **No Nesting**: Branches should never be created inside existing sub-folders.
+3.  **Metadata Pathing**: When operating in a worktree, always include the primary `main/.git` path in the trusted environment to bypass macOS sandbox restrictions.
+
+## Workflows
+
+### 1. Creating a New Task (Branch)
+
+When the user asks to "start a new task" or "create a branch":
+1.  Identify the base directory (the parent of `main/`).
+2.  Use `git worktree add ../<branch-name> -b <branch-name>` from within `main/`.
+3.  **Mandatory Prep**: Run `npm install` inside the new worktree directory to ensure all dependencies are resolved.
+4.  Instruct the user to move into the new directory and reload their session.
+
+### 2. Checking out a PR (Semantic Naming)
+
+When the user asks to "check out PR #123":
+1.  **NEVER** use standard `gh pr checkout` without a directory.
+2.  **ALWAYS** use the automation script: `./packages/extensions/ux-toolkit/skills/_ux_git-worktree/scripts/worktree-manager.sh pr 123`.
+3.  **Mandatory Prep**: Run `npm install` inside the new worktree directory to ensure all dependencies are resolved.
+4.  This script will automatically fetch the PR title and create a semantic directory name (e.g., `pr-123-fix-core-bug`).
+
+### 3. Committing Changes in a Worktree
+
+If operating in a sibling worktree (e.g., `feature-xyz/`):
+1.  Check for sandbox access to `../main/.git`.
+2.  If access is denied, use `/directory add ../main/.git` (if interactive) or suggest the `--include-directories` flag for the next launch.
+
+## Task-Based Guide
+
+### Managing Worktrees
+- **List Worktrees**: Run `git worktree list`.
+- **Semantic PR Checkout**: `worktree-manager.sh pr <number>`.
+- **Add Manual Worktree**: `git worktree add ../<dir> <branch>`.
+- **Remove Worktree**: `git worktree remove <dir>`.
+
+## Resources
+
+### references/architecture.md
+Technical details of the "Base Folder" standard.
+
+### scripts/worktree-manager.sh
+Automated wrapper for Git Worktree operations that handles sibling pathing, semantic PR naming, and metadata links.

packages/extensions/ux-toolkit/skills/_ux_git-worktree/references/architecture.md

@@ -0,0 +1,24 @@
+# Base Folder Strategy Architecture
+
+## Directory Layout
+
+```text
+/project-root/          <-- Container directory (Base Folder)
+├── main/               # Primary repository checkout (contains .git/)
+├── feature-alpha/      # Isolated worktree for feature 'alpha'
+├── bugfix-beta/        # Isolated worktree for bugfix 'beta'
+└── ...
+```
+
+## Shared Metadata
+
+All worktrees (`feature-alpha/`, `bugfix-beta/`, etc.) share the Git database
+located in `main/.git`. Git worktrees use a `.git` file (not a directory) that
+contains a pointer to the original metadata:
+`gitdir: /path/to/main/.git/worktrees/feature-alpha`
+
+## Sandbox Constraints (macOS)
+
+On macOS, the Seatbelt sandbox restricts write access to the worktree directory
+only. To perform Git operations (which modify `main/.git/worktrees/`), the agent
+requires explicit access to the `main/.git` path.

packages/extensions/ux-toolkit/skills/_ux_git-worktree/scripts/worktree-manager.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# worktree-manager.sh - Manage sibling worktrees for Gemini CLI
+
+set -e
+
+ACTION="${1}"
+NAME="${2}"
+BRANCH="${3}"
+
+BASE_DIR="$(pwd)"
+PARENT_DIR="$(dirname "${BASE_DIR}")"
+
+slugify() {
+    local input="${1}"
+    local slug
+    slug=$(echo "${input}" | iconv -t ascii//TRANSLIT)
+    slug=$(echo "${slug}" | tr -cd "[:alnum:] ")
+    slug=$(echo "${slug}" | tr "[:upper:]" "[:lower:]")
+    slug=$(echo "${slug}" | tr " " "-")
+    slug="${slug//--/-}"
+    slug=$(echo "${slug}" | cut -c 1-50)
+    echo "${slug}"
+}
+
+case "${ACTION}" in
+    "add")
+        if [[ -z "${NAME}" ]] || [[ -z "${BRANCH}" ]]; then
+            echo "Error: Usage: worktree-manager.sh add <dir-name> <branch-name>"
+            exit 1
+        fi
+        git worktree add "${PARENT_DIR}/${NAME}" "${BRANCH}"
+        echo "Success: Added worktree at ${PARENT_DIR}/${NAME} tracking branch ${BRANCH}"
+        ;;
+    "pr")
+        if [[ -z "${NAME}" ]]; then
+            echo "Error: Usage: worktree-manager.sh pr <pr-number>"
+            exit 1
+        fi
+        PR_NUMBER="${NAME}"
+        echo "Fetching PR details for #${PR_NUMBER}..."
+        
+        PR_DATA=$(gh pr view "${PR_NUMBER}" --json title,headRefName)
+        
+        PR_TITLE=$(echo "${PR_DATA}" | jq -r .title)
+        PR_BRANCH=$(echo "${PR_DATA}" | jq -r .headRefName)
+        
+        SLUG=$(slugify "${PR_TITLE}")
+        DIR_NAME="pr-${PR_NUMBER}-${SLUG}"
+        
+        echo "Creating semantic worktree: ${DIR_NAME}"
+        git worktree add "${PARENT_DIR}/${DIR_NAME}" "${PR_BRANCH}"
+        echo "Success: Added PR worktree at ${PARENT_DIR}/${DIR_NAME}"
+        ;;
+    "list")
+        git worktree list
+        ;;
+    "remove")
+        if [[ -z "${NAME}" ]]; then
+            echo "Error: Usage: worktree-manager.sh remove <dir-name>"
+            exit 1
+        fi
+        git worktree remove "${PARENT_DIR}/${NAME}"
+        echo "Success: Removed worktree ${PARENT_DIR}/${NAME}"
+        ;;
+    *)
+        echo "Error: Unknown action ${ACTION}"
+        exit 1
+        ;;
+esac

packages/extensions/ux-toolkit/skills/_ux_string-reviewer/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: _ux_string-reviewer
+description: >
+  Use this skill when asked to review text and user-facing strings within the codebase. It ensures that these strings follow rules on clarity,
+  usefulness, brevity and style.
+---
+
+# String Reviewer
+
+## Instructions
+
+Act as a Senior UX Writer. Look for user-facing strings that are too long,
+unclear, or inconsistent. This includes inline text, error messages, and other
+user-facing text.
+
+Do NOT automatically change strings without user approval. You must only suggest
+changes and do not attempt to rewrite them directly unless the user explicitly
+asks you to do so.
+
+## Core voice principles
+
+The system prioritizes deterministic clarity over conversational fluff. We
+provide telemetry, not etiquette, ensuring the user retains absolute agency..
+
+1. **Deterministic clarity:** Distinguish between certain system/service states
+   (Cloud Billing, IAM, the System) and probabilistic AI analysis (Gemini).
+2. **System transparency:** Replace "Loading..." with active technical telemetry
+   (e.g., Tracing stack traces...). Keep status updates under 5 words.
+3. **Front-loaded actionability:** Always use the [Goal] + [Action] pattern.
+   Lead with intent so users can scan left-to-right.
+4. **Agentic error recovery:** Every error must be a pivot point. Pair failures
+   with one-click recovery commands or suggested prompts.
+5. **Contextual humility:** Reserve disclaimers and "be careful" warnings for P0
+   (destructive/irreversible) tasks only. Stop warning-fatigue.
+
+## The writing checklist
+
+Use this checklist to audit UI strings and AI responses.
+
+### Identity and voice
+- **Eliminate the "I":** Remove all first-person pronouns (I, me, my, mine).
+- **Subject attribution:** Refer to the AI as Gemini and the infrastructure as
+  the - system or the CLI.
+- **Active voice:** Ensure the subject (Gemini or the system) is clearly
+  performing the action.
+- **Ownership rule:** Use the system for execution (doing) and Gemini for
+  analysis (thinking)
+
+### Structural scannability
+- **The skip test:** Do the first 3 words describe the user’s intent? If not,
+  rewrite.
+- **Goal-first sequence:** Use the template: [To Accomplish X] + [Do Y].
+- **The 5-word rule:** Keep status updates and loading states under 5 words.
+- **Telemetry over etiquette:** Remove polite filler (Please wait, Thank you,
+  Certainly). Replace with raw data or progress indicators.
+- **Micro-state cycles:** For tasks $> 3$ seconds, cycle through specific
+  sub-states (e.g., Parsing logs... ➔ Identifying patterns...) to show momentum.
+
+
+### Technical accuracy and humility
+- **Verb signal check:** Use deterministic verbs (is, will, must) for system
+  state/infrastructure.
+  - Use probabilistic verbs (suggests, appears, may, identifies) for AI output.
+- **No 100% certainty:** Never attribute absolute certainty to model-generated
+  content.
+- **Precision over fuzziness:** Use technical metrics (latency, tokens, compute) instead of "speed" or "cost."
+- **Instructional warnings:** Every warning must include a specific corrective action (e.g., "Perform a dry-run first" or "Review line 42").
+
+### Agentic error recovery
+- **The one-step rule:** Pair every error message with exactly one immediate
+  path to a fix (command, link, or prompt).
+- **Human-first:** Provide a human-readable explanation before machine error
+  codes (e.g., 404, 500).
+-  **Suggested prompts:** Offer specific text for the user to copy/click like
+   “Ask Gemini: 'Explain this port error.'”
+
+### Use consistent terminology
+
+Ensure all terminology aligns with the project [word
+list](./references/word-list.md). 
+
+If a string uses a term marked "do not use" or "use with caution," provide a
+correction based on the preferred terms.
+
+## Ensure consistent style for settings
+
+If `packages/cli/src/config/settingsSchema.ts` is modified, confirm labels and
+descriptions specifically follow the unique [Settings
+guidelines](./references/settings.md).
+
+## Output format
+When suggesting changes, always present your review using the following list
+format. Do not provide suggestions outside of this list..
+
+```
+1. **{Rationale/Principle Violated}**
+  - ❌ "{incorrect phrase}"
+  - ✅ `"{corrected phrase}"`
+```

packages/extensions/ux-toolkit/skills/_ux_string-reviewer/references/settings.md

@@ -0,0 +1,28 @@
+# Settings
+
+## Noun-First Labeling (Scannability)
+
+Labels must start with the subject of the setting, not the action. This allows
+users to scan for the feature they want to change.
+
+- **Rule:** `[Noun]` `[Attribute/Action]`
+- **Example:** `Show line numbers` becomes simply `Line numbers`
+
+## Positive Boolean Logic (Cognitive Ease)
+
+Eliminate "double negatives." Booleans should represent the presence of a
+feature, not its absence.
+
+- **Rule:** Replace `Disable {feature}` or `Hide {Feature}` with
+  `{Feature} enabled` or simply `{Feature}`.
+- **Example:** Change "Disable auto update" to "Auto update".
+- **Implementation:** Invert the boolean value in your config loader so true
+  always equals `On`
+
+## Verb Stripping (Brevity)
+
+Remove redundant leading verbs like "Enable," "Use," "Display," or "Show" unless
+they are part of a specific technical term.
+
+- **Rule**: If the label works without the verb, remove it
+- **Example**: Change `Enable prompt completion` to `Prompt completion`

packages/extensions/ux-toolkit/skills/_ux_string-reviewer/references/word-list.md

@@ -0,0 +1,61 @@
+## Terms
+
+### Preferred
+
+- Use **create** when a user is creating or setting up something.
+- Use **allow** instead of **may** to indicate that permission has been granted
+  to perform some action.
+- Use **canceled**, not **cancelled**.
+- Use **configure** to refer to the process of changing the attributes of a
+  feature, even if that includes turning on or off the feature.
+- Use **delete** when the action being performed is destructive.
+- Use **enable** for binary operations that turn a feature or API on. Use "turn
+  on" and "turn off" instead of "enable" and "disable" for other situations.
+- Use **key combination** to refer to pressing multiple keys simultaneously.
+- Use **key sequence** to refer to pressing multiple keys separately in order.
+- Use **modify** to refer to something that has changed vs obtaining the latest
+  version of something.
+- Use **remove** when the action being performed takes an item out of a larger
+  whole, but doesn't destroy the item itself.
+- Use **set up** as a verb. Use **setup** as a noun or adjective.
+- Use **show**. In general, use paired with **hide**.
+- Use **sign in**, **sign out** as a verb. Use **sign-in** or **sign-out** as a
+  noun or adjective.
+- Use **update** when you mean to obtain the latest version of something.
+- Use **want** instead of **like** or **would like**.
+
+#### Don't use
+
+- Don't use **etc.** It's redundant. To convey that a series is incomplete,
+  introduce it with "such as" instead.
+- Don't use **hostname**, use "host name" instead.
+- Don't use **in order to**. It's too formal. "Before you can" is usually better
+  in UI text.
+- Don't use **one or more**. Specify the quantity where possible. Use "at least
+  one" when the quantity is 1+ but you can't be sure of the number. Likewise,
+  use "at least one" when the user must choose a quantity of 1+.
+- Don't use the terms **log in**, **log on**, **login**, **logout** or **log
+  out**.
+- Don't use **like** or **would you like**. Use **want** instead. Better yet,
+  rephrase so that it's not referring to the user's emotional state, but rather
+  what is required.
+
+#### Use with caution
+
+- Avoid using **leverage**, especially as a verb. "Leverage" is considered a
+  buzzword largely devoid of meaning apart from the simpler "use".
+- Avoid using **once** as a synonym for "after". Typically, when "once" is used
+  in this way, it is followed by a verb in the perfect tense.
+- Don't use **e.g.** Use "example", "such as", "like", or "for example". The
+  phrase is always followed by a comma.
+- Don't use **i.e.** unless absolutely essential to make text fit. Use "that is"
+  instead.
+- Use **disable** for binary operations that turn a feature or API off. Use
+  "turn on" and "turn off" instead of "enable" and "disable" for other
+  situations. For UI elements that are not available, use "dimmed" instead of
+  "disabled".
+- Use **please** only when you're asking the user to do something inconvenient,
+  not just following the instructions in a typical flow.
+- Use **really** sparingly in such constructions as "Do you really want to..."
+  Because of the weight it puts on the decision, it should be used to confirm
+  actions that the user is extremely unlikely to make.