@dgxo/mashadevcli 1.1.0

package/bundle/docs/cli/gemini-md.md

@@ -0,0 +1,116 @@
+# Provide context with GEMINI.md files
+
+Context files, which use the default name `GEMINI.md`, are a powerful feature
+for providing instructional context to the Gemini model. You can use these files
+to give project-specific instructions, define a persona, or provide coding style
+guides to make the AI's responses more accurate and tailored to your needs.
+
+Instead of repeating instructions in every prompt, you can define them once in a
+context file.
+
+## Understand the context hierarchy
+
+The CLI uses a hierarchical system to source context. It loads various context
+files from several locations, concatenates the contents of all found files, and
+sends them to the model with every prompt. The CLI loads files in the following
+order:
+
+1.  **Global context file:**
+    - **Location:** `~/.gemini/GEMINI.md` (in your user home directory).
+    - **Scope:** Provides default instructions for all your projects.
+
+2.  **Environment and workspace context files:**
+    - **Location:** The CLI searches for `GEMINI.md` files in your configured
+      workspace directories and their parent directories.
+    - **Scope:** Provides context relevant to the projects you are currently
+      working on.
+
+3.  **Just-in-time (JIT) context files:**
+    - **Location:** When a tool accesses a file or directory, the CLI
+      automatically scans for `GEMINI.md` files in that directory and its
+      ancestors up to a trusted root.
+    - **Scope:** Lets the model discover highly specific instructions for
+      particular components only when they are needed.
+
+The CLI footer displays the number of loaded context files, which gives you a
+quick visual cue of the active instructional context.
+
+### Example `GEMINI.md` file
+
+Here is an example of what you can include in a `GEMINI.md` file at the root of
+a TypeScript project:
+
+```markdown
+# Project: My TypeScript Library
+
+## General Instructions
+
+- When you generate new TypeScript code, follow the existing coding style.
+- Ensure all new functions and classes have JSDoc comments.
+- Prefer functional programming paradigms where appropriate.
+
+## Coding Style
+
+- Use 2 spaces for indentation.
+- Prefix interface names with `I` (for example, `IUserService`).
+- Always use strict equality (`===` and `!==`).
+```
+
+## Manage context with the `/memory` command
+
+You can interact with the loaded context files by using the `/memory` command.
+
+- **`/memory show`**: Displays the full, concatenated content of the current
+  hierarchical memory. This lets you inspect the exact instructional context
+  being provided to the model.
+- **`/memory refresh`**: Forces a re-scan and reload of all `GEMINI.md` files
+  from all configured locations.
+- **`/memory add <text>`**: Appends your text to your global
+  `~/.gemini/GEMINI.md` file. This lets you add persistent memories on the fly.
+
+## Modularize context with imports
+
+You can break down large `GEMINI.md` files into smaller, more manageable
+components by importing content from other files using the `@file.md` syntax.
+This feature supports both relative and absolute paths.
+
+**Example `GEMINI.md` with imports:**
+
+```markdown
+# Main GEMINI.md file
+
+This is the main content.
+
+@./components/instructions.md
+
+More content here.
+
+@../shared/style-guide.md
+```
+
+For more details, see the [Memory Import Processor](../reference/memport.md)
+documentation.
+
+## Customize the context file name
+
+While `GEMINI.md` is the default filename, you can configure this in your
+`settings.json` file. To specify a different name or a list of names, use the
+`context.fileName` property.
+
+**Example `settings.json`:**
+
+```json
+{
+  "context": {
+    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
+  }
+}
+```
+
+## Next steps
+
+- Learn about [Ignoring files](./gemini-ignore.md) to exclude content from the
+  context system.
+- Explore the [Memory tool](../tools/memory.md) to save persistent memories.
+- See how to use [Custom commands](./custom-commands.md) to automate common
+  prompts.

package/bundle/docs/cli/generation-settings.md

