@machina.ai/cell-cli-core 1.38.1-rc2 → 1.40.1-rc2

package/dist/docs/cli/settings.md

@@ -24,20 +24,22 @@ they appear in the UI.
 
 ### General
 
-| UI Label                | Setting                            | Description                                                                                                                                                                                                                                                   | Default     |
-| ----------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
-| Vim Mode                | `general.vimMode`                  | Enable Vim keybindings                                                                                                                                                                                                                                        | `false`     |
-| Default Approval Mode   | `general.defaultApprovalMode`      | The default approval mode for tool execution. 'default' prompts for approval, 'auto_edit' auto-approves edit tools, and 'plan' is read-only mode. YOLO mode (auto-approve all actions) can only be enabled via command line (--yolo or --approval-mode=yolo). | `"default"` |
-| Enable Auto Update      | `general.enableAutoUpdate`         | Enable automatic updates.                                                                                                                                                                                                                                     | `true`      |
-| Enable Notifications    | `general.enableNotifications`      | Enable run-event notifications for action-required prompts and session completion.                                                                                                                                                                            | `false`     |
-| Enable Plan Mode        | `general.plan.enabled`             | Enable Plan Mode for read-only safety during planning.                                                                                                                                                                                                        | `true`      |
-| Plan Directory          | `general.plan.directory`           | The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory. A custom directory requires a policy to allow write access in Plan Mode.                                                                     | `undefined` |
-| Plan Model Routing      | `general.plan.modelRouting`        | Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pro for the planning phase and Flash for the implementation phase.                                                                                                          | `true`      |
-| Retry Fetch Errors      | `general.retryFetchErrors`         | Retry on "exception TypeError: fetch failed sending request" errors.                                                                                                                                                                                          | `true`      |
-| Max Chat Model Attempts | `general.maxAttempts`              | Maximum number of attempts for requests to the main chat model. Cannot exceed 10.                                                                                                                                                                             | `10`        |
-| Debug Keystroke Logging | `general.debugKeystrokeLogging`    | Enable debug logging of keystrokes to the console.                                                                                                                                                                                                            | `false`     |
-| Enable Session Cleanup  | `general.sessionRetention.enabled` | Enable automatic session cleanup                                                                                                                                                                                                                              | `true`      |
-| Keep chat history       | `general.sessionRetention.maxAge`  | Automatically delete chats older than this time period (e.g., "30d", "7d", "24h", "1w")                                                                                                                                                                       | `"30d"`     |
+| UI Label                      | Setting                            | Description                                                                                                                                                                                                                                                   | Default     |
+| ----------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| Vim Mode                      | `general.vimMode`                  | Enable Vim keybindings                                                                                                                                                                                                                                        | `false`     |
+| Default Approval Mode         | `general.defaultApprovalMode`      | The default approval mode for tool execution. 'default' prompts for approval, 'auto_edit' auto-approves edit tools, and 'plan' is read-only mode. YOLO mode (auto-approve all actions) can only be enabled via command line (--yolo or --approval-mode=yolo). | `"default"` |
+| Enable Auto Update            | `general.enableAutoUpdate`         | Enable automatic updates.                                                                                                                                                                                                                                     | `true`      |
+| Enable Terminal Notifications | `general.enableNotifications`      | Enable terminal run-event notifications for action-required prompts and session completion.                                                                                                                                                                   | `false`     |
+| Terminal Notification Method  | `general.notificationMethod`       | How to send terminal notifications.                                                                                                                                                                                                                           | `"auto"`    |
+| Enable Plan Mode              | `general.plan.enabled`             | Enable Plan Mode for read-only safety during planning.                                                                                                                                                                                                        | `true`      |
+| Plan Directory                | `general.plan.directory`           | The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory. A custom directory requires a policy to allow write access in Plan Mode.                                                                     | `undefined` |
+| Plan Model Routing            | `general.plan.modelRouting`        | Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pro for the planning phase and Flash for the implementation phase.                                                                                                          | `true`      |
+| Retry Fetch Errors            | `general.retryFetchErrors`         | Retry on "exception TypeError: fetch failed sending request" errors.                                                                                                                                                                                          | `true`      |
+| Max Chat Model Attempts       | `general.maxAttempts`              | Maximum number of attempts for requests to the main chat model. Cannot exceed 10.                                                                                                                                                                             | `10`        |
+| Debug Keystroke Logging       | `general.debugKeystrokeLogging`    | Enable debug logging of keystrokes to the console.                                                                                                                                                                                                            | `false`     |
+| Enable Session Cleanup        | `general.sessionRetention.enabled` | Enable automatic session cleanup                                                                                                                                                                                                                              | `true`      |
+| Keep chat history             | `general.sessionRetention.maxAge`  | Automatically delete chats older than this time period (e.g., "30d", "7d", "24h", "1w")                                                                                                                                                                       | `"30d"`     |
+| Topic & Update Narration      | `general.topicUpdateNarration`     | Enable the Topic & Update communication model for reduced chattiness and structured progress reporting.                                                                                                                                                       | `true`      |
 
 ### Output
 
