@anthropic-field/core 0.1.0

package/dist/docs/cli/index.md

@@ -0,0 +1,65 @@
+# Gemini CLI
+
+Within Gemini CLI, `packages/cli` is the frontend for users to send and receive
+prompts with the Gemini AI model and its associated tools. For a general
+overview of Gemini CLI, see the [main documentation page](../index.md).
+
+## Basic features
+
+- **[Commands](./commands.md):** A reference for all built-in slash commands
+- **[Custom commands](./custom-commands.md):** Create your own commands and
+  shortcuts for frequently used prompts.
+- **[Headless mode](./headless.md):** Use Gemini CLI programmatically for
+  scripting and automation.
+- **[Model selection](./model.md):** Configure the Gemini AI model used by the
+  CLI.
+- **[Settings](./settings.md):** Configure various aspects of the CLI's behavior
+  and appearance.
+- **[Themes](./themes.md):** Customizing the CLI's appearance with different
+  themes.
+- **[Keyboard shortcuts](./keyboard-shortcuts.md):** A reference for all
+  keyboard shortcuts to improve your workflow.
+- **[Tutorials](./tutorials.md):** Step-by-step guides for common tasks.
+
+## Advanced features
+
+- **[Checkpointing](./checkpointing.md):** Automatically save and restore
+  snapshots of your session and files.
+- **[Enterprise configuration](./enterprise.md):** Deploy and manage Gemini CLI
+  in an enterprise environment.
+- **[Sandboxing](./sandbox.md):** Isolate tool execution in a secure,
+  containerized environment.
+- **[Agent Skills](./skills.md):** Extend the CLI with specialized expertise and
+  procedural workflows.
+- **[Telemetry](./telemetry.md):** Configure observability to monitor usage and
+  performance.
+- **[Token caching](./token-caching.md):** Optimize API costs by caching tokens.
+- **[Trusted folders](./trusted-folders.md):** A security feature to control
+  which projects can use the full capabilities of the CLI.
+- **[Ignoring files (.geminiignore)](./gemini-ignore.md):** Exclude specific
+  files and directories from being accessed by tools.
+- **[Context files (GEMINI.md)](./gemini-md.md):** Provide persistent,
+  hierarchical context to the model.
+- **[System prompt override](./system-prompt.md):** Replace the built‑in system
+  instructions using `GEMINI_SYSTEM_MD`.
+
+## Non-interactive mode
+
+Gemini CLI can be run in a non-interactive mode, which is useful for scripting
+and automation. In this mode, you pipe input to the CLI, it executes the
+command, and then it exits.
+
+The following example pipes a command to Gemini CLI from your terminal:
+
+```bash
+echo "What is fine tuning?" | gemini
+```
+
+You can also use the `--prompt` or `-p` flag:
+
+```bash
+gemini -p "What is fine tuning?"
+```
+
+For comprehensive documentation on headless usage, scripting, automation, and
+advanced examples, see the **[Headless mode](./headless.md)** guide.

package/dist/docs/cli/keyboard-shortcuts.md