@@ -0,0 +1,210 @@
+# Advanced Model Configuration
+
+This guide details the Model Configuration system within the Gemini CLI.
+Designed for researchers, AI quality engineers, and advanced users, this system
+provides a rigorous framework for managing generative model hyperparameters and
+behaviors.
+
+> **Warning**: This is a power-user feature. Configuration values are passed
+> directly to the model provider with minimal validation. Incorrect settings
+> (e.g., incompatible parameter combinations) may result in runtime errors from
+> the API.
+
+## 1. System Overview
+
+The Model Configuration system (`ModelConfigService`) enables deterministic
+control over model generation. It decouples the requested model identifier
+(e.g., a CLI flag or agent request) from the underlying API configuration. This
+allows for:
+
+- **Precise Hyperparameter Tuning**: Direct control over `temperature`, `topP`,
+  `thinkingBudget`, and other SDK-level parameters.
+- **Environment-Specific Behavior**: Distinct configurations for different
+  operating contexts (e.g., testing vs. production).
+- **Agent-Scoped Customization**: Applying specific settings only when a
+  particular agent is active.
+
+The system operates on two core primitives: **Aliases** and **Overrides**.
+
+## 2. Configuration Primitives
+
+These settings are located under the `modelConfigs` key in your configuration
+file.
+
+### Aliases (`customAliases`)
+
+Aliases are named, reusable configuration presets. Users should define their own
+aliases (or override system defaults) in the `customAliases` map.
+
+- **Inheritance**: An alias can `extends` another alias (including system
+  defaults like `chat-base`), inheriting its `modelConfig`. Child aliases can
+  overwrite or augment inherited settings.
+- **Abstract Aliases**: An alias is not required to specify a concrete `model`
+  if it serves purely as a base for other aliases.
+
+**Example Hierarchy**:
+
+```json
+"modelConfigs": {
+  "customAliases": {
+    "base": {
+      "modelConfig": {
+        "generateContentConfig": { "temperature": 0.0 }
+      }
+    },
+    "chat-base": {
+      "extends": "base",
+      "modelConfig": {
+        "generateContentConfig": { "temperature": 0.7 }
+      }
+    }
+  }
+}
+```
+
+### Overrides (`overrides`)
+
+Overrides are conditional rules that inject configuration based on the runtime
+context. They are evaluated dynamically for each model request.
+
+- **Match Criteria**: Overrides apply when the request context matches the
+  specified `match` properties.
+  - `model`: Matches the requested model name or alias.
+  - `overrideScope`: Matches the distinct scope of the request (typically the
+    agent name, e.g., `codebaseInvestigator`).
+
+**Example Override**:
+
+```json
+"modelConfigs": {
+  "overrides": [
+    {
+      "match": {
+        "overrideScope": "codebaseInvestigator"
+      },
+      "modelConfig": {
+        "generateContentConfig": { "temperature": 0.1 }
+      }
+    }
+  ]
+}
+```
+
+## 3. Resolution Strategy
+
+The `ModelConfigService` resolves the final configuration through a two-step
+process:
+
+### Step 1: Alias Resolution
+
+The requested model string is looked up in the merged map of system `aliases`
+and user `customAliases`.
+
+1.  If found, the system recursively resolves the `extends` chain.
+2.  Settings are merged from parent to child (child wins).
+3.  This results in a base `ResolvedModelConfig`.
+4.  If not found, the requested string is treated as the raw model name.
+
+### Step 2: Override Application
+
+The system evaluates the `overrides` list against the request context (`model`
+and `overrideScope`).
+
+1.  **Filtering**: All matching overrides are identified.
+2.  **Sorting**: Matches are prioritized by **specificity** (the number of
+    matched keys in the `match` object).
+    - Specific matches (e.g., `model` + `overrideScope`) override broad matches
+      (e.g., `model` only).
+    - Tie-breaking: If specificity is equal, the order of definition in the
+      `overrides` array is preserved (last one wins).
+3.  **Merging**: The configurations from the sorted overrides are merged
+    sequentially onto the base configuration.
+
+## 4. Configuration Reference
+
+The configuration follows the `ModelConfigServiceConfig` interface.
+
+### `ModelConfig` Object
+
+Defines the actual parameters for the model.
+
+| Property                | Type     | Description                                                        |
+| :---------------------- | :------- | :----------------------------------------------------------------- |
+| `model`                 | `string` | The identifier of the model to be called (e.g., `gemini-2.5-pro`). |
+| `generateContentConfig` | `object` | The configuration object passed to the `@google/genai` SDK.        |
+
+### `GenerateContentConfig` (Common Parameters)
+
+Directly maps to the SDK's `GenerateContentConfig`. Common parameters include:
+
+- **`temperature`**: (`number`) Controls output randomness. Lower values (0.0)
+  are deterministic; higher values (>0.7) are creative.
+- **`topP`**: (`number`) Nucleus sampling probability.
+- **`maxOutputTokens`**: (`number`) Limit on generated response length.
+- **`thinkingConfig`**: (`object`) Configuration for models with reasoning
+  capabilities (e.g., `thinkingBudget`, `includeThoughts`).
+
+## 5. Practical Examples
+
+### Defining a Deterministic Baseline
+
+Create an alias for tasks requiring high precision, extending the standard chat
+configuration but enforcing zero temperature.
+
+```json
+"modelConfigs": {
+  "customAliases": {
+    "precise-mode": {
+      "extends": "chat-base",
+      "modelConfig": {
+        "generateContentConfig": {
+          "temperature": 0.0,
+          "topP": 1.0
+        }
+      }
+    }
+  }
+}
+```
+
+### Agent-Specific Parameter Injection
+
+Enforce extended thinking budgets for a specific agent without altering the
+global default, e.g. for the `codebaseInvestigator`.
+
+```json
+"modelConfigs": {
+  "overrides": [
+    {
+      "match": {
+        "overrideScope": "codebaseInvestigator"
+      },
+      "modelConfig": {
+        "generateContentConfig": {
+          "thinkingConfig": { "thinkingBudget": 4096 }
+        }
+      }
+    }
+  ]
+}
+```
+
+### Experimental Model Evaluation
+
+Route traffic for a specific alias to a preview model for A/B testing, without
+changing client code.
+
+```json
+"modelConfigs": {
+  "overrides": [
+    {
+      "match": {
+        "model": "gemini-2.5-pro"
+      },
+      "modelConfig": {
+        "model": "gemini-2.5-pro-experimental-001"
+      }
+    }
+  ]
+}
+```