@@ -153,9 +155,9 @@ they appear in the UI.
 
 ### Advanced
 
-| UI Label                          | Setting                        | Description                                   | Default |
-| --------------------------------- | ------------------------------ | --------------------------------------------- | ------- |
-| Auto Configure Max Old Space Size | `advanced.autoConfigureMemory` | Automatically configure Node.js memory limits | `true`  |
+| UI Label                          | Setting                        | Description                                                                                                                                                                                                           | Default |
+| --------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| Auto Configure Max Old Space Size | `advanced.autoConfigureMemory` | Automatically configure Node.js memory limits. Note: Because memory is allocated during the initial process boot, this setting is only read from the global user settings file and ignores workspace-level overrides. | `true`  |
 
 ### LoadMemoryFromIncludeDirectories
 
@@ -177,17 +179,19 @@ they appear in the UI.
 
 ### Experimental
 
-| UI Label                                             | Setting                             | Description                                                                                                                                               | Default |
-| ---------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| Enable Git Worktrees                                 | `experimental.worktrees`            | Enable automated Git worktree management for parallel work.                                                                                               | `false` |
-| Use OSC 52 Paste                                     | `experimental.useOSC52Paste`        | Use OSC 52 for pasting. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it). | `false` |
-| Use OSC 52 Copy                                      | `experimental.useOSC52Copy`         | Use OSC 52 for copying. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it). | `false` |
-| Model Steering                                       | `experimental.modelSteering`        | Enable model steering (user hints) to guide the model during tool execution.                                                                              | `false` |
-| Direct Web Fetch                                     | `experimental.directWebFetch`       | Enable web fetch behavior that bypasses LLM summarization.                                                                                                | `false` |
-| Memory Manager Agent                                 | `experimental.memoryManager`        | Replace the built-in save_memory tool with a memory manager subagent that supports adding, removing, de-duplicating, and organizing memories.             | `false` |
-| Use the generalist profile to manage agent contexts. | `experimental.generalistProfile`    | Suitable for general coding and software development tasks.                                                                                               | `false` |
-| Enable Context Management                            | `experimental.contextManagement`    | Enable logic for context management.                                                                                                                      | `false` |
-| Topic & Update Narration                             | `experimental.topicUpdateNarration` | Enable the experimental Topic & Update communication model for reduced chattiness and structured progress reporting.                                      | `false` |
+| UI Label                                             | Setting                                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Default |
+| ---------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
+| Enable Git Worktrees                                 | `experimental.worktrees`                        | Enable automated Git worktree management for parallel work.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `false` |
+| Use OSC 52 Paste                                     | `experimental.useOSC52Paste`                    | Use OSC 52 for pasting. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it).                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `false` |
+| Use OSC 52 Copy                                      | `experimental.useOSC52Copy`                     | Use OSC 52 for copying. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it).                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `false` |
+| Model Steering                                       | `experimental.modelSteering`                    | Enable model steering (user hints) to guide the model during tool execution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false` |
+| Direct Web Fetch                                     | `experimental.directWebFetch`                   | Enable web fetch behavior that bypasses LLM summarization.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `false` |
+| Enable Gemma Model Router                            | `experimental.gemmaModelRouter.enabled`         | Enable the Gemma Model Router (experimental). Requires a local endpoint serving Gemma via the Gemini API using LiteRT-LM shim.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `false` |
+| Auto-start LiteRT Server                             | `experimental.gemmaModelRouter.autoStartServer` | Automatically start the LiteRT-LM server when Cell CLI starts and the Gemma router is enabled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `false` |
+| Memory v2                                            | `experimental.memoryV2`                         | Disable the built-in save_memory tool and let the main agent persist project context by editing markdown files directly with edit/write_file. Route facts across four tiers: team-shared conventions go to project GEMINI.md files, project-specific personal notes go to the per-project private memory folder (MEMORY.md as index + sibling .md files for detail), and cross-project personal preferences go to the global ~/.cell-cli/GEMINI.md (the only file under ~/.cell-cli/ that the agent can edit — settings, credentials, etc. remain off-limits). Set to false to fall back to the legacy save_memory tool. | `true`  |
+| Auto Memory                                          | `experimental.autoMemory`                       | Automatically extract reusable skills from past sessions in the background. Review results with /memory inbox.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `false` |
+| Use the generalist profile to manage agent contexts. | `experimental.generalistProfile`                | Suitable for general coding and software development tasks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `false` |
+| Enable Context Management                            | `experimental.contextManagement`                | Enable logic for context management.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `false` |
 
 ### Skills
 

package/dist/docs/cli/system-prompt.md

@@ -24,7 +24,7 @@ project-specific behavior or create a customized persona.
 
 You can set the environment variable temporarily in your shell, or persist it
 via a `.cell-cli/.env` file. See
-[Persisting Environment Variables](../get-started/authentication.md#persisting-environment-variables).
+[Persisting Environment Variables](../get-started/authentication.mdx#persisting-environment-variables).
 
 - Use the project default path (`.cell-cli/system.md`):
   - `CELL_SYSTEM_MD=true` or `CELL_SYSTEM_MD=1`
@@ -35,7 +35,7 @@ via a `.cell-cli/.env` file. See
   - `CELL_SYSTEM_MD=/absolute/path/to/my-system.md`
   - Relative paths are supported and resolved from the current working
     directory.
-  - Tilde expansion is supported (e.g., `~/my-system.md`).
+  - Tilde expansion is supported (for example, `~/my-system.md`).
 
 - Disable the override (use built‑in prompt):
   - `CELL_SYSTEM_MD=false` or `CELL_SYSTEM_MD=0` or unset the variable.
@@ -51,7 +51,7 @@ error with: `missing system prompt file '<path>'`.
   - Create `.cell-cli/system.md`, then add to `.cell-cli/.env`:
     - `CELL_SYSTEM_MD=1`
 - Use a custom file under your home directory:
-  - `CELL_SYSTEM_MD=~/prompts/SYSTEM.md gemini`
+  - `CELL_SYSTEM_MD=~/prompts/system.md gemini`
 
 ## UI indicator
 
@@ -70,7 +70,7 @@ dynamically include built-in content:
 - `${AvailableTools}`: Injects a bulleted list of all currently enabled tool
   names.
 - Tool Name Variables: Injects the actual name of a tool using the pattern:
-  `${toolName}_ToolName` (e.g., `${write_file_ToolName}`,
+  `${toolName}_ToolName` (for example, `${write_file_ToolName}`,
   `${run_shell_command_ToolName}`).
 
   This pattern is generated dynamically for all available tools.
@@ -102,17 +102,17 @@ safety and workflow rules.
 
 This creates the file and writes the current built‑in system prompt to it.
 
-## Best practices: SYSTEM.md vs GEMINI.md
+## Best practices: system.md vs GEMINI.md
 
-- SYSTEM.md (firmware):
+- system.md (firmware):
   - Non‑negotiable operational rules: safety, tool‑use protocols, approvals, and
     mechanics that keep the CLI reliable.
   - Stable across tasks and projects (or per project when needed).
 - GEMINI.md (strategy):
   - Persona, goals, methodologies, and project/domain context.
-  - Evolves per task; relies on SYSTEM.md for safe execution.
+  - Evolves per task; relies on system.md for safe execution.
 
-Keep SYSTEM.md minimal but complete for safety and tool operation. Keep
+Keep system.md minimal but complete for safety and tool operation. Keep
 GEMINI.md focused on high‑level guidance and project specifics.
 
 ## Troubleshooting

package/dist/docs/cli/telemetry.md

@@ -35,17 +35,18 @@ The observability system provides:
 You control telemetry behavior through the `.cell-cli/settings.json` file.
 Environment variables can override these settings.
 
-| Setting        | Environment Variable           | Description                                         | Values            | Default                 |
-| -------------- | ------------------------------ | --------------------------------------------------- | ----------------- | ----------------------- |
-| `enabled`      | `CELL_TELEMETRY_ENABLED`       | Enable or disable telemetry                         | `true`/`false`    | `false`                 |
-| `target`       | `CELL_TELEMETRY_TARGET`        | Where to send telemetry data                        | `"gcp"`/`"local"` | `"local"`               |
-| `otlpEndpoint` | `CELL_TELEMETRY_OTLP_ENDPOINT` | OTLP collector endpoint                             | URL string        | `http://localhost:4317` |
-| `otlpProtocol` | `CELL_TELEMETRY_OTLP_PROTOCOL` | OTLP transport protocol                             | `"grpc"`/`"http"` | `"grpc"`                |
-| `outfile`      | `CELL_TELEMETRY_OUTFILE`       | Save telemetry to file (overrides `otlpEndpoint`)   | file path         | -                       |
-| `logPrompts`   | `CELL_TELEMETRY_LOG_PROMPTS`   | Include prompts in telemetry logs                   | `true`/`false`    | `true`                  |
-| `useCollector` | `CELL_TELEMETRY_USE_COLLECTOR` | Use external OTLP collector (advanced)              | `true`/`false`    | `false`                 |
-| `useCliAuth`   | `CELL_TELEMETRY_USE_CLI_AUTH`  | Use CLI credentials for telemetry (GCP target only) | `true`/`false`    | `false`                 |
-| -              | `CELL_CLI_SURFACE`             | Optional custom label for traffic reporting         | string            | -                       |
+| Setting        | Environment Variable            | Description                                         | Values            | Default                 |
+| -------------- | ------------------------------- | --------------------------------------------------- | ----------------- | ----------------------- |
+| `enabled`      | `CELL_TELEMETRY_ENABLED`        | Enable or disable telemetry                         | `true`/`false`    | `false`                 |
+| `traces`       | `CELL_TELEMETRY_TRACES_ENABLED` | Enable detailed attribute tracing                   | `true`/`false`    | `false`                 |
+| `target`       | `CELL_TELEMETRY_TARGET`         | Where to send telemetry data                        | `"gcp"`/`"local"` | `"local"`               |
+| `otlpEndpoint` | `CELL_TELEMETRY_OTLP_ENDPOINT`  | OTLP collector endpoint                             | URL string        | `http://localhost:4317` |
+| `otlpProtocol` | `CELL_TELEMETRY_OTLP_PROTOCOL`  | OTLP transport protocol                             | `"grpc"`/`"http"` | `"grpc"`                |
+| `outfile`      | `CELL_TELEMETRY_OUTFILE`        | Save telemetry to file (overrides `otlpEndpoint`)   | file path         | -                       |
+| `logPrompts`   | `CELL_TELEMETRY_LOG_PROMPTS`    | Include prompts in telemetry logs                   | `true`/`false`    | `true`                  |
+| `useCollector` | `CELL_TELEMETRY_USE_COLLECTOR`  | Use external OTLP collector (advanced)              | `true`/`false`    | `false`                 |
+| `useCliAuth`   | `CELL_TELEMETRY_USE_CLI_AUTH`   | Use CLI credentials for telemetry (GCP target only) | `true`/`false`    | `false`                 |
+| -              | `CELL_CLI_SURFACE`              | Optional custom label for traffic reporting         | string            | -                       |
 
 **Note on boolean environment variables:** For boolean settings like `enabled`,
 setting the environment variable to `true` or `1` enables the feature.
