@machina.ai/cell-cli-core 1.41.1-rc2 → 1.45.1-rc1

package/dist/docs/cli/tutorials/skills-getting-started.md

@@ -1,110 +1,158 @@
 # Get started with Agent Skills
 
-Agent Skills extend Cell CLI with specialized expertise. In this guide, you'll
-learn how to create your first skill, bundle custom scripts, and activate them
-during a session.
+Agent Skills extend Cell CLI with specialized expertise. In this tutorial,
+you'll learn how to create your first skill, bundle custom logic, and activate
+it during a session.
 
-## How to create a skill
+## Create your first skill
 
-A skill is defined by a directory containing a `SKILL.md` file. Let's create an
-**API Auditor** skill that helps you verify if local or remote endpoints are
-responding correctly.
+A skill is defined by a directory containing a `SKILL.md` file and
+subdirectories containing reference materials or scripts used by the skill.
+Let's create an **API Auditor** skill that runs a script to help you verify if
+local or remote endpoints are responding correctly.
 
-### Create the directory structure
+### 1. Create the directory structure
+
+The first step is to create the necessary folders for your skill and its
+scripts.
+
+**macOS/Linux**
+
+```bash
+mkdir -p .cell-cli/skills/api-auditor/scripts
+```
+
+**Windows (PowerShell)**
+
+```powershell
+New-Item -ItemType Directory -Force -Path ".cell-cli\skills\api-auditor\scripts"
+```
+
+### 2. Create the definition (`SKILL.md`)
+
+The `SKILL.md` file defines the skill's purpose and instructions for the agent.
+Create a file at `.cell-cli/skills/api-auditor/SKILL.md`. This tells the agent
+_when_ to use the skill and _how_ to behave.
+
+```markdown
+---
+name: api-auditor
+description:
+  Expertise in auditing and testing API endpoints. Use when the user asks to
+  "check", "test", or "audit" a URL or API.
+---
+
+# API Auditor Instructions
+
+You act as a QA engineer specialized in API reliability. When this skill is
+active, you MUST:
+
+1.  **Audit**: Use the bundled `scripts/audit.js` utility to check the status of
+    the provided URL.
+2.  **Report**: Analyze the output (status codes, latency) and explain any
+    failures in plain English.
+3.  **Secure**: Remind the user if they are testing a sensitive endpoint without
+    an `https://` protocol.
+```
+
+### 3. Add the tool logic
+
+Skills can bundle resources like scripts to perform deterministic tasks. Create
+a file at `.cell-cli/skills/api-auditor/scripts/audit.js`. This is the code the
+agent will run.
+
+```javascript
+// .cell-cli/skills/api-auditor/scripts/audit.js
+const url = process.argv[2];
+
+if (!url) {
+  console.error('Usage: node audit.js <url>');
+  process.exit(1);
+}
+
+console.log(`Auditing ${url}...`);
+fetch(url, { method: 'HEAD' })
+  .then((r) => console.log(`Result: Success (Status ${r.status})`))
+  .catch((e) => console.error(`Result: Failed (${e.message})`));
+```
+
+## Verify discovery
+
+Cell CLI automatically discovers skills in the `.cell-cli/skills` directory (as
+well as the `.agents/skills` alias).
+
+To check if Cell CLI found your new skill, use the `/skills list` command within
+an interactive session:
+
+```bash
+/skills list
+```
+
+You should see `api-auditor` in the list of available skills. If you just added
+the files, you can run `/skills reload` to refresh the list without restarting
+the session.
+
+### If your skill doesn't appear
+
+If `/skills list` doesn't show your skill, check the following:
+
+1.  **The folder must be trusted (workspace skills only).** Skills under
+    `<workspace>/.cell-cli/skills/` are only loaded when the workspace folder is
+    marked as trusted. Run `/trust` and restart the session if needed. Skills
+    under `~/.cell-cli/skills/` (user scope) are not affected by trust.
+2.  **Check the path layout.** `SKILL.md` is discovered either at the root of
+    the skills directory (`.cell-cli/skills/SKILL.md`) or one directory deep
+    (`.cell-cli/skills/<skill-name>/SKILL.md`). The recommended layout uses a
+    subdirectory per skill so you can bundle scripts and other resources
+    alongside it. Files nested more than one directory deep are not discovered.
+3.  **The filename must be exactly `SKILL.md`.** Capitalization matters on
+    case-sensitive filesystems (Linux, and macOS when configured as such):
+    `skill.md` or `Skill.md` will be ignored.
+4.  **Frontmatter must include both `name:` and `description:`, and must be the
+    first thing in the file.** A `SKILL.md` is silently skipped if either field
+    is missing, if the delimiters (`---` on their own lines) are absent, or if
+    any text (an H1 title, a comment, even a blank line) appears before the
+    opening `---`.
+5.  **The skill name comes from the `name:` field, not the directory name.** If
+    your frontmatter says `name: foo`, the skill appears as `foo` in
+    `/skills list` regardless of what its parent directory is called. The
+    characters `: \ / < > * ? " |` in the name are replaced with `-`.
 