package/bundle/docs/cli/headless.md

@@ -0,0 +1,50 @@
+# Headless mode reference
+
+Headless mode provides a programmatic interface to Gemini CLI, returning
+structured text or JSON output without an interactive terminal UI.
+
+## Technical reference
+
+Headless mode is triggered when the CLI is run in a non-TTY environment or when
+providing a query as a positional argument without the interactive flag.
+
+### Output formats
+
+You can specify the output format using the `--output-format` flag.
+
+#### JSON output
+
+Returns a single JSON object containing the response and usage statistics.
+
+- **Schema:**
+  - `response`: (string) The model's final answer.
+  - `stats`: (object) Token usage and API latency metrics.
+  - `error`: (object, optional) Error details if the request failed.
+
+#### Streaming JSON output
+
+Returns a stream of newline-delimited JSON (JSONL) events.
+
+- **Event types:**
+  - `init`: Session metadata (session ID, model).
+  - `message`: User and assistant message chunks.
+  - `tool_use`: Tool call requests with arguments.
+  - `tool_result`: Output from executed tools.
+  - `error`: Non-fatal warnings and system errors.
+  - `result`: Final outcome with aggregated statistics.
+
+## Exit codes
+
+The CLI returns standard exit codes to indicate the result of the headless
+execution:
+
+- `0`: Success.
+- `1`: General error or API failure.
+- `42`: Input error (invalid prompt or arguments).
+- `53`: Turn limit exceeded.
+
+## Next steps
+
+- Follow the [Automation tutorial](./tutorials/automation.md) for practical
+  scripting examples.
+- See the [CLI reference](./cli-reference.md) for all available flags.

package/bundle/docs/cli/model-routing.md

