feat: introduce UX Extension and Base Folder Strategy

docs/tools/mcp-server.md

@@ -176,8 +176,8 @@ Each server configuration supports the following properties:
   enabled by default.
 - **`excludeTools`** (string[]): List of tool names to exclude from this MCP
   server. Tools listed here will not be available to the model, even if they are
-  exposed by the server. `excludeTools` takes precedence over `includeTools`. If
-  a tool is in both lists, it will be excluded.
+  exposed by the server. **Note:** `excludeTools` takes precedence over
+  `includeTools` - if a tool is in both lists, it will be excluded.
 - **`targetAudience`** (string): The OAuth Client ID allowlisted on the
   IAP-protected application you are trying to access. Used with
   `authProviderType: 'service_account_impersonation'`.
@@ -238,9 +238,7 @@ This follows the security principle that if a variable is explicitly configured
 by the user for a specific server, it constitutes informed consent to share that
 specific data with that server.
 
-<!-- prettier-ignore -->
-> [!NOTE]
-> Even when explicitly defined, you should avoid hardcoding secrets.
+> **Note:** Even when explicitly defined, you should avoid hardcoding secrets.
 > Instead, use environment variable expansion (e.g., `"MY_KEY": "$MY_KEY"`) to
 > securely pull the value from your host environment at runtime.
 
@@ -285,12 +283,10 @@ When connecting to an OAuth-enabled server:
 
 #### Browser redirect requirements
 
-<!-- prettier-ignore -->
-> [!IMPORTANT]
-> OAuth authentication requires that your local machine can:
->
-> - Open a web browser for authentication
-> - Receive redirects on `http://localhost:7777/oauth/callback`
+**Important:** OAuth authentication requires that your local machine can:
+
+- Open a web browser for authentication
+- Receive redirects on `http://localhost:7777/oauth/callback`
 
 This feature will not work in:
 
@@ -581,9 +577,7 @@ every discovered MCP tool is assigned a strict namespace.
    [Special syntax for MCP tools](../reference/policy-engine.md#special-syntax-for-mcp-tools)
    in the Policy Engine documentation.
 
-<!-- prettier-ignore -->
-> [!WARNING]
-> Do not use underscores (`_`) in your MCP server names (e.g., use
+> **Warning:** Do not use underscores (`_`) in your MCP server names (e.g., use
 > `my-server` rather than `my_server`). The policy parser splits Fully Qualified
 > Names (`mcp_server_tool`) on the _first_ underscore following the `mcp_`
 > prefix. If your server name contains an underscore, the parser will
@@ -1122,9 +1116,7 @@ command has no flags.
 gemini mcp list
 ```
 
-<!-- prettier-ignore -->
-> [!NOTE]
-> For security, `stdio` MCP servers (those using the
+> **Note on Trust:** For security, `stdio` MCP servers (those using the
 > `command` property) are only tested and displayed as "Connected" if the
 > current folder is trusted. If the folder is untrusted, they will show as
 > "Disconnected". Use `gemini trust` to trust the current folder.

docs/tools/planning.md

@@ -11,9 +11,7 @@ by the agent when you ask it to "start a plan" using natural language. In this
 mode, the agent is restricted to read-only tools to allow for safe exploration
 and planning.
 
-<!-- prettier-ignore -->
-> [!NOTE]
-> This tool is not available when the CLI is in YOLO mode.
+> **Note:** This tool is not available when the CLI is in YOLO mode.
 
 - **Tool name:** `enter_plan_mode`
 - **Display name:** Enter Plan Mode

docs/tools/shell.md

@@ -57,8 +57,8 @@ implementation, which does not support interactive commands.
 ### Showing color in output
 
 To show color in the shell output, you need to set the `tools.shell.showColor`
-setting to `true`. This setting only applies when
-`tools.shell.enableInteractiveShell` is enabled.
+setting to `true`. **Note: This setting only applies when
+`tools.shell.enableInteractiveShell` is enabled.**
 
 **Example `settings.json`:**
 
@@ -75,8 +75,8 @@ setting to `true`. This setting only applies when
 ### Setting the pager
 
 You can set a custom pager for the shell output by setting the
-`tools.shell.pager` setting. The default pager is `cat`. This setting only
-applies when `tools.shell.enableInteractiveShell` is enabled.
+`tools.shell.pager` setting. The default pager is `cat`. **Note: This setting
+only applies when `tools.shell.enableInteractiveShell` is enabled.**
 
 **Example `settings.json`:**
 

docs/tools/todos.md

@@ -13,8 +13,7 @@ updates to the CLI interface.
 - `todos` (array of objects, required): The complete list of tasks. Each object
   includes:
   - `description` (string): Technical description of the task.
-  - `status` (enum): `pending`, `in_progress`, `completed`, `cancelled`, or
-    `blocked`.
+  - `status` (enum): `pending`, `in_progress`, `completed`, or `cancelled`.
 
 ## Technical behavior