-1.  Run the following command to create the folders:
-
-    **macOS/Linux**
-
-    ```bash
-    mkdir -p .cell-cli/skills/api-auditor/scripts
-    ```
-
-    **Windows (PowerShell)**
-
-    ```powershell
-    New-Item -ItemType Directory -Force -Path ".cell-cli\skills\api-auditor\scripts"
-    ```
-
-### Create the definition
-
-1.  Create a file at `.cell-cli/skills/api-auditor/SKILL.md`. This tells the
-    agent _when_ to use the skill and _how_ to behave.
-
-    ```markdown
-    ---
-    name: api-auditor
-    description:
-      Expertise in auditing and testing API endpoints. Use when the user asks to
-      "check", "test", or "audit" a URL or API.
-    ---
-
-    # API Auditor Instructions
-
-    You act as a QA engineer specialized in API reliability. When this skill is
-    active, you MUST:
-
-    1.  **Audit**: Use the bundled `scripts/audit.js` utility to check the
-        status of the provided URL.
-    2.  **Report**: Analyze the output (status codes, latency) and explain any
-        failures in plain English.
-    3.  **Secure**: Remind the user if they are testing a sensitive endpoint
-        without an `https://` protocol.
-    ```
-
-### Add the tool logic
-
-Skills can bundle resources like scripts.
-
-1.  Create a file at `.cell-cli/skills/api-auditor/scripts/audit.js`. This is
-    the code the agent will run.
-
-    ```javascript
-    // .cell-cli/skills/api-auditor/scripts/audit.js
-    const url = process.argv[2];
-
-    if (!url) {
-      console.error('Usage: node audit.js <url>');
-      process.exit(1);
-    }
-
-    console.log(`Auditing ${url}...`);
-    fetch(url, { method: 'HEAD' })
-      .then((r) => console.log(`Result: Success (Status ${r.status})`))
-      .catch((e) => console.error(`Result: Failed (${e.message})`));
-    ```
-
-## How to verify discovery
-
-Cell CLI automatically discovers skills in the `.cell-cli/skills` directory. You
-can also use `.agents/skills` as a more generic alternative. Check that it found
-your new skill.
+## How to use the skill
 
-**Command:** `/skills list`
+Now that the skill is discovered, you can trigger its activation by asking a
+relevant question.
 
-You should see `api-auditor` in the list of available skills.
+1.  **Trigger**: Start a new session and ask: "Can you audit https://google.com"
+2.  **Activation**: Gemini identifies that the request matches the `api-auditor`
+    description and calls the `activate_skill` tool.
+3.  **Consent**: You will see a confirmation prompt. Type **y** to approve.
+4.  **Execution**: Once activated, Gemini uses the `run_shell_command` tool to
+    execute your bundled script:
+    `node .cell-cli/skills/api-auditor/scripts/audit.js https://google.com`
 