@@ -0,0 +1,42 @@
+# Model routing
+
+Gemini CLI includes a model routing feature that automatically switches to a
+fallback model in case of a model failure. This feature is enabled by default
+and provides resilience when the primary model is unavailable.
+
+## How it works
+
+Model routing is managed by the `ModelAvailabilityService`, which monitors model
+health and automatically routes requests to available models based on defined
+policies.
+
+1.  **Model failure:** If the currently selected model fails (e.g., due to quota
+    or server errors), the CLI will initiate the fallback process.
+
+2.  **User consent:** Depending on the failure and the model's policy, the CLI
+    may prompt you to switch to a fallback model (by default always prompts
+    you).
+
+    Some internal utility calls (such as prompt completion and classification)
+    use a silent fallback chain for `gemini-2.5-flash-lite` and will fall back
+    to `gemini-2.5-flash` and `gemini-2.5-pro` without prompting or changing the
+    configured model.
+
+3.  **Model switch:** If approved, or if the policy allows for silent fallback,
+    the CLI will use an available fallback model for the current turn or the
+    remainder of the session.
+
+### Model selection precedence
+
+The model used by Gemini CLI is determined by the following order of precedence:
+
+1.  **`--model` command-line flag:** A model specified with the `--model` flag
+    when launching the CLI will always be used.
+2.  **`GEMINI_MODEL` environment variable:** If the `--model` flag is not used,
+    the CLI will use the model specified in the `GEMINI_MODEL` environment
+    variable.
+3.  **`model.name` in `settings.json`:** If neither of the above are set, the
+    model specified in the `model.name` property of your `settings.json` file
+    will be used.
+4.  **Default model:** If none of the above are set, the default model will be
+    used. The default model is `auto`

package/bundle/docs/cli/model.md

@@ -0,0 +1,53 @@
+# Gemini CLI model selection (`/model` command)
+
+Select your Gemini CLI model. The `/model` command lets you configure the model
+used by Gemini CLI, giving you more control over your results. Use **Pro**
+models for complex tasks and reasoning, **Flash** models for high speed results,
+or the (recommended) **Auto** setting to choose the best model for your tasks.
+
+> **Note:** The `/model` command (and the `--model` flag) does not override the
+> model used by sub-agents. Consequently, even when using the `/model` flag you
+> may see other models used in your model usage reports.
+
+## How to use the `/model` command
+
+Use the following command in Gemini CLI:
+
+```
+/model
+```
+
+Running this command will open a dialog with your options:
+
+| Option            | Description                                                    | Models                                       |
+| ----------------- | -------------------------------------------------------------- | -------------------------------------------- |
+| Auto (Gemini 3)   | Let the system choose the best Gemini 3 model for your task.   | gemini-3-pro-preview, gemini-3-flash-preview |
+| Auto (Gemini 2.5) | Let the system choose the best Gemini 2.5 model for your task. | gemini-2.5-pro, gemini-2.5-flash             |
+| Manual            | Select a specific model.                                       | Any available model.                         |
+
+We recommend selecting one of the above **Auto** options. However, you can
+select **Manual** to select a specific model from those available.
+
+You can also use the `--model` flag to specify a particular Gemini model on
+startup. For more details, refer to the
+[configuration documentation](../reference/configuration.md).
+
+Changes to these settings will be applied to all subsequent interactions with
+Gemini CLI.
+
+## Best practices for model selection
+
+- **Default to Auto.** For most users, the _Auto_ option model provides a
+  balance between speed and performance, automatically selecting the correct
+  model based on the complexity of the task. Example: Developing a web
+  application could include a mix of complex tasks (building architecture and
+  scaffolding the project) and simple tasks (generating CSS).
+
+- **Switch to Pro if you aren't getting the results you want.** If you think you
+  need your model to be a little "smarter," you can manually select Pro. Pro
+  will provide you with the highest levels of reasoning and creativity. Example:
+  A complex or multi-stage debugging task.
+
+- **Switch to Flash or Flash-Lite if you need faster results.** If you need a
+  simple response quickly, Flash or Flash-Lite is the best option. Example:
+  Converting a JSON object to a YAML string.