@dgxo/mashadevcli 1.1.0

package/bundle/docs/resources/faq.md

@@ -0,0 +1,175 @@
+# Frequently asked questions (FAQ)
+
+This page provides answers to common questions and solutions to frequent
+problems encountered while using Gemini CLI.
+
+## General issues
+
+This section addresses common questions about Gemini CLI usage, security, and
+troubleshooting general errors.
+
+### Why can't I use third-party software (e.g. Claude Code, OpenClaw, OpenCode) with Gemini CLI?
+
+Using third-party software, tools, or services to harvest or piggyback on Gemini
+CLI's OAuth authentication to access our backend services is a direct violation
+of our [applicable terms and policies](tos-privacy.md). Doing so bypasses our
+intended authentication and security structures, and such actions may be grounds
+for immediate suspension or termination of your account. If you would like to
+use a third-party coding agent with Gemini, the supported and secure method is
+to use a Vertex AI or Google AI Studio API key.
+
+### Why am I getting an `API error: 429 - Resource exhausted`?
+
+This error indicates that you have exceeded your API request limit. The Gemini
+API has rate limits to prevent abuse and ensure fair usage.
+
+To resolve this, you can:
+
+- **Check your usage:** Review your API usage in the Google AI Studio or your
+  Google Cloud project dashboard.
+- **Optimize your prompts:** If you are making many requests in a short period,
+  try to batch your prompts or introduce delays between requests.
+- **Request a quota increase:** If you consistently need a higher limit, you can
+  request a quota increase from Google.
+
+### Why am I getting an `ERR_REQUIRE_ESM` error when running `npm run start`?
+
+This error typically occurs in Node.js projects when there is a mismatch between
+CommonJS and ES Modules.
+
+This is often due to a misconfiguration in your `package.json` or
+`tsconfig.json`. Ensure that:
+
+1.  Your `package.json` has `"type": "module"`.
+2.  Your `tsconfig.json` has `"module": "NodeNext"` or a compatible setting in
+    the `compilerOptions`.
+
+If the problem persists, try deleting your `node_modules` directory and
+`package-lock.json` file, and then run `npm install` again.
+
+### Why don't I see cached token counts in my stats output?
+
+Cached token information is only displayed when cached tokens are being used.
+This feature is available for API key users (Gemini API key or Google Cloud
+Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts
+like Google Gmail or Google Workspace, respectively). This is because the Gemini
+Code Assist API does not support cached content creation. You can still view
+your total token usage using the `/stats` command in Gemini CLI.
+
+## Installation and updates
+
+### How do I update Gemini CLI to the latest version?
+
+If you installed it globally via `npm`, update it using the command
+`npm install -g @dgxo/mashadevcli@latest`. If you compiled it from source, pull
+the latest changes from the repository, and then rebuild using the command
+`npm run build`.
+
+## Platform-specific issues
+
+### Why does the CLI crash on Windows when I run a command like `chmod +x`?
+
+Commands like `chmod` are specific to Unix-like operating systems (Linux,
+macOS). They are not available on Windows by default.
+
+To resolve this, you can:
+
+- **Use Windows-equivalent commands:** Instead of `chmod`, you can use `icacls`
+  to modify file permissions on Windows.
+- **Use a compatibility layer:** Tools like Git Bash or Windows Subsystem for
+  Linux (WSL) provide a Unix-like environment on Windows where these commands
+  will work.
+
+## Configuration
+
+### How do I configure my `GOOGLE_CLOUD_PROJECT`?
+
+You can configure your Google Cloud Project ID using an environment variable.
+
+Set the `GOOGLE_CLOUD_PROJECT` environment variable in your shell:
+
+**macOS/Linux**
+
+```bash
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+```
+
+**Windows (PowerShell)**
+
+```powershell
+$env:GOOGLE_CLOUD_PROJECT="your-project-id"
+```
+
+To make this setting permanent, add this line to your shell's startup file
+(e.g., `~/.bashrc`, `~/.zshrc`).
+
+### What is the best way to store my API keys securely?
+
+Exposing API keys in scripts or checking them into source control is a security
+risk.
+
+To store your API keys securely, you can:
+
+- **Use a `.env` file:** Create a `.env` file in your project's `.gemini`
+  directory (`.gemini/.env`) and store your keys there. Gemini CLI will
+  automatically load these variables.
+- **Use your system's keyring:** For the most secure storage, use your operating
+  system's secret management tool (like macOS Keychain, Windows Credential
+  Manager, or a secret manager on Linux). You can then have your scripts or
+  environment load the key from the secure storage at runtime.
+
+### Where are the Gemini CLI configuration and settings files stored?
+
+The Gemini CLI configuration is stored in two `settings.json` files:
+
+1.  In your home directory: `~/.gemini/settings.json`.
+2.  In your project's root directory: `./.gemini/settings.json`.
+
+Refer to [Gemini CLI Configuration](../reference/configuration.md) for more
+details.
+
+## Google AI Pro/Ultra and subscription FAQs
+
+### Where can I learn more about my Google AI Pro or Google AI Ultra subscription?
+
+To learn more about your Google AI Pro or Google AI Ultra subscription, visit
+**Manage subscription** in your [subscription settings](https://one.google.com).
+
+### How do I know if I have higher limits for Google AI Pro or Ultra?
+
+If you're subscribed to Google AI Pro or Ultra, you automatically have higher
+limits to Gemini Code Assist and Gemini CLI. These are shared across Gemini CLI
+and agent mode in the IDE. You can confirm you have higher limits by checking if
+you are still subscribed to Google AI Pro or Ultra in your
+[subscription settings](https://one.google.com).
+
+### What is the privacy policy for using Gemini Code Assist or Gemini CLI if I've subscribed to Google AI Pro or Ultra?
+
+To learn more about your privacy policy and terms of service governed by your
+subscription, visit
+[Gemini Code Assist: Terms of Service and Privacy Policies](https://developers.google.com/gemini-code-assist/resources/privacy-notices).
+
+### I've upgraded to Google AI Pro or Ultra but it still says I am hitting quota limits. Is this a bug?
+
+The higher limits in your Google AI Pro or Ultra subscription are for Gemini 2.5
+across both Gemini 2.5 Pro and Flash. They are shared quota across Gemini CLI
+and agent mode in Gemini Code Assist IDE extensions. You can learn more about
+quota limits for Gemini CLI, Gemini Code Assist and agent mode in Gemini Code
+Assist at
+[Quotas and limits](https://developers.google.com/gemini-code-assist/resources/quotas).
+
+### If I upgrade to higher limits for Gemini CLI and Gemini Code Assist by purchasing a Google AI Pro or Ultra subscription, will Gemini start using my data to improve its machine learning models?
+
+Google does not use your data to improve Google's machine learning models if you
+purchase a paid plan. Note: If you decide to remain on the free version of
+Gemini Code Assist, Gemini Code Assist for individuals, you can also opt out of
+using your data to improve Google's machine learning models. See the
+[Gemini Code Assist for individuals privacy notice](https://developers.google.com/gemini-code-assist/resources/privacy-notice-gemini-code-assist-individuals)
+for more information.
+
+## Not seeing your question?
+
+Search the
+[Gemini CLI Q&A discussions on GitHub](https://github.com/DGameGT/mashadev-cli/discussions/categories/q-a)
+or
+[start a new discussion on GitHub](https://github.com/DGameGT/mashadev-cli/discussions/new?category=q-a)

package/bundle/docs/resources/quota-and-pricing.md

@@ -0,0 +1,165 @@
+# Gemini CLI: Quotas and pricing
+
+Gemini CLI offers a generous free tier that covers many individual developers'
+use cases. For enterprise or professional usage, or if you need higher limits,
+several options are available depending on your authentication account type.
+
+See [privacy and terms](./tos-privacy.md) for details on the Privacy Policy and
+Terms of Service.
+
+> **Note:** Published prices are list price; additional negotiated commercial
+> discounting may apply.
+
+This article outlines the specific quotas and pricing applicable to Gemini CLI
+when using different authentication methods.
+
+Generally, there are three categories to choose from:
+
+- Free Usage: Ideal for experimentation and light use.
+- Paid Tier (fixed price): For individual developers or enterprises who need
+  more generous daily quotas and predictable costs.
+- Pay-As-You-Go: The most flexible option for professional use, long-running
+  tasks, or when you need full control over your usage.
+
+## Free usage
+
+Your journey begins with a generous free tier, perfect for experimentation and
+light use.
+
+Your free usage limits depend on your authorization type.
+
+### Log in with Google (Gemini Code Assist for individuals)
+
+For users who authenticate by using their Google account to access Gemini Code
+Assist for individuals. This includes:
+
+- 1000 model requests / user / day
+- 60 model requests / user / minute
+- Model requests will be made across the Gemini model family as determined by
+  Gemini CLI.
+
+Learn more at
+[Gemini Code Assist for Individuals Limits](https://developers.google.com/gemini-code-assist/resources/quotas#quotas-for-agent-mode-gemini-cli).
+
+### Log in with Gemini API Key (unpaid)
+
+If you are using a Gemini API key, you can also benefit from a free tier. This
+includes:
+
+- 250 model requests / user / day
+- 10 model requests / user / minute
+- Model requests to Flash model only.
+
+Learn more at
+[Gemini API Rate Limits](https://ai.google.dev/gemini-api/docs/rate-limits).
+
+### Log in with Vertex AI (Express Mode)
+
+Vertex AI offers an Express Mode without the need to enable billing. This
+includes:
+
+- 90 days before you need to enable billing.
+- Quotas and models are variable and specific to your account.
+
+Learn more at
+[Vertex AI Express Mode Limits](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview#quotas).
+
+## Paid tier: Higher limits for a fixed cost
+
+If you use up your initial number of requests, you can continue to benefit from
+Gemini CLI by upgrading to one of the following subscriptions:
+
+- [Google AI Pro and AI Ultra](https://gemini.google/subscriptions/). This is
+  recommended for individual developers. Quotas and pricing are based on a fixed
+  price subscription.
+
+  For predictable costs, you can log in with Google.
+
+  Learn more at
+  [Gemini Code Assist Quotas and Limits](https://developers.google.com/gemini-code-assist/resources/quotas)
+
+- [Purchase a Gemini Code Assist Subscription through Google Cloud ](https://cloud.google.com/gemini/docs/codeassist/overview)
+  by signing up in the Google Cloud console. Learn more at
+  [Set up Gemini Code Assist](https://cloud.google.com/gemini/docs/discover/set-up-gemini).
+
+  Quotas and pricing are based on a fixed price subscription with assigned
+  license seats. For predictable costs, you can sign in with Google.
+
+  This includes:
+  - Gemini Code Assist Standard edition:
+    - 1500 model requests / user / day
+    - 120 model requests / user / minute
+  - Gemini Code Assist Enterprise edition:
+    - 2000 model requests / user / day
+    - 120 model requests / user / minute
+  - Model requests will be made across the Gemini model family as determined by
+    Gemini CLI.
+
+  [Learn more about Gemini Code Assist Standard and Enterprise license limits](https://developers.google.com/gemini-code-assist/resources/quotas#quotas-for-agent-mode-gemini-cli).
+
+## Pay as you go
+
+If you hit your daily request limits or exhaust your Gemini Pro quota even after
+upgrading, the most flexible solution is to switch to a pay-as-you-go model,
+where you pay for the specific amount of processing you use. This is the
+recommended path for uninterrupted access.
+
+To do this, log in using a Gemini API key or Vertex AI.
+
+- Vertex AI (Regular Mode):
+  - Quota: Governed by a dynamic shared quota system or pre-purchased
+    provisioned throughput.
+  - Cost: Based on model and token usage.
+
+Learn more at
+[Vertex AI Dynamic Shared Quota](https://cloud.google.com/vertex-ai/generative-ai/docs/resources/dynamic-shared-quota)
+and [Vertex AI Pricing](https://cloud.google.com/vertex-ai/pricing).
+
+- Gemini API key:
+  - Quota: Varies by pricing tier.
+  - Cost: Varies by pricing tier and model/token usage.
+
+Learn more at
+[Gemini API Rate Limits](https://ai.google.dev/gemini-api/docs/rate-limits),
+[Gemini API Pricing](https://ai.google.dev/gemini-api/docs/pricing)
+
+It’s important to highlight that when using an API key, you pay per token/call.
+This can be more expensive for many small calls with few tokens, but it's the
+only way to ensure your workflow isn't interrupted by quota limits.
+
+## Gemini for workspace plans
+
+These plans currently apply only to the use of Gemini web-based products
+provided by Google-based experiences (for example, the Gemini web app or the
+Flow video editor). These plans do not apply to the API usage which powers the
+Gemini CLI. Supporting these plans is under active consideration for future
+support.
+
+## Check usage and quota
+
+You can check your current token usage and quota information using the
+`/stats model` command. This command provides a snapshot of your current
+session's token usage, as well as your overall quota and usage for the supported
+models.
+
+For more information on the `/stats` command and its subcommands, see the
+[Command Reference](../../reference/commands.md#stats).
+
+A summary of model usage is also presented on exit at the end of a session.
+
+## Tips to avoid high costs
+
+When using a Pay as you Go API key, be mindful of your usage to avoid unexpected
+costs.
+
+- Don't blindly accept every suggestion, especially for computationally
+  intensive tasks like refactoring large codebases.
+- Be intentional with your prompts and commands. You are paying per call, so
+  think about the most efficient way to get the job done.
+
+## Gemini API vs. Vertex
+
+- Gemini API (gemini developer api): This is the fastest way to use the Gemini
+  models directly.
+- Vertex AI: This is the enterprise-grade platform for building, deploying, and
+  managing Gemini models with specific security and control requirements.

package/bundle/docs/resources/tos-privacy.md

@@ -0,0 +1,102 @@
+# Gemini CLI: License, Terms of Service, and Privacy Notices
+
+Gemini CLI is an open-source tool that lets you interact with Google's powerful
+AI services directly from your command-line interface. The Gemini CLI software
+is licensed under the
+[Apache 2.0 license](https://github.com/DGameGT/mashadev-cli/blob/main/LICENSE).
+When you use Gemini CLI to access or use Google’s services, the Terms of Service
+and Privacy Notices applicable to those services apply to such access and use.
+
+Directly accessing the services powering Gemini CLI (e.g., the Gemini Code
+Assist service) using third-party software, tools, or services (for example,
+using OpenClaw with Gemini CLI OAuth) is a violation of applicable terms and
+policies. Such actions may be grounds for suspension or termination of your
+account.
+
+Your Gemini CLI Usage Statistics are handled in accordance with Google's Privacy
+Policy.
+
+**Note:** See [quotas and pricing](/docs/resources/quota-and-pricing.md) for the
+quota and pricing details that apply to your usage of the Gemini CLI.
+
+## Supported authentication methods
+
+Your authentication method refers to the method you use to log into and access
+Google’s services with Gemini CLI. Supported authentication methods include:
+
+- Logging in with your Google account to Gemini Code Assist.
+- Using an API key with Gemini Developer API.
+- Using an API key with Vertex AI GenAI API.
+
+The Terms of Service and Privacy Notices applicable to the aforementioned Google
+services are set forth in the table below.
+
+If you log in with your Google account and you do not already have a Gemini Code
+Assist account associated with your Google account, you will be directed to the
+sign up flow for Gemini Code Assist for individuals. If your Google account is
+managed by your organization, your administrator may not permit access to Gemini
+Code Assist for individuals. Please see the
+[Gemini Code Assist for individuals FAQs](https://developers.google.com/gemini-code-assist/resources/faqs)
+for further information.
+
+| Authentication Method    | Service(s)                   | Terms of Service                                                                                        | Privacy Notice                                                                                |
+| :----------------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------- |
+| Google Account           | Gemini Code Assist services  | [Terms of Service](https://developers.google.com/gemini-code-assist/resources/privacy-notices)          | [Privacy Notices](https://developers.google.com/gemini-code-assist/resources/privacy-notices) |
+| Gemini Developer API Key | Gemini API - Unpaid Services | [Gemini API Terms of Service - Unpaid Services](https://ai.google.dev/gemini-api/terms#unpaid-services) | [Google Privacy Policy](https://policies.google.com/privacy)                                  |
+| Gemini Developer API Key | Gemini API - Paid Services   | [Gemini API Terms of Service - Paid Services](https://ai.google.dev/gemini-api/terms#paid-services)     | [Google Privacy Policy](https://policies.google.com/privacy)                                  |
+| Vertex AI GenAI API Key  | Vertex AI GenAI API          | [Google Cloud Platform Terms of Service](https://cloud.google.com/terms/service-terms/)                 | [Google Cloud Privacy Notice](https://cloud.google.com/terms/cloud-privacy-notice)            |
+
+## 1. If you have logged in with your Google account to Gemini Code Assist
+
+For users who use their Google account to access
+[Gemini Code Assist](https://codeassist.google), these Terms of Service and
+Privacy Notice documents apply:
+
+- Gemini Code Assist for individuals:
+  [Google Terms of Service](https://policies.google.com/terms) and
+  [Gemini Code Assist for individuals Privacy Notice](https://developers.google.com/gemini-code-assist/resources/privacy-notice-gemini-code-assist-individuals).
+- Gemini Code Assist with Google AI Pro or Ultra subscription:
+  [Google Terms of Service](https://policies.google.com/terms),
+  [Google One Additional Terms of Service](https://one.google.com/terms-of-service)
+  and [Google Privacy Policy\*](https://policies.google.com/privacy).
+- Gemini Code Assist Standard and Enterprise editions:
+  [Google Cloud Platform Terms of Service](https://cloud.google.com/terms) and
+  [Google Cloud Privacy Notice](https://cloud.google.com/terms/cloud-privacy-notice).
+
+_\* If your account is also associated with an active subscription to Gemini
+Code Assist Standard or Enterprise edition, the terms and privacy policy of
+Gemini Code Assist Standard or Enterprise edition will apply to all your use of
+Gemini Code Assist._
+
+## 2. If you have logged in with a Gemini API key to the Gemini Developer API
+
+If you are using a Gemini API key for authentication with the
+[Gemini Developer API](https://ai.google.dev/gemini-api/docs), these Terms of
+Service and Privacy Notice documents apply:
+
+- Terms of Service: Your use of the Gemini CLI is governed by the
+  [Gemini API Terms of Service](https://ai.google.dev/gemini-api/terms). These
+  terms may differ depending on whether you are using an unpaid or paid service:
+  - For unpaid services, refer to the
+    [Gemini API Terms of Service - Unpaid Services](https://ai.google.dev/gemini-api/terms#unpaid-services).
+  - For paid services, refer to the
+    [Gemini API Terms of Service - Paid Services](https://ai.google.dev/gemini-api/terms#paid-services).
+- Privacy Notice: The collection and use of your data is described in the
+  [Google Privacy Policy](https://policies.google.com/privacy).
+
+## 3. If you have logged in with a Gemini API key to the Vertex AI GenAI API
+
+If you are using a Gemini API key for authentication with a
+[Vertex AI GenAI API](https://cloud.google.com/vertex-ai/generative-ai/docs/reference/rest)
+backend, these Terms of Service and Privacy Notice documents apply:
+
+- Terms of Service: Your use of the Gemini CLI is governed by the
+  [Google Cloud Platform Service Terms](https://cloud.google.com/terms/service-terms/).
+- Privacy Notice: The collection and use of your data is described in the
+  [Google Cloud Privacy Notice](https://cloud.google.com/terms/cloud-privacy-notice).
+
+## Usage statistics opt-out
+
+You may opt-out from sending Gemini CLI Usage Statistics to Google by following
+the instructions available here:
+[Usage Statistics Configuration](https://github.com/DGameGT/mashadev-cli/blob/main/docs/reference/configuration.md#usage-statistics).

package/bundle/docs/resources/troubleshooting.md

@@ -0,0 +1,176 @@
+# Troubleshooting guide
+
+This guide provides solutions to common issues and debugging tips, including
+topics on:
+
+- Authentication or login errors
+- Frequently asked questions (FAQs)
+- Debugging tips
+- Existing GitHub Issues similar to yours or creating new Issues
+
+## Authentication or login errors
+
+- **Error:
+  `You must be a named user on your organization's Gemini Code Assist Standard edition subscription to use this service. Please contact your administrator to request an entitlement to Gemini Code Assist Standard edition.`**
+  - **Cause:** This error might occur if Gemini CLI detects the
+    `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` environment variable is
+    defined. Setting these variables forces an organization subscription check.
+    This might be an issue if you are using an individual Google account not
+    linked to an organizational subscription.
+
+  - **Solution:**
+    - **Individual Users:** Unset the `GOOGLE_CLOUD_PROJECT` and
+      `GOOGLE_CLOUD_PROJECT_ID` environment variables. Check and remove these
+      variables from your shell configuration files (for example, `.bashrc`,
+      `.zshrc`) and any `.env` files. If this doesn't resolve the issue, try
+      using a different Google account.
+
+    - **Organizational Users:** Contact your Google Cloud administrator to be
+      added to your organization's Gemini Code Assist subscription.
+
+- **Error:
+  `Failed to login. Message: Your current account is not eligible... because it is not currently available in your location.`**
+  - **Cause:** Gemini CLI does not currently support your location. For a full
+    list of supported locations, see the following pages:
+    - Gemini Code Assist for individuals:
+      [Available locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas)
+
+- **Error: `Failed to login. Message: Request contains an invalid argument`**
+  - **Cause:** Users with Google Workspace accounts or Google Cloud accounts
+    associated with their Gmail accounts may not be able to activate the free
+    tier of the Google Code Assist plan.
+  - **Solution:** For Google Cloud accounts, you can work around this by setting
+    `GOOGLE_CLOUD_PROJECT` to your project ID. Alternatively, you can obtain the
+    Gemini API key from
+    [Google AI Studio](http://aistudio.google.com/app/apikey), which also
+    includes a separate free tier.
+
+- **Error: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` or
+  `unable to get local issuer certificate`**
+  - **Cause:** You may be on a corporate network with a firewall that intercepts
+    and inspects SSL/TLS traffic. This often requires a custom root CA
+    certificate to be trusted by Node.js.
+  - **Solution:** First try setting `NODE_USE_SYSTEM_CA`; if that does not
+    resolve the issue, set `NODE_EXTRA_CA_CERTS`.
+    - Set the `NODE_USE_SYSTEM_CA=1` environment variable to tell Node.js to use
+      the operating system's native certificate store (where corporate
+      certificates are typically already installed).
+      - Example: `export NODE_USE_SYSTEM_CA=1` (Windows PowerShell:
+        `$env:NODE_USE_SYSTEM_CA=1`)
+    - Set the `NODE_EXTRA_CA_CERTS` environment variable to the absolute path of
+      your corporate root CA certificate file.
+      - Example: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt`
+        (Windows PowerShell:
+        `$env:NODE_EXTRA_CA_CERTS="C:\path\to\your\corporate-ca.crt"`)
+
+## Common error messages and solutions
+
+- **Error: `EADDRINUSE` (Address already in use) when starting an MCP server.**
+  - **Cause:** Another process is already using the port that the MCP server is
+    trying to bind to.
+  - **Solution:** Either stop the other process that is using the port or
+    configure the MCP server to use a different port.
+
+- **Error: Command not found (when attempting to run Gemini CLI with
+  `gemini`).**
+  - **Cause:** Gemini CLI is not correctly installed or it is not in your
+    system's `PATH`.
+  - **Solution:** The update depends on how you installed Gemini CLI:
+    - If you installed `gemini` globally, check that your `npm` global binary
+      directory is in your `PATH`. You can update Gemini CLI using the command
+      `npm install -g @dgxo/mashadevcli@latest`.
+    - If you are running `gemini` from source, ensure you are using the correct
+      command to invoke it (e.g., `node packages/cli/dist/index.js ...`). To
+      update Gemini CLI, pull the latest changes from the repository, and then
+      rebuild using the command `npm run build`.
+
+- **Error: `MODULE_NOT_FOUND` or import errors.**
+  - **Cause:** Dependencies are not installed correctly, or the project hasn't
+    been built.
+  - **Solution:**
+    1.  Run `npm install` to ensure all dependencies are present.
+    2.  Run `npm run build` to compile the project.
+    3.  Verify that the build completed successfully with `npm run start`.
+
+- **Error: "Operation not permitted", "Permission denied", or similar.**
+  - **Cause:** When sandboxing is enabled, Gemini CLI may attempt operations
+    that are restricted by your sandbox configuration, such as writing outside
+    the project directory or system temp directory.
+  - **Solution:** Refer to the [Configuration: Sandboxing](../cli/sandbox.md)
+    documentation for more information, including how to customize your sandbox
+    configuration.
+
+- **Gemini CLI is not running in interactive mode in "CI" environments**
+  - **Issue:** The Gemini CLI does not enter interactive mode (no prompt
+    appears) if an environment variable starting with `CI_` (e.g., `CI_TOKEN`)
+    is set. This is because the `is-in-ci` package, used by the underlying UI
+    framework, detects these variables and assumes a non-interactive CI
+    environment.
+  - **Cause:** The `is-in-ci` package checks for the presence of `CI`,
+    `CONTINUOUS_INTEGRATION`, or any environment variable with a `CI_` prefix.
+    When any of these are found, it signals that the environment is
+    non-interactive, which prevents the Gemini CLI from starting in its
+    interactive mode.
+  - **Solution:** If the `CI_` prefixed variable is not needed for the CLI to
+    function, you can temporarily unset it for the command. e.g.,
+    `env -u CI_TOKEN gemini`
+
+- **DEBUG mode not working from project .env file**
+  - **Issue:** Setting `DEBUG=true` in a project's `.env` file doesn't enable
+    debug mode for gemini-cli.
+  - **Cause:** The `DEBUG` and `DEBUG_MODE` variables are automatically excluded
+    from project `.env` files to prevent interference with gemini-cli behavior.
+  - **Solution:** Use a `.gemini/.env` file instead, or configure the
+    `advanced.excludedEnvVars` setting in your `settings.json` to exclude fewer
+    variables.
+
+## Exit codes
+
+The Gemini CLI uses specific exit codes to indicate the reason for termination.
+This is especially useful for scripting and automation.
+
+| Exit Code | Error Type                 | Description                                                                                         |
+| --------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
+| 41        | `FatalAuthenticationError` | An error occurred during the authentication process.                                                |
+| 42        | `FatalInputError`          | Invalid or missing input was provided to the CLI. (non-interactive mode only)                       |
+| 44        | `FatalSandboxError`        | An error occurred with the sandboxing environment (e.g., Docker, Podman, or Seatbelt).              |
+| 52        | `FatalConfigError`         | A configuration file (`settings.json`) is invalid or contains errors.                               |
+| 53        | `FatalTurnLimitedError`    | The maximum number of conversational turns for the session was reached. (non-interactive mode only) |
+
+## Debugging tips
+
+- **CLI debugging:**
+  - Use the `--debug` flag for more detailed output. In interactive mode, press
+    F12 to view the debug console.
+  - Check the CLI logs, often found in a user-specific configuration or cache
+    directory.
+
+- **Core debugging:**
+  - Check the server console output for error messages or stack traces.
+  - Increase log verbosity if configurable. For example, set the `DEBUG_MODE`
+    environment variable to `true` or `1`.
+  - Use Node.js debugging tools (e.g., `node --inspect`) if you need to step
+    through server-side code.
+
+- **Tool issues:**
+  - If a specific tool is failing, try to isolate the issue by running the
+    simplest possible version of the command or operation the tool performs.
+  - For `run_shell_command`, check that the command works directly in your shell
+    first.
+  - For _file system tools_, verify that paths are correct and check the
+    permissions.
+
+- **Pre-flight checks:**
+  - Always run `npm run preflight` before committing code. This can catch many
+    common issues related to formatting, linting, and type errors.
+
+## Existing GitHub issues similar to yours or creating new issues
+
+If you encounter an issue that was not covered here in this _Troubleshooting
+guide_, consider searching the Gemini CLI
+[Issue tracker on GitHub](https://github.com/DGameGT/mashadev-cli/issues).
+If you can't find an issue similar to yours, consider creating a new GitHub
+Issue with a detailed description. Pull requests are also welcome!
+
+> **Note:** Issues tagged as "🔒Maintainers only" are reserved for project
+> maintainers. We will not accept pull requests related to these issues.

package/bundle/docs/resources/uninstall.md

@@ -0,0 +1,56 @@
+# Uninstalling the CLI
+
+Your uninstall method depends on how you ran the CLI. Follow the instructions
+for either npx or a global npm installation.
+
+## Method 1: Using npx
+
+npx runs packages from a temporary cache without a permanent installation. To
+"uninstall" the CLI, you must clear this cache, which will remove gemini-cli and
+any other packages previously executed with npx.
+
+The npx cache is a directory named `_npx` inside your main npm cache folder. You
+can find your npm cache path by running `npm config get cache`.
+
+**For macOS / Linux**
+
+```bash
+# The path is typically ~/.npm/_npx
+rm -rf "$(npm config get cache)/_npx"
+```
+
+**For Windows (PowerShell)**
+
+```powershell
+# The path is typically $env:LocalAppData\npm-cache\_npx
+Remove-Item -Path (Join-Path $env:LocalAppData "npm-cache\_npx") -Recurse -Force
+```
+
+## Method 2: Using npm (global install)
+
+If you installed the CLI globally (e.g., `npm install -g @dgxo/mashadevcli`),
+use the `npm uninstall` command with the `-g` flag to remove it.
+
+```bash
+npm uninstall -g @dgxo/mashadevcli
+```
+
+This command completely removes the package from your system.
+
+## Method 3: Homebrew
+
+If you installed the CLI globally using Homebrew (e.g.,
+`brew install gemini-cli`), use the `brew uninstall` command to remove it.
+
+```bash
+brew uninstall gemini-cli
+```
+
+## Method 4: MacPorts
+
+If you installed the CLI globally using MacPorts (e.g.,
+`sudo port install gemini-cli`), use the `port uninstall` command to remove it.
+
+```bash
+sudo port uninstall gemini-cli
+```