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

package/dist/docs/core/subagents.md

@@ -1,23 +1,10 @@
-# Subagents (experimental)
+# Subagents
 
 Subagents are specialized agents that operate within your main Cell CLI session.
 They are designed to handle specific, complex tasks—like deep codebase analysis,
 documentation lookup, or domain-specific reasoning—without cluttering the main
 agent's context or toolset.
 
-<!-- prettier-ignore -->
-> [!NOTE]
-> Subagents are currently an experimental feature.
-> 
-To use custom subagents, you must ensure they are enabled in your
-`settings.json` (enabled by default):
-
-```json
-{
-  "experimental": { "enableAgents": true }
-}
-```
-
 ## What are subagents?
 
 Subagents are "specialists" that the main Gemini agent can hire for a specific
@@ -125,10 +112,12 @@ Cell CLI comes with the following built-in subagents:
 
 The browser agent requires:
 
-- **Chrome** version 144 or later (any recent stable release will work).
-- **Node.js** with `npx` available (used to launch the
-  [`chrome-devtools-mcp`](https://www.npmjs.com/package/chrome-devtools-mcp)
-  server).
+- **Chrome** version 144 or later (any recent stable release works).
+
+The underlying
+[`chrome-devtools-mcp`](https://www.npmjs.com/package/chrome-devtools-mcp)
+server is bundled with Cell CLI and launched automatically — no separate
+installation is needed.
 
 #### Enabling the browser agent
 
@@ -174,26 +163,58 @@ The available modes are:
 | `isolated`   | Launches Chrome with a temporary profile that is deleted after each session. Use this for clean-state automation.                                                                           |
 | `existing`   | Attaches to an already-running Chrome instance. You must enable remote debugging first by navigating to `chrome://inspect/#remote-debugging` in Chrome. No new browser process is launched. |
 
+#### First-run consent
+
+The first time the browser agent is invoked, Cell CLI displays a consent dialog.
+You must accept before the browser session starts. This dialog only appears
+once.
+
 #### Configuration reference
 
 All browser-specific settings go under `agents.browser` in your `settings.json`.
-
-| Setting       | Type      | Default        | Description                                                                                     |
-| :------------ | :-------- | :------------- | :---------------------------------------------------------------------------------------------- |
-| `sessionMode` | `string`  | `"persistent"` | How Chrome is managed: `"persistent"`, `"isolated"`, or `"existing"`.                           |
-| `headless`    | `boolean` | `false`        | Run Chrome in headless mode (no visible window).                                                |
-| `profilePath` | `string`  | —              | Custom path to a browser profile directory.                                                     |
-| `visualModel` | `string`  | —              | Model override for the visual agent (for example, `"gemini-2.5-computer-use-preview-10-2025"`). |
+For full details, see the
+[`agents.browser` configuration reference](../reference/configuration.md#agents).
+
+| Setting                   | Type       | Default        | Description                                                                     |
+| :------------------------ | :--------- | :------------- | :------------------------------------------------------------------------------ |
+| `sessionMode`             | `string`   | `"persistent"` | How Chrome is managed: `"persistent"`, `"isolated"`, or `"existing"`.           |
+| `headless`                | `boolean`  | `false`        | Run Chrome in headless mode (no visible window).                                |
+| `profilePath`             | `string`   | —              | Custom path to a browser profile directory.                                     |
+| `visualModel`             | `string`   | —              | Model override for the visual agent.                                            |
+| `allowedDomains`          | `string[]` | —              | Restrict navigation to specific domains (for example, `["github.com"]`).        |
+| `disableUserInput`        | `boolean`  | `true`         | Disable user input on the browser window during automation (non-headless only). |
+| `maxActionsPerTask`       | `number`   | `100`          | Maximum tool calls per task. The agent is terminated when the limit is reached. |
+| `confirmSensitiveActions` | `boolean`  | `false`        | Require manual confirmation for `upload_file` and `evaluate_script`.            |
+| `blockFileUploads`        | `boolean`  | `false`        | Hard-block all file upload requests from the agent.                             |
+
+#### Automation overlay and input blocking
+
+In non-headless mode, the browser agent injects a visual overlay into the
+browser window to indicate that automation is in progress. By default, user
+input (keyboard and mouse) is also blocked to prevent accidental interference.
+You can disable this by setting `disableUserInput` to `false`.
 
 #### Security
 
-The browser agent enforces the following security restrictions:
-
-- **Blocked URL patterns:** `file://`, `javascript:`, `data:text/html`,
-  `chrome://extensions`, and `chrome://settings/passwords` are always blocked.
-- **Sensitive action confirmation:** Actions like form filling, file uploads,
-  and form submissions require user confirmation through the standard policy
-  engine.
+The browser agent enforces several layers of security:
+
+- **Domain restrictions:** When `allowedDomains` is set, the agent can only
+  navigate to the listed domains (and their subdomains when using `*.` prefix).
+  Attempting to visit a disallowed domain throws a fatal error that immediately
+  terminates the agent. The agent also attempts to detect and block the use of
+  allowed domains as proxies (e.g., via query parameters or fragments) to access
+  restricted content.
+- **Blocked URL patterns:** The underlying MCP server blocks dangerous URL
+  schemes including `file://`, `javascript:`, `data:text/html`,
+  `chrome://extensions`, and `chrome://settings/passwords`.
+- **Sensitive action confirmation:** Form filling (`fill`, `fill_form`) always
+  requires user confirmation through the policy engine, regardless of approval
+  mode. When `confirmSensitiveActions` is `true`, `upload_file` and
+  `evaluate_script` also require confirmation.
+- **File upload blocking:** Set `blockFileUploads` to `true` to hard-block all
+  file upload requests, preventing the agent from uploading any files.
+- **Action rate limiting:** The `maxActionsPerTask` setting (default: 100)
+  limits the total number of tool calls per task to prevent runaway execution.
 
 #### Visual agent
 
@@ -227,19 +248,65 @@ the `click_at` tool for precise, coordinate-based interactions.
 > The visual agent requires API key or Vertex AI authentication. It is
 > not available when using "Sign in with Google".
 
+#### Sandbox support
+
+The browser agent adjusts its behavior automatically when running inside a
+sandbox.
+
+##### macOS seatbelt (`sandbox-exec`)
+
+When the CLI runs under the macOS seatbelt sandbox, `persistent` and `isolated`
+session modes are forced to `isolated` with `headless` enabled. This avoids
+permission errors caused by seatbelt file-system restrictions on persistent
+browser profiles. If `sessionMode` is set to `existing`, no override is applied.
+
+##### Container sandboxes (Docker / Podman)
+
+Chrome is not available inside the container, so the browser agent is
+**disabled** unless `sessionMode` is set to `"existing"`. When enabled with
+`existing` mode, the agent automatically connects to Chrome on the host via the
+resolved IP of `host.docker.internal:9222` instead of using local pipe
+discovery. Port `9222` is currently hardcoded and cannot be customized.
+
+To use the browser agent in a Docker sandbox:
+
+1. Start Chrome on the host with remote debugging enabled:
+
+   ```bash
+   # Option A: Launch Chrome from the command line
+   google-chrome --remote-debugging-port=9222
+
+   # Option B: Enable in Chrome settings
+   # Navigate to chrome://inspect/#remote-debugging and enable
+   ```
+
+2. Configure `sessionMode` and allowed domains in your project's
+   `.cell-cli/settings.json`:
+
+   ```json
+   {
+     "agents": {
+       "overrides": {
+         "browser_agent": { "enabled": true }
+       },
+       "browser": {
+         "sessionMode": "existing",
+         "allowedDomains": ["example.com"]
+       }
+     }
+   }
+   ```
+
+3. Launch the CLI with port forwarding:
+
+   ```bash
+   GEMINI_SANDBOX=docker SANDBOX_PORTS=9222 gemini
+   ```
+
 ## Creating custom subagents
 
 You can create your own subagents to automate specific workflows or enforce
-specific personas. To use custom subagents, you must enable them in your
-`settings.json`:
-
-```json
-{
-  "experimental": {
-    "enableAgents": true
-  }
-}
-```
+specific personas.
 
 ### Agent definition files
 
@@ -291,6 +358,7 @@ it yourself; just report it.
 | `description`  | string | Yes      | Short description of what the agent does. This is visible to the main agent to help it decide when to call this subagent.                                                                                     |
 | `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).                                                                                                        |
 | `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`.                                                                                                          |
@@ -318,6 +386,78 @@ Each subagent runs in its own isolated context loop. This means:
   subagents **cannot** call other subagents. If a subagent is granted the `*`
   tool wildcard, it will still be unable to see or invoke other agents.
 
+## Subagent tool isolation
+
+Subagent tool isolation moves Cell CLI away from a single global tool registry.
+By providing isolated execution environments, you can ensure that subagents only
+interact with the parts of the system they are designed for. This prevents
+unintended side effects, improves reliability by avoiding state contamination,
+and enables fine-grained permission control.
+
+With this feature, you can:
+
+- **Specify tool access:** Define exactly which tools an agent can access using
+  a `tools` list in the agent definition.
+- **Define inline MCP servers:** Configure Model Context Protocol (MCP) servers
+  (which provide a standardized way to connect AI models to external tools and
+  data sources) directly in the subagent's markdown frontmatter, isolating them
+  to that specific agent.
+- **Maintain state isolation:** Ensure that subagents only interact with their
+  own set of tools and servers, preventing side effects and state contamination.
+- **Apply subagent-specific policies:** Enforce granular rules in your
+  [Policy Engine](../reference/policy-engine.md) TOML configuration based on the
+  executing subagent's name.
+
+### 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.
+
+Add an `mcpServers` object to define inline MCP servers that are unique to the
+agent.
+
+**Example:**
+
+```yaml
+---
+name: my-isolated-agent
+tools:
+  - grep_search
+  - read_file
+mcpServers:
+  my-custom-server:
+    command: 'node'
+    args: ['path/to/server.js']
+---
+```
+
+### Subagent-specific policies
+
+You can enforce fine-grained control over subagents using the
+[Policy Engine's](../reference/policy-engine.md) TOML configuration. This allows
+you to grant or restrict permissions specifically for an agent, without
+affecting the rest of your CLI session.
+
+To restrict a policy rule to a specific subagent, add the `subagent` property to
+the `[[rules]]` block in your `policy.toml` file.
+
+**Example:**
+
+```toml
+[[rules]]
+name = "Allow pr-creator to push code"
+subagent = "pr-creator"
+description = "Permit pr-creator to push branches automatically."
+action = "allow"
+toolName = "run_shell_command"
+commandPrefix = "git push"
+```
+
+In this configuration, the policy rule only triggers if the executing subagent's
+name matches `pr-creator`. Rules without the `subagent` property apply
+universally to all agents.
+
 ## Managing subagents
 
 You can manage subagents interactively using the `/agents` command or
@@ -407,15 +547,11 @@ If you need to further tune your subagent, you can do so by selecting the model
 to optimize for with `/model` and then asking the model why it does not think
 that your subagent was called with a specific prompt and the given description.
 
-## Remote subagents (Agent2Agent) (experimental)
+## Remote subagents (Agent2Agent)
 
 Cell CLI can also delegate tasks to remote subagents using the Agent-to-Agent
 (A2A) protocol.
 
-<!-- prettier-ignore -->
-> [!NOTE]
-> Remote subagents are currently an experimental feature.
-
 See the [Remote Subagents documentation](remote-agents) for detailed
 configuration, authentication, and usage instructions.
 
@@ -424,3 +560,14 @@ configuration, authentication, and usage instructions.
 Extensions can bundle and distribute subagents. See the
 [Extensions documentation](../extensions/index.md#subagents) for details on how
 to package agents within an extension.
+
+## Disabling subagents
+
+Subagents are enabled by default. To disable them, set `enableAgents` to `false`
+in your `settings.json`:
+
+```json
+{
+  "experimental": { "enableAgents": false }
+}
+```

package/dist/docs/get-started/authentication.md

@@ -398,8 +398,8 @@ on this page.
 
 ## Running in headless mode <a id="headless"></a>
 
-[Headless mode](../cli/headless) will use your existing authentication method,
-if an existing authentication credential is cached.
+[Headless mode](../cli/headless.md) will use your existing authentication
+method, if an existing authentication credential is cached.
 
 If you have not already signed in with an authentication credential, you must
 configure authentication using environment variables:

package/dist/docs/get-started/gemini-3.md

@@ -1,6 +1,6 @@
 # Gemini 3 Pro and Gemini 3 Flash on Cell CLI
 
-Gemini 3 Pro and Gemini 3 Flash are available on Cell CLI for all users!
+Learn about how you can use Gemini 3 Pro and Gemini 3 Flash on Cell CLI.
 
 <!-- prettier-ignore -->
 > [!NOTE]

package/dist/docs/get-started/index.md

@@ -62,7 +62,133 @@ Once installed and authenticated, you can start using Cell CLI by issuing
 commands and prompts in your terminal. Ask it to generate code, explain files,
 and more.
 
-To explore the power of Cell CLI, see [Cell CLI examples](./examples.md).
+<!-- prettier-ignore -->
+> [!NOTE]
+> These examples demonstrate potential capabilities. Your actual
+> results can vary based on the model used and your project environment.
+
+### Rename your photographs based on content
+
+You can use Cell CLI to automate file management tasks that require visual
+analysis. In this example, Cell CLI renames images based on their actual subject
+matter.
+
+Scenario: You have a folder containing the following files:
+
+```bash
+photos/photo1.png
+photos/photo2.png
+photos/photo3.png
+```
+
+Give Gemini the following prompt:
+
+```cli
+Rename the photos in my "photos" directory based on their contents.
+```
+
+Result: Gemini asks for permission to rename your files.
+
+Select **Allow once** and your files are renamed:
+
+```bash
+photos/yellow_flowers.png
+photos/antique_dresser.png
+photos/green_android_robot.png
+```
+
+### Explain a repository by reading its code
+
+Cell CLI is effective for rapid codebase exploration. The following example
+shows how to ask Cell CLI to fetch, analyze, and summarize a remote project.
+
+Scenario: You want to understand how a popular open-source utility works by
+inspecting its code, not just its README.
+
+Give Cell CLI the following prompt:
+
+```cli
+Clone the 'chalk' repository from https://github.com/chalk/chalk, read its key source files, and explain how it works.
+```
+
+Result: Gemini performs a sequence of actions to answer your request.
+
+1.  First, it asks for permission to run `git clone` to download the repository.
+2.  Next, it finds the important source files and asks for permission to read
+    them.
+3.  Finally, after analyzing the code, it provides a summary.
+
+Cell CLI returns an explanation based on the actual source code:
+
+```markdown
+The `chalk` library is a popular npm package for styling terminal output with
+colors. After analyzing the source code, here's how it works:
+
+- **Core functionality:** The main file sets up a chainable API. Each color or
+  modifier (like `bold` or `italic`) is a getter that appends the corresponding
+  ANSI escape code to an internal stack.
+
+- **Chainable API:** When you call `chalk.red.bold('Hello')`, you are accessing
+  getters. The `red` getter adds the red color code, and the `bold` getter adds
+  the bold code.
+
+- **Output generation:** When the chain is treated as a string (e.g., in
+  `console.log`), a final `toString()` method is called. This method joins all
+  the stored ANSI codes, wraps them around the input string ('Hello'), and adds
+  a reset code at the end. This produces the final, styled string that the
+  terminal can render.
+```
+
+### Combine two spreadsheets into one spreadsheet
+
+Cell CLI can process and transform data across multiple files. Use this
+capability to merge reports or reformat data sets without manual copying.
+
+Scenario: You have two .csv files: `Revenue - 2023.csv` and
+`Revenue - 2024.csv`. Each file contains monthly revenue figures.
+
+Give Cell CLI the following prompt:
+
+```cli
+Combine the two .csv files into a single .csv file, with each year a different column.
+```
+
+Result: Cell CLI reads each file and then asks for permission to write a new
+file. Provide your permission and Cell CLI provides the combined data:
+
+```csv
+Month,2023,2024
+January,0,1000
+February,0,1200
+March,0,2400
+April,900,500
+May,1000,800
+June,1000,900
+July,1200,1000
+August,1800,400
+September,2000,2000
+October,2400,3400
+November,3400,1800
+December,2100,9000
+```
+
+### Run unit tests
+
+Cell CLI can generate boilerplate code and tests based on your existing
+implementation. This example demonstrates how to request code coverage for a
+JavaScript component.
+
+Scenario: You've written a simple login page. You wish to write unit tests to
+ensure that your login page has code coverage.
+
+Give Cell CLI the following prompt:
+
+```cli
+Write unit tests for Login.js.
+```
+
+Result: Cell CLI asks for permission to write a new file and creates a test for
+your login page.
 
 ## Check usage and quota
 

package/dist/docs/get-started/installation.md

@@ -122,6 +122,13 @@ code.
   # From the root of the repository
   npm run start
   ```
+- **Production mode (React optimizations):** This method runs the CLI with React
+  production mode enabled, which is useful for testing performance without
+  development overhead.
+  ```bash
+  # From the root of the repository
+  npm run start:prod
+  ```
 - **Production-like mode (linked package):** This method simulates a global
   installation by linking your local package. It's useful for testing a local
   build in a production workflow.

package/dist/docs/hooks/index.md

@@ -22,11 +22,11 @@ With hooks, you can:
 
 ### Getting started
 
-- **[Writing hooks guide](../hooks/writing-hooks)**: A tutorial on creating your
-  first hook with comprehensive examples.
-- **[Best practices](../hooks/best-practices)**: Guidelines on security,
+- **[Writing hooks guide](../hooks/writing-hooks.md)**: A tutorial on creating
+  your first hook with comprehensive examples.
+- **[Best practices](../hooks/best-practices.md)**: Guidelines on security,
   performance, and debugging.
-- **[Hooks reference](../hooks/reference)**: The definitive technical
+- **[Hooks reference](../hooks/reference.md)**: The definitive technical
   specification of I/O schemas and exit codes.
 
 ## Core concepts
@@ -154,8 +154,8 @@ Cell CLI **fingerprints** project hooks. If a hook's name or command changes
 (e.g., via `git pull`), it is treated as a **new, untrusted hook** and you will
 be warned before it executes.
 
-See [Security Considerations](../hooks/best-practices#using-hooks-securely) for
-a detailed threat model.
+See [Security Considerations](../hooks/best-practices.md#using-hooks-securely)
+for a detailed threat model.
 
 ## Managing hooks