@@ -1235,6 +1236,12 @@ These metrics follow standard [OpenTelemetry GenAI semantic conventions].
 Traces provide an "under-the-hood" view of agent and backend operations. Use
 traces to debug tool interactions and optimize performance.
 
+<!-- prettier-ignore -->
+> [!NOTE]
+> Detailed trace attributes (like full prompts and tool outputs) are disabled by default
+> to minimize overhead. You must explicitly set `telemetry.traces` to `true` (or set
+> `CELL_TELEMETRY_TRACES_ENABLED=true`) to capture them.
+
 Every trace captures rich metadata via standard span attributes.
 
 <details open>

package/dist/docs/cli/themes.md

@@ -117,8 +117,8 @@ least `background.primary`, `text.primary`, `text.secondary`, and the various
 accent colors via `text.link`, `text.accent`, and `status` to ensure a cohesive
 UI.
 
-You can use either hex codes (e.g., `#FF0000`) **or** standard CSS color names
-(e.g., `coral`, `teal`, `blue`) for any color value. See
+You can use either hex codes (for example, `#FF0000`) **or** standard CSS color
+names (for example, `coral`, `teal`, `blue`) for any color value. See
 [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords)
 for a full list of supported names.
 

package/dist/docs/cli/trusted-folders.md

@@ -1,7 +1,7 @@
 # Trusted Folders
 
 The Trusted Folders feature is a security setting that gives you control over