@@ -0,0 +1,140 @@
+# Gemini CLI keyboard shortcuts
+
+Gemini CLI ships with a set of default keyboard shortcuts for editing input,
+navigating history, and controlling the UI. Use this reference to learn the
+available combinations.
+
+<!-- KEYBINDINGS-AUTOGEN:START -->
+
+#### Basic Controls
+
+| Action                                                          | Keys       |
+| --------------------------------------------------------------- | ---------- |
+| Confirm the current selection or choice.                        | `Enter`    |
+| Dismiss dialogs or cancel the current focus.                    | `Esc`      |
+| Cancel the current request or quit the CLI when input is empty. | `Ctrl + C` |
+| Exit the CLI when the input buffer is empty.                    | `Ctrl + D` |
+
+#### Cursor Movement
+
+| Action                                      | Keys                                                         |
+| ------------------------------------------- | ------------------------------------------------------------ |
+| Move the cursor to the start of the line.   | `Ctrl + A`<br />`Home (no Shift, Ctrl)`                      |
+| Move the cursor to the end of the line.     | `Ctrl + E`<br />`End (no Shift, Ctrl)`                       |
+| Move the cursor up one line.                | `Up Arrow (no Shift, Alt, Ctrl, Cmd)`                        |
+| Move the cursor down one line.              | `Down Arrow (no Shift, Alt, Ctrl, Cmd)`                      |
+| Move the cursor one character to the left.  | `Left Arrow (no Shift, Alt, Ctrl, Cmd)`                      |
+| Move the cursor one character to the right. | `Right Arrow (no Shift, Alt, Ctrl, Cmd)`<br />`Ctrl + F`     |
+| Move the cursor one word to the left.       | `Ctrl + Left Arrow`<br />`Alt + Left Arrow`<br />`Alt + B`   |
+| Move the cursor one word to the right.      | `Ctrl + Right Arrow`<br />`Alt + Right Arrow`<br />`Alt + F` |
+
+#### Editing
+
+| Action                                           | Keys                                                             |
+| ------------------------------------------------ | ---------------------------------------------------------------- |
+| Delete from the cursor to the end of the line.   | `Ctrl + K`                                                       |
+| Delete from the cursor to the start of the line. | `Ctrl + U`                                                       |
+| Clear all text in the input field.               | `Ctrl + C`                                                       |
+| Delete the previous word.                        | `Ctrl + Backspace`<br />`Alt + Backspace`<br />`Ctrl + W`        |
+| Delete the next word.                            | `Ctrl + Delete`<br />`Alt + Delete`                              |
+| Delete the character to the left.                | `Backspace`<br />`Ctrl + H`                                      |
+| Delete the character to the right.               | `Delete`<br />`Ctrl + D`                                         |
+| Undo the most recent text edit.                  | `Cmd + Z (no Shift)`<br />`Alt + Z (no Shift)`                   |
+| Redo the most recent undone text edit.           | `Shift + Ctrl + Z`<br />`Shift + Cmd + Z`<br />`Shift + Alt + Z` |
+
+#### Scrolling
+
+| Action                   | Keys                              |
+| ------------------------ | --------------------------------- |
+| Scroll content up.       | `Shift + Up Arrow`                |
+| Scroll content down.     | `Shift + Down Arrow`              |
+| Scroll to the top.       | `Ctrl + Home`<br />`Shift + Home` |
+| Scroll to the bottom.    | `Ctrl + End`<br />`Shift + End`   |
+| Scroll up by one page.   | `Page Up`                         |
+| Scroll down by one page. | `Page Down`                       |
+
+#### History & Search
+
+| Action                                       | Keys                  |
+| -------------------------------------------- | --------------------- |
+| Show the previous entry in history.          | `Ctrl + P (no Shift)` |
+| Show the next entry in history.              | `Ctrl + N (no Shift)` |
+| Start reverse search through history.        | `Ctrl + R`            |
+| Submit the selected reverse-search match.    | `Enter (no Ctrl)`     |
+| Accept a suggestion while reverse searching. | `Tab`                 |
+| Browse and rewind previous interactions.     | `Double Esc`          |
+
+#### Navigation
+
+| Action                                             | Keys                                        |
+| -------------------------------------------------- | ------------------------------------------- |
+| Move selection up in lists.                        | `Up Arrow (no Shift)`                       |
+| Move selection down in lists.                      | `Down Arrow (no Shift)`                     |
+| Move up within dialog options.                     | `Up Arrow (no Shift)`<br />`K (no Shift)`   |
+| Move down within dialog options.                   | `Down Arrow (no Shift)`<br />`J (no Shift)` |
+| Move to the next item or question in a dialog.     | `Tab (no Shift)`                            |
+| Move to the previous item or question in a dialog. | `Shift + Tab`                               |
+
+#### Suggestions & Completions
+
+| Action                                  | Keys                                               |
+| --------------------------------------- | -------------------------------------------------- |
+| Accept the inline suggestion.           | `Tab`<br />`Enter (no Ctrl)`                       |
+| Move to the previous completion option. | `Up Arrow (no Shift)`<br />`Ctrl + P (no Shift)`   |
+| Move to the next completion option.     | `Down Arrow (no Shift)`<br />`Ctrl + N (no Shift)` |
+| Expand an inline suggestion.            | `Right Arrow`                                      |
+| Collapse an inline suggestion.          | `Left Arrow`                                       |
+
+#### Text Input
+
+| Action                                         | Keys                                                                                      |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Submit the current prompt.                     | `Enter (no Shift, Alt, Ctrl, Cmd)`                                                        |
+| Insert a newline without submitting.           | `Ctrl + Enter`<br />`Cmd + Enter`<br />`Alt + Enter`<br />`Shift + Enter`<br />`Ctrl + J` |
+| Open the current prompt in an external editor. | `Ctrl + X`                                                                                |
+| Paste from the clipboard.                      | `Ctrl + V`<br />`Cmd + V`<br />`Alt + V`                                                  |
+
+#### App Controls
+
+| Action                                                                                                | Keys                       |
+| ----------------------------------------------------------------------------------------------------- | -------------------------- |
+| Toggle detailed error information.                                                                    | `F12`                      |
+| Toggle the full TODO list.                                                                            | `Ctrl + T`                 |
+| Show IDE context details.                                                                             | `Ctrl + G`                 |
+| Toggle Markdown rendering.                                                                            | `Alt + M`                  |
+| Toggle copy mode when in alternate buffer mode.                                                       | `Ctrl + S`                 |
+| Toggle YOLO (auto-approval) mode for tool calls.                                                      | `Ctrl + Y`                 |
+| Cycle through approval modes: default (prompt), auto_edit (auto-approve edits), and plan (read-only). | `Shift + Tab`              |
+| Expand a height-constrained response to show additional lines when not in alternate buffer mode.      | `Ctrl + O`<br />`Ctrl + S` |
+| Ctrl+B                                                                                                | `Ctrl + B`                 |
+| Ctrl+L                                                                                                | `Ctrl + L`                 |
+| Ctrl+K                                                                                                | `Ctrl + K`                 |
+| Enter                                                                                                 | `Enter`                    |
+| Esc                                                                                                   | `Esc`                      |
+| Shift+Tab                                                                                             | `Shift + Tab`              |
+| Tab                                                                                                   | `Tab (no Shift)`           |
+| Tab                                                                                                   | `Tab (no Shift)`           |
+| Focus the shell input from the gemini input.                                                          | `Tab (no Shift)`           |
+| Focus the Gemini input from the shell input.                                                          | `Tab`                      |
+| Clear the terminal screen and redraw the UI.                                                          | `Ctrl + L`                 |
+| Restart the application.                                                                              | `R`                        |
+| Suspend the application (not yet implemented).                                                        | `Ctrl + Z`                 |
+
+<!-- KEYBINDINGS-AUTOGEN:END -->
+
+## Additional context-specific shortcuts
+
+- `Option+B/F/M` (macOS only): Are interpreted as `Cmd+B/F/M` even if your
+  terminal isn't configured to send Meta with Option.
+- `!` on an empty prompt: Enter or exit shell mode.
+- `\` (at end of a line) + `Enter`: Insert a newline without leaving single-line
+  mode.
+- `Esc` pressed twice quickly: Clear the input prompt if it is not empty,
+  otherwise browse and rewind previous interactions.
+- `Up Arrow` / `Down Arrow`: When the cursor is at the top or bottom of a
+  single-line input, navigate backward or forward through prompt history.
+- `Number keys (1-9, multi-digit)` inside selection dialogs: Jump directly to
+  the numbered radio option and confirm when the full number is entered.
+- `Double-click` on a paste placeholder (`[Pasted Text: X lines]`) in alternate
+  buffer mode: Expand to view full content inline. Double-click again to
+  collapse.

package/dist/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/dist/docs/cli/model.md

@@ -0,0 +1,62 @@
+# 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 (if enabled), gemini-3-flash-preview (if enabled) |
+| 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.
+
+### Gemini 3 and preview features
+
+> **Note:** Gemini 3 is not currently available on all account types. To learn
+> more about Gemini 3 access, refer to
+> [Gemini 3 on Gemini CLI](../get-started/gemini-3.md).
+
+To enable Gemini 3 Pro and Gemini 3 Flash (if available), enable
+[**Preview Features** by using the `settings` command](../cli/settings.md).
+
+You can also use the `--model` flag to specify a particular Gemini model on
+startup. For more details, refer to the
+[configuration documentation](../get-started/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.

package/dist/docs/cli/rewind.md

@@ -0,0 +1,51 @@
+# Rewind
+
+The `/rewind` command allows you to go back to a previous state in your
+conversation and, optionally, revert any file changes made by the AI during
+those interactions. This is a powerful tool for undoing mistakes, exploring
+different approaches, or simply cleaning up your session history.
+
+## Usage
+
+To use the rewind feature, simply type `/rewind` into the input prompt and press
+**Enter**.
+
+Alternatively, you can use the keyboard shortcut: **Press `Esc` twice**.
+
+## Interface
+
+When you trigger a rewind, an interactive list of your previous interactions
+appears.
+
+1.  **Select Interaction:** Use the **Up/Down arrow keys** to navigate through
+    the list. The most recent interactions are at the bottom.
+2.  **Preview:** As you select an interaction, you'll see a preview of the user
+    prompt and, if applicable, the number of files changed during that step.
+3.  **Confirm Selection:** Press **Enter** on the interaction you want to rewind
+    back to.
+4.  **Action Selection:** After selecting an interaction, you'll be presented
+    with a confirmation dialog with up to three options:
+    - **Rewind conversation and revert code changes:** Reverts both the chat
+      history and the file modifications to the state before the selected
+      interaction.
+    - **Rewind conversation:** Only reverts the chat history. File changes are
+      kept.
+    - **Revert code changes:** Only reverts the file modifications. The chat
+      history is kept.
+    - **Do nothing (esc):** Cancels the rewind operation.
+
+If no code changes were made since the selected point, the options related to
+reverting code changes will be hidden.
+
+## Key Considerations
+
+- **Destructive Action:** Rewinding is a destructive action for your current
+  session history and potentially your files. Use it with care.
+- **Agent Awareness:** When you rewind the conversation, the AI model loses all
+  memory of the interactions that were removed. If you only revert code changes,
+  you may need to inform the model that the files have changed.
+- **Manual Edits:** Rewinding only affects file changes made by the AI's edit
+  tools. It does **not** undo manual edits you've made or changes triggered by
+  the shell tool (`!`).
+- **Compression:** Rewind works across chat compression points by reconstructing
+  the history from stored session data.

package/dist/docs/cli/sandbox.md

@@ -0,0 +1,171 @@
+# Sandboxing in the Gemini CLI
+
+This document provides a guide to sandboxing in the Gemini CLI, including
+prerequisites, quickstart, and configuration.
+
+## Prerequisites
+
+Before using sandboxing, you need to install and set up the Gemini CLI:
+
+```bash
+npm install -g @google/gemini-cli
+```
+
+To verify the installation:
+
+```bash
+gemini --version
+```
+
+## Overview of sandboxing
+
+Sandboxing isolates potentially dangerous operations (such as shell commands or
+file modifications) from your host system, providing a security barrier between
+AI operations and your environment.
+
+The benefits of sandboxing include:
+
+- **Security**: Prevent accidental system damage or data loss.
+- **Isolation**: Limit file system access to project directory.
+- **Consistency**: Ensure reproducible environments across different systems.
+- **Safety**: Reduce risk when working with untrusted code or experimental
+  commands.
+
+## Sandboxing methods
+
+Your ideal method of sandboxing may differ depending on your platform and your
+preferred container solution.
+
+### 1. macOS Seatbelt (macOS only)
+
+Lightweight, built-in sandboxing using `sandbox-exec`.
+
+**Default profile**: `permissive-open` - restricts writes outside project
+directory but allows most other operations.
+
+### 2. Container-based (Docker/Podman)
+
+Cross-platform sandboxing with complete process isolation.
+
+**Note**: Requires building the sandbox image locally or using a published image
+from your organization's registry.
+
+## Quickstart
+
+```bash
+# Enable sandboxing with command flag
+gemini -s -p "analyze the code structure"
+
+# Use environment variable
+export GEMINI_SANDBOX=true
+gemini -p "run the test suite"
+
+# Configure in settings.json
+{
+  "tools": {
+    "sandbox": "docker"
+  }
+}
+```
+
+## Configuration
+
+### Enable sandboxing (in order of precedence)
+
+1. **Command flag**: `-s` or `--sandbox`
+2. **Environment variable**: `GEMINI_SANDBOX=true|docker|podman|sandbox-exec`
+3. **Settings file**: `"sandbox": true` in the `tools` object of your
+   `settings.json` file (e.g., `{"tools": {"sandbox": true}}`).
+
+### macOS Seatbelt profiles
+
+Built-in profiles (set via `SEATBELT_PROFILE` env var):
+
+- `permissive-open` (default): Write restrictions, network allowed
+- `permissive-closed`: Write restrictions, no network
+- `permissive-proxied`: Write restrictions, network via proxy
+- `restrictive-open`: Strict restrictions, network allowed
+- `restrictive-closed`: Maximum restrictions
+
+### Custom sandbox flags
+
+For container-based sandboxing, you can inject custom flags into the `docker` or
+`podman` command using the `SANDBOX_FLAGS` environment variable. This is useful
+for advanced configurations, such as disabling security features for specific
+use cases.
+
+**Example (Podman)**:
+
+To disable SELinux labeling for volume mounts, you can set the following:
+
+```bash
+export SANDBOX_FLAGS="--security-opt label=disable"
+```
+
+Multiple flags can be provided as a space-separated string:
+
+```bash
+export SANDBOX_FLAGS="--flag1 --flag2=value"
+```
+
+## Linux UID/GID handling
+
+The sandbox automatically handles user permissions on Linux. Override these
+permissions with:
+
+```bash
+export SANDBOX_SET_UID_GID=true   # Force host UID/GID
+export SANDBOX_SET_UID_GID=false  # Disable UID/GID mapping
+```
+
+## Troubleshooting
+
+### Common issues
+
+**"Operation not permitted"**
+
+- Operation requires access outside sandbox.
+- Try more permissive profile or add mount points.
+
+**Missing commands**
+
+- Add to custom Dockerfile.
+- Install via `sandbox.bashrc`.
+
+**Network issues**
+
+- Check sandbox profile allows network.
+- Verify proxy configuration.
+
+### Debug mode
+
+```bash
+DEBUG=1 gemini -s -p "debug command"
+```
+
+**Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect
+gemini-cli due to automatic exclusion. Use `.gemini/.env` files for gemini-cli
+specific debug settings.
+
+### Inspect sandbox
+
+```bash
+# Check environment
+gemini -s -p "run shell command: env | grep SANDBOX"
+
+# List mounts
+gemini -s -p "run shell command: mount | grep workspace"
+```
+
+## Security notes
+
+- Sandboxing reduces but doesn't eliminate all risks.
+- Use the most restrictive profile that allows your work.
+- Container overhead is minimal after first build.
+- GUI applications may not work in sandboxes.
+
+## Related documentation
+
+- [Configuration](../get-started/configuration.md): Full configuration options.
+- [Commands](./commands.md): Available commands.
+- [Troubleshooting](../troubleshooting.md): General troubleshooting.