-## How to use the skill
+## Pro tip: Use the skill-creator
 
-Now, try it out. Start a new session and ask a question that triggers the
-skill's description.
+If you don't want to create the files manually, you can use the built-in
+`skill-creator` skill. Simply ask Gemini:
 
-**User:** "Can you audit http://geminicli.com"
+> "Create a new skill called 'api-auditor' that tests if URLs are responding."
 
-Gemini recognizes the request matches the `api-auditor` description and asks for
-permission to activate it.
+The `skill-creator` will handle the directory structure and boilerplate for you.
 
-**Model:** (After calling `activate_skill`) "I've activated the **api-auditor**
-skill. I'll run the audit script now..."
+## Manage skills
 
-Gemini then uses the `run_shell_command` tool to execute your bundled Node
-script:
+You can also manage skills using the `gemini skills` command from your terminal:
 
-`node .cell-cli/skills/api-auditor/scripts/audit.js http://geminili.com`
+- **Install**: `gemini skills install <url-or-path>`
+- **Link**: `gemini skills link <path>` (useful for local development)
+- **Uninstall**: `gemini skills uninstall <name>`
 
 ## Next steps
 
-- Explore the
-  [Agent Skills Authoring Guide](../../cli/skills.md#creating-a-skill) to learn
-  about more advanced features.
-- Learn how to share skills via [Extensions](../../extensions/index.md).
+- [Creating Agent Skills](../creating-skills.md): Detailed guide on advanced
+  skill features and metadata.
+- [Using Agent Skills](../using-agent-skills.md): More ways to discover and
+  manage your skill library.
+- [Skill best practices](../skills-best-practices.md): Learn how to design
+  reliable and effective expertise.

package/dist/docs/cli/using-agent-skills.md

@@ -0,0 +1,90 @@
+# Managing Agent Skills
+
+Agent Skills provide Cell CLI with specialized expertise on demand. This guide
+covers advanced management techniques, including using slash commands, terminal
+utilities, and understanding discovery tiers.
+
+## Discovery tiers
+
+Cell CLI discovers skills from several locations, following a specific order of
+precedence (lowest to highest):
+
+1.  **Built-in Skills**: Included with Cell CLI and always available.
+2.  **Extension Skills**: Bundled within [extensions](../extensions/index.md).
+3.  **User Skills**: Located in `~/.cell-cli/skills/` or the `~/.agents/skills/`
+    alias. These are available across all your projects.
+4.  **Workspace Skills**: Located in `.cell-cli/skills/` or the
+    `.agents/skills/` alias within your current directory. These are
+    project-specific.
+
+> **Tip:** If multiple skills share the same name, the version from the
+> higher-precedence location is used.
+
+## In-session management
+
+Use the `/skills` slash command during an interactive session to manage your
+available expertise.
+
+- **List skills**: `/skills list` (shows discovered skills).
+  - Use `/skills list all` to include internal built-in skills.
+  - Use `/skills list nodesc` to hide descriptions.
+- **Reload skills**: `/skills reload` (or `/skills refresh`) to scan for new or
+  modified skills without restarting the CLI.
+- **Toggle status**:
+  - `/skills disable <name>`: Prevents a skill from being triggered.
+  - `/skills enable <name>`: Re-enables a disabled skill.
+- **Link local skills**: `/skills link <path> [--scope user|workspace]` to
+  immediately use a skill you are developing.
+
+## Terminal utilities
+
+The `gemini skills` command provides management utilities directly from your
+system shell.
+
+### Install a skill
+
+To install a skill from a remote repository or a local `.skill` package:
+
+```bash
+gemini skills install https://github.com/user/my-awesome-skill
+```
+
+By default, this installs to your **user profile**. Use `--scope workspace` to
+install it only for the current project.
+
+### Link for development
+
+If you are developing a skill, use the `link` command to create a reference to
+your local directory:
+
+```bash
+gemini skills link ./path/to/my-skill
+```
+
+### Uninstall a skill
+
+To completely remove an installed or linked skill:
+
+```bash
+gemini skills uninstall <name>
+```
+
+## Security and consent
+
+Agent Skills can execute scripts and access your files. To protect your
+environment:
+
+1.  **Installation consent**: When installing from a remote URL, you will be
+    asked to confirm the source.
+2.  **Activation consent**: Every time a skill is triggered during a session,
+    the agent must ask for permission to activate it and gain access to its
+    resources.
+
+## Next steps
+
+- [Get started with Agent Skills](./tutorials/skills-getting-started.md): A
+  walkthrough for creating your first skill.
+- [Creating Agent Skills](./creating-skills.md): Detailed guide on bundling
+  scripts and assets.
+- [Skill best practices](./skills-best-practices.md): Strategies for building
+  reliable expertise.

package/dist/docs/core/gemma-setup.md

@@ -0,0 +1,83 @@
+# `gemini gemma` — Automated Local Model Routing Setup
+
+Local model routing uses a local Gemma 3 1B model running on your machine to
+classify and route user requests. It routes simple requests (like file reads) to
+Gemini Flash and complex requests (like architecture discussions) to Gemini Pro.
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> This is an experimental feature currently under active development.
+
+## What is this?
+
+This feature saves cloud API costs by using local inference for task
+classification instead of a cloud-based classifier. It adds a few milliseconds
+of local latency but can significantly reduce the overall token usage for hosted
+models.
+
+## Quick start
+
+```bash
+# One command does everything: downloads runtime, pulls model, configures settings, starts server
+gemini gemma setup
+```
+
+You'll be prompted to accept the Gemma Terms of Use. The model is ~1 GB.
+
+After setup, **just use the CLI normally** — routing happens automatically on
+every request.
+
+## Commands
+
+| Command               | What it does                                                   |
+| --------------------- | -------------------------------------------------------------- |
+| `gemini gemma setup`  | Full install (binary + model + settings + server start)        |
+| `gemini gemma status` | Health check — shows what's installed and running              |
+| `gemini gemma start`  | Start the LiteRT server (auto-starts on CLI launch by default) |
+| `gemini gemma stop`   | Stop the LiteRT server                                         |
+| `gemini gemma logs`   | Tail the server logs to see routing requests live              |
+| `/gemma`              | In-session status check (type it inside the CLI)               |
+
+## Verifying it works
+
+1. Run `gemini gemma status` — all checks should show green
+2. Open two terminals:
+   - Terminal 1: `gemini gemma logs` (watch for incoming requests)
+   - Terminal 2: use the CLI normally
+3. You should see classification requests appear in the logs as you interact
+   with the CLI
+4. The `/gemma` slash command inside a session shows a quick status panel
+
+## Setup flags
+
+```bash
+gemini gemma setup --port 8080      # custom port
+gemini gemma setup --no-start       # don't start server after install
+gemini gemma setup --force           # re-download everything
+gemini gemma setup --skip-model     # binary only, skip the 1GB model download
+```
+
+## How it works under the hood
+
+- Local Gemma classifies each request as "simple" or "complex" (~100ms)
+- Simple → Flash, Complex → Pro
+- If the local server is down, the CLI silently falls back to the cloud
+  classifier — no errors, no disruption
+
+## Disabling
+
+Set `enabled: false` in settings or just run `gemini gemma stop` to turn off the
+server:
+
+```json
+{ "experimental": { "gemmaModelRouter": { "enabled": false } } }
+```
+
+## Advanced setup
+
+If you are in an environment where the `gemini gemma setup` command cannot
+automatically download binaries (for example, behind a strict corporate
+firewall), you can perform the setup manually.
+
+For more information, see the
+[Manual Local Model Routing Setup guide](./local-model-routing.md).

package/dist/docs/core/index.md

@@ -15,8 +15,9 @@ requests sent from `packages/cli`. For a general overview of Cell CLI, see the
   modular GEMINI.md import feature using @file.md syntax.
 - **[Policy Engine](../reference/policy-engine.md):** Use the Policy Engine for
   fine-grained control over tool execution.
-- **[Local Model Routing (experimental)](./local-model-routing.md):** Learn how
-  to enable use of a local Gemma model for model routing decisions.
+- **[Local Model Routing (experimental)](./gemma-setup.md):** Learn how to
+  enable use of a local Gemma model for model routing decisions using the
+  automated setup command.
 
 ## Role of the core
 

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

@@ -1,22 +1,29 @@
-# Local Model Routing (experimental)
+# Manual Local Model Routing Setup (experimental)
 
 Cell CLI supports using a local model for
 [routing decisions](../cli/model-routing.md). When configured, Cell CLI will use
 a locally-running **Gemma** model to make routing decisions (instead of sending
 routing decisions to a hosted model).
 
+<!-- prettier-ignore -->
+> [!NOTE]
+> This is an experimental feature currently under active development.
+
+<!-- prettier-ignore -->
+> [!IMPORTANT]
+> **Recommended:** We now provide a fully automated setup command. We recommend
+> using the [`gemini gemma` Setup Guide](./gemma-setup.md) instead of following
+> these manual steps.
+
 This feature can help reduce costs associated with hosted model usage while
 offering similar routing decision latency and quality.
 
-> **Note: Local model routing is currently an experimental feature.**
-
-## Setup
+## Manual Setup
 
 Using a Gemma model for routing decisions requires that an implementation of a
 Gemma model be running locally on your machine, served behind an HTTP endpoint
-and accessed via the Gemini API.
-
-To serve the Gemma model, follow these steps:
+and accessed via the Gemini API. If you cannot use the `gemini gemma setup`
+command, follow these manual steps:
 
 ### Download the LiteRT-LM runtime
 

package/dist/docs/extensions/reference.md

@@ -210,6 +210,22 @@ To update an extension's settings:
 gemini extensions config <name> [setting] [--scope <scope>]
 ```
 
+#### Environment variable sanitization
+
+For security reasons, sensitive environment variables are filtered out and not
+passed to extensions or MCP servers by default.
+
+Extensions **will not** inherit the user's full shell environment variables.
+They will only have access to:
+
+1. Standard safe variables (e.g., `HOME`, `PATH`, `TMPDIR`).
+2. Variables explicitly declared and requested in the `gemini-extension.json`
+   manifest via the `settings` array (using the `envVar` property).
+
+If your extension requires specific environment variables (like an API key,
+custom host, or config path), you **must** declare them in the `settings` array
+so the CLI can allowlist them for use within the extension.
+
 ### Custom commands
 
 Provide [custom commands](../cli/custom-commands.md) by placing TOML files in a

package/dist/docs/extensions/releasing.md

@@ -1,7 +1,8 @@
 # Release extensions
 
 Release Cell CLI extensions to your users through a Git repository or GitHub
-Releases.
+Releases. This guide explains how to share your work, list it in the gallery,
+and manage updates.
 
 Git repository releases are the simplest approach and offer the most flexibility
 for managing development branches. GitHub Releases are more efficient for
@@ -153,29 +154,62 @@ jobs:
             release/win32.arm64.my-tool.zip
 ```
 
-## Migrating an Extension Repository
+## Migrate an extension repository
 
-If you need to move your extension to a new repository (for example, from a
-personal account to an organization) or rename it, you can use the `migratedTo`
-property in your `gemini-extension.json` file to seamlessly transition your
+If you move your extension to a new repository or rename it, use the
+`migratedTo` property in `gemini-extension.json` to seamlessly transition your
 users.
 
-1. **Create the new repository**: Setup your extension in its new location.
-2. **Update the old repository**: In your original repository, update the
-   `gemini-extension.json` file to include the `migratedTo` property, pointing
-   to the new repository URL, and bump the version number. You can optionally
-   change the `name` of your extension at this time in the new repository.
-   ```json
-   {
-     "name": "my-extension",
-     "version": "1.1.0",
-     "migratedTo": "https://github.com/new-owner/new-extension-repo"
-   }
-   ```
-3. **Release the update**: Publish this new version in your old repository.
-
-When users check for updates, Cell CLI will detect the `migratedTo` field,
-verify that the new repository contains a valid extension update, and
-automatically update their local installation to track the new source and name
-moving forward. All extension settings will automatically migrate to the new
-installation.
+1.  **Create the new repository:** Set up your extension in its new location.
+2.  **Update the old repository:** In your original repository, update the
+    `gemini-extension.json` file to include the `migratedTo` property pointing
+    to the new repository URL, and increment the version number.
+    ```json
+    {
+      "name": "my-extension",
+      "version": "1.1.0",
+      "migratedTo": "https://github.com/new-owner/new-extension-repo"
+    }
+    ```
+3.  **Release the update:** Publish this new version in your old repository.
+
+When users check for updates, Cell CLI detects the `migratedTo` field, verifies
+the new repository, and automatically updates their local installation to track
+the new source. All settings migrate automatically.
+
+## How updates work
+
+Cell CLI automatically checks for extension updates based on the installation
+method. Understanding these mechanisms helps you ensure your users always have
+the latest version.
+
+### Sync manifest and tags
+
+For GitHub releases, always ensure the `version` in `gemini-extension.json`
+matches your GitHub release tag. While the CLI uses tags for update detection,
+it displays the manifest version in the UI. Keeping them in sync prevents
+confusion.
+
+### Update mechanisms
+
+<details>
+<summary>Technical update details</summary>
+
+The CLI uses different strategies depending on the installation type:
+
+- **GitHub releases:** The CLI queries the GitHub API for the latest release
+  tag. It ignores the `version` field in the manifest for detection.
+- **Git clones:** The CLI runs `git ls-remote` to compare the latest remote
+  commit hash with your local `HEAD`.
+- **Local extensions:** The CLI compares the `version` field in the source
+  directory's manifest with the installed version.
+
+To verify an extension's installation type, inspect the `type` field in the
+metadata file at `~/.cell-cli/extensions/<name>/.gemini-extension-install.json`.
+
+</details>
+
+<!-- prettier-ignore -->
+> [!IMPORTANT]
+> The `migratedTo` flow requires at least one release on the new repository for
+> the CLI to recognize it as a valid update source.

package/dist/docs/extensions/writing-extensions.md

@@ -159,6 +159,13 @@ Key". The value will be stored securely in the system keychain (because
 `sensitive` is true) and injected into the MCP server's process as the
 `MY_SERVICE_API_KEY` environment variable.
 
+> **Important (Environment Variable Sanitization):** For security reasons,
+> sensitive environment variables are filtered out and not passed to extensions
+> or MCP servers by default. Extensions will _only_ have access to environment
+> variables that are explicitly declared in the `settings` array using the
+> `envVar` property, plus a few standard safe variables. Do not expect host
+> environment variables to be available otherwise.
+
 ## Step 4: Link your extension
 
 Link your extension to your Cell CLI installation for local development.

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

@@ -111,8 +111,8 @@ You can also run Cell CLI using one of the following advanced methods:
     directly. This is useful for environments where you only have Docker and want
     to run the CLI.
     ```bash
-    # Run the published sandbox image
-    docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.1
+    # Run the published sandbox image for a specified CLI version
+    docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.42.0-nightly.20260428.g59b2dea0e
     ```
   - **Using the `--sandbox` flag:** If you have Cell CLI installed locally
     (using the standard installation described above), you can instruct it to run