-which projects can use the full capabilities of the Cell CLI. It prevents
+which projects can use the full capabilities of Cell CLI. It prevents
 potentially malicious code from running by asking you to approve a folder before
 the CLI loads any project-specific configurations from it.
 
@@ -24,12 +24,12 @@ Add the following to your user `settings.json` file:
 
 ## How it works: The trust dialog
 
-Once the feature is enabled, the first time you run the Cell CLI from a folder,
-a dialog will automatically appear, prompting you to make a choice:
+Once the feature is enabled, the first time you run Cell CLI from a folder, a
+dialog will automatically appear, prompting you to make a choice:
 
-- **Trust folder**: Grants full trust to the current folder (e.g.,
+- **Trust folder**: Grants full trust to the current folder (for example,
   `my-project`).
-- **Trust parent folder**: Grants trust to the parent directory (e.g.,
+- **Trust parent folder**: Grants trust to the parent directory (for example,
   `safe-projects`), which automatically trusts all of its subdirectories as
   well. This is useful if you keep all your safe projects in one place.
 - **Don't trust**: Marks the folder as untrusted. The CLI will operate in a
@@ -40,9 +40,9 @@ you will only be asked once per folder.
 
 ## Understanding folder contents: The discovery phase
 
-Before you make a choice, the Cell CLI performs a **discovery phase** to scan
-the folder for potential configurations. This information is displayed in the
-trust dialog to help you make an informed decision.
+Before you make a choice, Cell CLI performs a **discovery phase** to scan the
+folder for potential configurations. This information is displayed in the trust
+dialog to help you make an informed decision.
 
 The discovery UI lists the following categories of items found in the project:
 
@@ -63,15 +63,15 @@ attention:
   settings, such as auto-approving certain tools or disabling the security
   sandbox.
 - **Discovery Errors**: If the CLI encounters issues while scanning the folder
-  (e.g., a malformed `settings.json` file), these errors will be displayed
-  prominently.
+  (for example, a malformed `settings.json` file), these errors will be
+  displayed prominently.
 
 By reviewing these details, you can ensure that you only grant trust to projects
 that you know are safe.
 
 ## Why trust matters: The impact of an untrusted workspace
 
-When a folder is **untrusted**, the Cell CLI runs in a restricted "safe mode" to
+When a folder is **untrusted**, Cell CLI runs in a restricted "safe mode" to
 protect you. In this mode, the following features are disabled:
 
 1.  **Workspace settings are ignored**: The CLI will **not** load the
@@ -97,8 +97,36 @@ protect you. In this mode, the following features are disabled:
     commands from .toml files, including both project-specific and global user
     commands.
 
-Granting trust to a folder unlocks the full functionality of the Cell CLI for
-that workspace.
+Granting trust to a folder unlocks the full functionality of Cell CLI for that
+workspace.
+
+## Headless and automated environments
+
+When running Cell CLI in a headless environment (for example, a CI/CD pipeline)
+where interactive prompts are not possible, the trust dialog cannot be
+displayed. If the folder is untrusted and the Folder Trust feature is enabled,
+the CLI will throw a `FatalUntrustedWorkspaceError` and exit.
+
+To proceed in these environments, you can bypass the trust check using one of
+the following methods:
+
+- **Command-line flag:** Run the CLI with the `--skip-trust` flag.
+- **Environment variable:** Set the `CELL_CLI_TRUST_WORKSPACE=true` environment
+  variable.
+
+These methods will trust the current workspace for the duration of the session
+without prompting.
+
+For detailed instructions on managing folder trust within CI/CD workflows,
+review the
+[Cell CLI trust guidance for GitHub Actions](https://github.com/google-github-actions/run-gemini-cli/blob/main/docs/trust-guidance.md).
+
+## Overriding the trust file location
+
+By default, trust settings are saved to `~/.cell-cli/trustedFolders.json`. If
+you need to store this file in a different location, you can set the
+`CELL_CLI_TRUSTED_FOLDERS_PATH` environment variable to the desired absolute
+file path.
 
 ## Managing your trust settings
 

package/dist/docs/cli/tutorials/mcp-setup.md

@@ -102,7 +102,7 @@ The agent will:
 ## Troubleshooting
 
 - **Server won't start?** Try running the docker command manually in your
-  terminal to see if it prints an error (e.g., "image not found").
+  terminal to see if it prints an error (for example, "image not found").
 - **Tools not found?** Run `/mcp reload` to force the CLI to re-query the server
   for its capabilities.
 

package/dist/docs/cli/tutorials/memory-management.md

@@ -50,7 +50,7 @@ loaded into every conversation.
 
 ### Scenario: Using the hierarchy
 
-Context is loaded hierarchically. This allows you to have general rules for
+Context is loaded hierarchically. This lets you have general rules for
 everything and specific rules for sub-projects.
 
 1.  **Global:** `~/.cell-cli/GEMINI.md` (Rules for _every_ project you work on).
@@ -124,3 +124,5 @@ immediately. Force a reload with:
 - Explore the [Command reference](../../reference/commands.md) for more
   `/memory` options.
 - Read the technical spec for [Project context](../../cli/gemini-md.md).
+- Try the experimental [Auto Memory](../auto-memory.md) feature to extract
+  reusable skills from your past sessions automatically.

package/dist/docs/cli/tutorials/plan-mode-steering.md

@@ -79,8 +79,8 @@ each step with higher confidence and fewer errors.
 - **Steer early:** Providing feedback during the research phase is more
   efficient than waiting for the final plan to be drafted.
 - **Use for context:** Steering is a great way to provide knowledge that might
-  not be obvious from reading the code (e.g., "We are planning to deprecate this
-  module next month").
+  not be obvious from reading the code (for example, "We are planning to
+  deprecate this module next month").
 
 ## Next steps
 

package/dist/docs/cli/tutorials/session-management.md

@@ -35,7 +35,7 @@ browser.
 
 This opens a searchable list of all your past sessions. You'll see:
 
-- A timestamp (e.g., "2 hours ago").
+- A timestamp (for example, "2 hours ago").
 - The first user message (helping you identify the topic).
 - The number of turns in the conversation.
 

package/dist/docs/cli/tutorials/shell-commands.md

@@ -58,7 +58,7 @@ watchers.
 
 **Prompt:** `Start the React dev server in the background.`
 
-Gemini will run the command (e.g., `npm run dev`) and detach it.
+Gemini will run the command (for example, `npm run dev`) and detach it.
 
 ### Scenario: Viewing active shells
 

package/dist/docs/cli/tutorials/task-planning.md

@@ -7,7 +7,7 @@ progress with the todo list.
 ## Prerequisites
 
 - Cell CLI installed and authenticated.
-- A complex task in mind (e.g., a multi-file refactor or new feature).
+- A complex task in mind (for example, a multi-file refactor or new feature).
 
 ## Why use task planning?
 
@@ -58,7 +58,7 @@ Tell the agent to proceed.
 As the agent works, you'll see the todo list update in real-time above the input
 box.
 
-- **Current focus:** The active task is highlighted (e.g.,
+- **Current focus:** The active task is highlighted (for example,
   `[IN_PROGRESS] Create tsconfig.json`).
 - **Progress:** Completed tasks are marked as done.
 
@@ -90,4 +90,4 @@ living document, not a static text block.
 - See the [Todo tool reference](../../tools/todos.md) for technical schema
   details.
 - Learn about [Memory management](memory-management.md) to persist planning
-  preferences (e.g., "Always create a test plan first").
+  preferences (for example, "Always create a test plan first").

package/dist/docs/core/index.md

@@ -29,7 +29,7 @@ While the `packages/cli` portion of Cell CLI provides the user interface,
   potentially incorporating conversation history, tool definitions, and
   instructional context from `GEMINI.md` files.
 - **Tool management & orchestration:**
-  - Registering available tools (e.g., file system tools, shell command
+  - Registering available tools (for example, file system tools, shell command
     execution).
   - Interpreting tool use requests from the Gemini model.
   - Executing the requested tools with the provided arguments.
@@ -45,7 +45,7 @@ The core plays a vital role in security:
 
 - **API key management:** It handles the `GEMINI_API_KEY` and ensures it's used
   securely when communicating with the Gemini API.
-- **Tool execution:** When tools interact with the local system (e.g.,
+- **Tool execution:** When tools interact with the local system (for example,
   `run_shell_command`), the core (and its underlying tool implementations) must
   do so with appropriate caution, often involving sandboxing mechanisms to
   prevent unintended modifications.
@@ -70,7 +70,7 @@ use the CLI even if the default "pro" model is rate-limited.
 
 If you are using the default "pro" model and the CLI detects that you are being
 rate-limited, it automatically switches to the "flash" model for the current
-session. This allows you to continue working without interruption.
+session. This lets you continue working without interruption.
 
 Internal utility calls that use `gemini-2.5-flash-lite` (for example, prompt
 completion and classification) silently fall back to `gemini-2.5-flash` and
@@ -90,9 +90,8 @@ in a hierarchical manner, starting from the current working directory and moving
 up to the project root and the user's home directory. It also searches in
 subdirectories.
 
-This allows you to have global, project-level, and component-level context
-files, which are all combined to provide the model with the most relevant
-information.
+This lets you have global, project-level, and component-level context files,
+which are all combined to provide the model with the most relevant information.
 
 You can use the [`/memory` command](../reference/commands.md) to `show`, `add`,
 and `refresh` the content of loaded `GEMINI.md` files.

package/dist/docs/core/local-model-routing.md

@@ -108,7 +108,7 @@ Download complete.
 $ ./lit.lit.macos_arm64 pull gemma3-1b-gpu-custom
 
 [Legal] The model you are about to download is governed by
-the Gemma Terms of Use and Prohibited Use Policy. Please review these terms and ensure you agree before continuing.
+the Gemma Terms of Use and Prohibited Use Policy. Review these terms and ensure you agree before continuing.
 
 Full Terms: https://ai.google.dev/gemma/terms
 Prohibited Use Policy: https://ai.google.dev/gemma/prohibited_use_policy

package/dist/docs/core/remote-agents.md

@@ -430,7 +430,7 @@ both behind auth.
 
 ## Managing Subagents
 
-Users can manage subagents using the following commands within the Cell CLI:
+Users can manage subagents using the following commands within Cell CLI:
 
 - `/agents list`: Displays all available local and remote subagents.
 - `/agents reload`: Reloads the agent registry. Use this after adding or

package/dist/docs/core/subagents.md

@@ -88,11 +88,23 @@ Cell CLI comes with the following built-in subagents:
 
 ### Generalist Agent
 
-- **Name:** `generalist_agent`
-- **Purpose:** Route tasks to the appropriate specialized subagent.
-- **When to use:** Implicitly used by the main agent for routing. Not directly
-  invoked by the user.
-- **Configuration:** Enabled by default. No specific configuration options.
+- **Name:** `generalist`
+- **Purpose:** A general, all-purpose subagent that uses the inherited tool
+  access and configurations from the main agent. Useful for executing broad,
+  resource-heavy subtasks in an isolated conversation, optimizing your main
+  agent's context by returning only the final result of that given task.
+- **When to use:** Use this agent when a task requires many steps, handles large
+  volumes of information, or requires the same full capabilities as the main
+  agent. It is ideal for:
+  - **Multi-file modifications:** Applying refactors or fixing errors across
+    several files at once.
+  - **High-volume execution:** Running commands or tests that produce extensive
+    terminal output.
+  - **Action-oriented research:** Investigations where the agent needs to both
+    search code and run commands or make edits to find a solution. By delegating
+    these tasks, you prevent your main conversation from becoming cluttered or
+    slow. You can invoke it explicitly using `@generalist`.
+- **Configuration:** Enabled by default.
 
 ### Browser Agent (experimental)
 
@@ -359,7 +371,7 @@ it yourself; just report it.
 | `kind`         | string | No       | `local` (default) or `remote`.                                                                                                                                                                                |
 | `tools`        | array  | No       | List of tool names this agent can use. Supports wildcards: `*` (all tools), `mcp_*` (all MCP tools), `mcp_server_*` (all tools from a server). **If omitted, it inherits all tools from the parent session.** |
 | `mcpServers`   | object | No       | Configuration for inline Model Context Protocol (MCP) servers isolated to this specific agent.                                                                                                                |
-| `model`        | string | No       | Specific model to use (e.g., `gemini-3-preview`). Defaults to `inherit` (uses the main session model).                                                                                                        |
+| `model`        | string | No       | Specific model to use (for example, `gemini-3-preview`). Defaults to `inherit` (uses the main session model).                                                                                                 |
 | `temperature`  | number | No       | Model temperature (0.0 - 2.0). Defaults to `1`.                                                                                                                                                               |
 | `max_turns`    | number | No       | Maximum number of conversation turns allowed for this agent before it must return. Defaults to `30`.                                                                                                          |
 | `timeout_mins` | number | No       | Maximum execution time in minutes. Defaults to `10`.                                                                                                                                                          |
@@ -411,8 +423,8 @@ With this feature, you can:
 ### Configuring isolated tools and servers
 
 You can configure tool isolation for a subagent by updating its markdown
-frontmatter. This allows you to explicitly state which tools the subagent can
-use, rather than relying on the global registry.
+frontmatter. This lets you explicitly state which tools the subagent can use,
+rather than relying on the global registry.
 
 Add an `mcpServers` object to define inline MCP servers that are unique to the
 agent.
@@ -522,6 +534,24 @@ field.
 }
 ```
 
+#### Safety policies (TOML)
+
+You can restrict access to specific subagents using the CLI's **Policy Engine**.
+Subagents are treated as virtual tool names for policy matching purposes.
+
+To govern access to a subagent, create a `.toml` file in your policy directory
+(e.g., `~/.cell-cli/policies/`):
+
+```toml
+[[rule]]
+toolName = "codebase_investigator"
+decision = "deny"
+deny_message = "Deep codebase analysis is restricted for this session."
+```
+
+For more information on setting up fine-grained safety guardrails, see the
+[Policy Engine reference](../reference/policy-engine.md#special-syntax-for-subagents).
+
 ### Optimizing your subagent
 
 The main agent's system prompt encourages it to use an expert subagent when one

package/dist/docs/extensions/best-practices.md

@@ -117,8 +117,9 @@ for your users.
 Follow [Semantic Versioning (SemVer)](https://semver.org/) to communicate
 changes clearly.
 
-- **Major:** Breaking changes (e.g., renaming tools or changing arguments).
-- **Minor:** New features (e.g., adding new tools or commands).
+- **Major:** Breaking changes (for example, renaming tools or changing
+  arguments).
+- **Minor:** New features (for example, adding new tools or commands).
 - **Patch:** Bug fixes and performance improvements.
 
 ### Release channels
@@ -182,7 +183,7 @@ If your tools aren't working as expected:
 If a custom command isn't responding:
 
 - **Check precedence:** Remember that user and project commands take precedence
-  over extension commands. Use the prefixed name (e.g., `/extension.command`) to
-  verify the extension's version.
+  over extension commands. Use the prefixed name (for example,
+  `/extension.command`) to verify the extension's version.
 - **Help command:** Run `/help` to see a list of all available commands and
   their sources.

package/dist/docs/extensions/reference.md

@@ -88,12 +88,12 @@ gemini extensions new <path> [template]
 ```
 
 - `<path>`: The directory to create.
-- `[template]`: The template to use (e.g., `mcp-server`, `context`,
+- `[template]`: The template to use (for example, `mcp-server`, `context`,
   `custom-commands`).
 
 ### Link a local extension
 
-Create a symbolic link between your development directory and the Cell CLI
+Create a symbolic link between your development directory and Cell CLI
 extensions directory. This lets you test changes immediately without
 reinstalling.
 
@@ -244,7 +244,7 @@ agent definition files (`.md`) to an `agents/` directory in your extension root.
 
 ### <a id="policy-engine"></a>Policy Engine
 
-Extensions can contribute policy rules and safety checkers to the Cell CLI
+Extensions can contribute policy rules and safety checkers to Cell CLI
 [Policy Engine](../reference/policy-engine.md). These rules are defined in
 `.toml` files and take effect when the extension is activated.
 
@@ -324,13 +324,14 @@ defined in the `themes` array in `gemini-extension.json`.
 Custom themes provided by extensions can be selected using the `/theme` command
 or by setting the `ui.theme` property in your `settings.json` file. Note that
 when referring to a theme from an extension, the extension name is appended to
-the theme name in parentheses, e.g., `shades-of-green (my-green-extension)`.
+the theme name in parentheses, for example,
+`shades-of-green (my-green-extension)`.
 
 ### Conflict resolution
 
 Extension commands have the lowest precedence. If an extension command name
 conflicts with a user or project command, the extension command is prefixed with
-the extension name (e.g., `/gcp.deploy`) using a dot separator.
+the extension name (for example, `/gcp.deploy`) using a dot separator.
 
 ## Variables