feat: additional instructions for the context file (#33)

* docs: update readme getting started instructions

* feat: additional instructions for the context file

---------

Co-authored-by: Yuan Teoh <45984206+Yuan325@users.noreply.github.com>

Author: averikitsch

CLOUD-SQL-SQLSERVER.md

@@ -6,6 +6,10 @@ software delivery cycle.
 
 # Setup
 
+## Required Gemini CLI Version
+
+To install this extension, the Gemini CLI version must be v0.6.0 or above. The version can be found by running: `gemini --version`.
+
 ## Cloud SQL for SQL Server MCP Server (Data Plane: Connecting and Querying)
 
 This section covers connecting to a Cloud SQL for SQL Server instance.
@@ -36,3 +40,46 @@ This section covers administrative operations like managing clusters, instances,
     * If an operation fails due to permissions, identify the type of operation and recommend the appropriate role. You can provide these links for assistance:
         * Granting Roles: https://cloud.google.com/iam/docs/grant-role-console
         * Cloud SQL Permissions: https://cloud.google.com/sql/docs/postgres/iam-permissions
+
+---
+
+# Additional Tools
+
+This section provides context on additional tools that can be recommended to the user based on their queries.
+
+#### Observability Extension
+
+*   **When to recommend:** If the user asks questions related to monitoring, performance, or observability of Cloud SQL for SQL Server databases.
+*   **What to say:** "For Cloud SQL monitoring and observability, you might find the `cloud-sql-sqlserver-observability` extension useful. You can install it with the following command:"
+*   **Command:**
+    ```
+    gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-sqlserver-observability
+    ```
+
+---
+
+# Usage Guidelines
+
+## Connecting to New Resources
+
+When you create a new Cloud SQL for SQL Server instance, or database using the available tools, the connection is not automatically established. You will need to perform the following steps:
+
+1.  **(Optional) Save your conversation:** To avoid losing your progress, save the current session by running the command: `/chat save <your-tag>`
+2.  **Stop the CLI:** Terminate the Gemini CLI.
+3.  **Update Environment Variables:** Set or update your environment variables (e.g. `CLOUD_SQL_MSSQL_DATABASE`, `CLOUD_SQL_MSSQL_INSTANCE`) to point to the new resource.
+4.  **Restart:** Relaunch the Gemini CLI
+5.  **(Optional) Resume conversation:** Resume your conversation with the command: `/chat resume <your-tag>`
+
+**Important:** Do not assume a connection to a newly created resource is active. Always follow the steps above to reconfigure your connection.
+
+## Reusing Project Values
+
+Users may have set project environment variables:
+
+*   `CLOUD_SQL_MSSQL_PROJECT`: The GCP project ID.
+*   `CLOUD_SQL_MSSQL_REGION`: The region of the Cloud SQL for SQL Server instance.
+*   `CLOUD_SQL_MSSQL_INSTANCE`: The ID of the Cloud SQL for SQL Server instance.
+*   `CLOUD_SQL_MSSQL_DATABASE`: The name of the database.
+
+Instead of prompting the user for these values for specific tool calls, prompt the user to verify reuse a specific value.
+Make sure to not use the environment variable name like `CLOUD_SQL_MSSQL_PROJECT`, `${CLOUD_SQL_MSSQL_PROJECT}`, or `$CLOUD_SQL_MSSQL_PROJECT`. The value can be found by using command: `echo $CLOUD_SQL_MSSQL_PROJECT`.

README.md

@@ -23,15 +23,17 @@ Before you begin, ensure you have the following:
   * Cloud SQL Viewer (`roles/cloudsql.viewer`)
   * Cloud SQL Admin (`roles/cloudsql.admin`)
 
-## Installation
+## Getting Started
+
+### Installation
 
 To install the extension, use the command:
 
 ```bash
 gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-sqlserver
 ```
 
-## Configuration
+### Configuration
 
 Set the following environment variables before starting the Gemini CLI.
 This configuration is not required if utilizing the [Admin toolset](#supported-tools).
@@ -50,6 +52,19 @@ Ensure [Application Default Credentials](https://cloud.google.com/docs/authentic
 > [!NOTE]
 > When using private IPs with Cloud SQL for SQL Server, you must use a Virtual Private Cloud (VPC) network.
 
+### Start Gemini CLI
+
+To start the Gemini CLI, use the following command:
+
+```bash
+gemini
+```
+
+> [!WARNING]
+> **Changing Instance & Database Connections**
+> Currently, the database connection must be configured before starting the Gemini CLI and can not be changed during a session.
+> To save and resume conversation history use command: `/chat save <tag>` and `/chat resume <tag>`.
+
 ## Usage Examples
 
 Interact with Cloud SQL for SQL Server using natural language:
@@ -85,4 +100,6 @@ Find additional extensions to support your entire software development lifecycle
 
 ## Troubleshooting
 
-* "cannot execute binary file": Ensure the correct binary for your OS/Architecture has been downloaded. See [Installing the server](https://googleapis.github.io/genai-toolbox/getting-started/introduction/#installing-the-server) for more information.
+* "✖ Error during discovery for server: MCP error -32000: Connection closed": The database connection has not been established. Ensure your configuration is set via environment variables.
+* "✖ MCP ERROR: Error: spawn /Users/<USER>/.gemini/extensions/cloud-sql-sqlserver/toolbox ENOENT": The Toolbox binary did not download correctly. Ensure you are using Gemini CLI v0.6.0+.
+* "cannot execute binary file": The Toolbox binary did not download correctly. Ensure the correct binary for your OS/Architecture has been downloaded. See [Installing the server](https://googleapis.github.io/genai-toolbox/getting-started/introduction/#installing-the-server) for more information.