@machina.ai/cell-cli-core 1.22.5-rc1 → 1.25.0-rc2

package/dist/docs/cli/settings.md

@@ -0,0 +1,148 @@
+# Cell CLI settings (`/settings` command)
+
+Control your Cell CLI experience with the `/settings` command. The `/settings`
+command opens a dialog to view and edit all your Cell CLI settings, including
+your UI experience, keybindings, and accessibility features.
+
+Your Cell CLI settings are stored in a `settings.json` file. In addition to
+using the `/settings` command, you can also edit them in one of the following
+locations:
+
+- **User settings**: `~/.cell-cli/settings.json`
+- **Workspace settings**: `your-project/.cell-cli/settings.json`
+
+Note: Workspace settings override user settings.
+
+## Settings reference
+
+Here is a list of all the available settings, grouped by category and ordered as
+they appear in the UI.
+
+<!-- SETTINGS-AUTOGEN:START -->
+
+### General
+
+| UI Label                        | Setting                            | Description                                                   | Default |
+| ------------------------------- | ---------------------------------- | ------------------------------------------------------------- | ------- |
+| Preview Features (e.g., models) | `general.previewFeatures`          | Enable preview features (e.g., preview models).               | `false` |
+| Vim Mode                        | `general.vimMode`                  | Enable Vim keybindings                                        | `false` |
+| Disable Auto Update             | `general.disableAutoUpdate`        | Disable automatic updates                                     | `false` |
+| Enable Prompt Completion        | `general.enablePromptCompletion`   | Enable AI-powered prompt completion suggestions while typing. | `false` |
+| Debug Keystroke Logging         | `general.debugKeystrokeLogging`    | Enable debug logging of keystrokes to the console.            | `false` |
+| Enable Session Cleanup          | `general.sessionRetention.enabled` | Enable automatic session cleanup                              | `false` |
+
+### Output
+
+| UI Label      | Setting         | Description                                            | Default  |
+| ------------- | --------------- | ------------------------------------------------------ | -------- |
+| Output Format | `output.format` | The format of the CLI output. Can be `text` or `json`. | `"text"` |
+
+### UI
+
+| UI Label                       | Setting                                  | Description                                                                                                                                                       | Default |
+| ------------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| Hide Window Title              | `ui.hideWindowTitle`                     | Hide the window title bar                                                                                                                                         | `false` |
+| Show Thoughts in Title         | `ui.showStatusInTitle`                   | Show Cell CLI model thoughts in the terminal window title during the working phase                                                                                | `false` |
+| Dynamic Window Title           | `ui.dynamicWindowTitle`                  | Update the terminal window title with current status icons (Ready: ◇, Action Required: ✋, Working: ✦)                                                            | `true`  |
+| Show Home Directory Warning    | `ui.showHomeDirectoryWarning`            | Show a warning when running Cell CLI in the home directory.                                                                                                       | `true`  |
+| Hide Tips                      | `ui.hideTips`                            | Hide helpful tips in the UI                                                                                                                                       | `false` |
+| Hide Banner                    | `ui.hideBanner`                          | Hide the application banner                                                                                                                                       | `false` |
+| Hide Context Summary           | `ui.hideContextSummary`                  | Hide the context summary (GEMINI.md, MCP servers) above the input.                                                                                                | `false` |
+| Hide CWD                       | `ui.footer.hideCWD`                      | Hide the current working directory path in the footer.                                                                                                            | `false` |
+| Hide Sandbox Status            | `ui.footer.hideSandboxStatus`            | Hide the sandbox status indicator in the footer.                                                                                                                  | `false` |
+| Hide Model Info                | `ui.footer.hideModelInfo`                | Hide the model name and context usage in the footer.                                                                                                              | `false` |
+| Hide Context Window Percentage | `ui.footer.hideContextPercentage`        | Hides the context window remaining percentage.                                                                                                                    | `true`  |
+| Hide Footer                    | `ui.hideFooter`                          | Hide the footer from the UI                                                                                                                                       | `false` |
+| Show Memory Usage              | `ui.showMemoryUsage`                     | Display memory usage information in the UI                                                                                                                        | `false` |
+| Show Line Numbers              | `ui.showLineNumbers`                     | Show line numbers in the chat.                                                                                                                                    | `true`  |
+| Show Citations                 | `ui.showCitations`                       | Show citations for generated text in the chat.                                                                                                                    | `false` |
+| Show Model Info In Chat        | `ui.showModelInfoInChat`                 | Show the model name in the chat for each model turn.                                                                                                              | `false` |
+| Use Full Width                 | `ui.useFullWidth`                        | Use the entire width of the terminal for output.                                                                                                                  | `true`  |
+| Use Alternate Screen Buffer    | `ui.useAlternateBuffer`                  | Use an alternate screen buffer for the UI, preserving shell history.                                                                                              | `false` |
+| Incremental Rendering          | `ui.incrementalRendering`                | Enable incremental rendering for the UI. This option will reduce flickering but may cause rendering artifacts. Only supported when useAlternateBuffer is enabled. | `true`  |
+| Disable Loading Phrases        | `ui.accessibility.disableLoadingPhrases` | Disable loading phrases for accessibility                                                                                                                         | `false` |
+| Screen Reader Mode             | `ui.accessibility.screenReader`          | Render output in plain-text to be more screen reader accessible                                                                                                   | `false` |
+
+### IDE
+
+| UI Label | Setting       | Description                  | Default |
+| -------- | ------------- | ---------------------------- | ------- |
+| IDE Mode | `ide.enabled` | Enable IDE integration mode. | `false` |
+
+### Model
+
+| UI Label                | Setting                      | Description                                                                            | Default |
+| ----------------------- | ---------------------------- | -------------------------------------------------------------------------------------- | ------- |
+| Max Session Turns       | `model.maxSessionTurns`      | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited.      | `-1`    |
+| Compression Threshold   | `model.compressionThreshold` | The fraction of context usage at which to trigger context compression (e.g. 0.2, 0.3). | `0.5`   |
+| Skip Next Speaker Check | `model.skipNextSpeakerCheck` | Skip the next speaker check.                                                           | `true`  |
+
+### Context
+
+| UI Label                             | Setting                                           | Description                                                                                                                                     | Default |
+| ------------------------------------ | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| Memory Discovery Max Dirs            | `context.discoveryMaxDirs`                        | Maximum number of directories to search for memory.                                                                                             | `200`   |
+| Load Memory From Include Directories | `context.loadMemoryFromIncludeDirectories`        | Controls how /memory refresh loads GEMINI.md files. When true, include directories are scanned; when false, only the current directory is used. | `false` |
+| Respect .gitignore                   | `context.fileFiltering.respectGitIgnore`          | Respect .gitignore files when searching.                                                                                                        | `true`  |
+| Respect .geminiignore                | `context.fileFiltering.respectGeminiIgnore`       | Respect .geminiignore files when searching.                                                                                                     | `true`  |
+| Enable Recursive File Search         | `context.fileFiltering.enableRecursiveFileSearch` | Enable recursive file search functionality when completing @ references in the prompt.                                                          | `true`  |
+| Disable Fuzzy Search                 | `context.fileFiltering.disableFuzzySearch`        | Disable fuzzy search when searching for files.                                                                                                  | `false` |
+
+### Tools
+
+| UI Label                         | Setting                              | Description                                                                                                                                                                | Default   |
+| -------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
+| Enable Interactive Shell         | `tools.shell.enableInteractiveShell` | Use node-pty for an interactive shell experience. Fallback to child_process still applies.                                                                                 | `true`    |
+| Show Color                       | `tools.shell.showColor`              | Show color in shell output.                                                                                                                                                | `false`   |
+| Auto Accept                      | `tools.autoAccept`                   | Automatically accept and execute tool calls that are considered safe (e.g., read-only operations).                                                                         | `false`   |
+| Use Ripgrep                      | `tools.useRipgrep`                   | Use ripgrep for file content search instead of the fallback implementation. Provides faster search performance.                                                            | `true`    |
+| Enable Tool Output Truncation    | `tools.enableToolOutputTruncation`   | Enable truncation of large tool outputs.                                                                                                                                   | `true`    |
+| Tool Output Truncation Threshold | `tools.truncateToolOutputThreshold`  | Truncate tool output if it is larger than this many characters. Set to -1 to disable.                                                                                      | `4000000` |
+| Tool Output Truncation Lines     | `tools.truncateToolOutputLines`      | The number of lines to keep when truncating tool output.                                                                                                                   | `1000`    |
+| Disable LLM Correction           | `tools.disableLLMCorrection`         | Disable LLM-based error correction for edit tools. When enabled, tools will fail immediately if exact string matches are not found, instead of attempting to self-correct. | `false`   |
+
+### Security
+
+| UI Label                              | Setting                                         | Description                                                                     | Default |
+| ------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- | ------- |
+| Disable YOLO Mode                     | `security.disableYoloMode`                      | Disable YOLO mode, even if enabled by a flag.                                   | `false` |
+| Allow Permanent Tool Approval         | `security.enablePermanentToolApproval`          | Enable the "Allow for all future sessions" option in tool confirmation dialogs. | `false` |
+| Blocks extensions from Git            | `security.blockGitExtensions`                   | Blocks installing and loading extensions from Git.                              | `false` |
+| Folder Trust                          | `security.folderTrust.enabled`                  | Setting to track whether Folder trust is enabled.                               | `false` |
+| Enable Environment Variable Redaction | `security.environmentVariableRedaction.enabled` | Enable redaction of environment variables that may contain secrets.             | `false` |
+
+### LoadMemoryFromIncludeDirectories
+
+| UI Label                             | Setting                            | Description                                            | Default |
+| ------------------------------------ | ---------------------------------- | ------------------------------------------------------ | ------- |
+| Load Memory From Include Directories | `loadMemoryFromIncludeDirectories` | Whether to load memory files from include directories. | `false` |
+
+### FolderTrustFeature
+
+| UI Label             | Setting              | Description                                        | Default |
+| -------------------- | -------------------- | -------------------------------------------------- | ------- |
+| Folder Trust Feature | `folderTrustFeature` | Enable folder trust feature for enhanced security. | `false` |
+
+### FolderTrust
+
+| UI Label     | Setting       | Description                                       | Default |
+| ------------ | ------------- | ------------------------------------------------- | ------- |
+| Folder Trust | `folderTrust` | Setting to track whether Folder trust is enabled. | `false` |
+
+### Experimental
+
+| UI Label                            | Setting                                                 | Description                                                                         | Default |
+| ----------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------- |
+| Agent Skills                        | `experimental.skills`                                   | Enable Agent Skills (experimental).                                                 | `false` |
+| Enable Codebase Investigator        | `experimental.codebaseInvestigatorSettings.enabled`     | Enable the Codebase Investigator agent.                                             | `true`  |
+| Codebase Investigator Max Num Turns | `experimental.codebaseInvestigatorSettings.maxNumTurns` | Maximum number of turns for the Codebase Investigator agent.                        | `10`    |
+| Use OSC 52 Paste                    | `experimental.useOSC52Paste`                            | Use OSC 52 sequence for pasting instead of clipboardy (useful for remote sessions). | `false` |
+| Enable CLI Help Agent               | `experimental.cliHelpAgentSettings.enabled`             | Enable the CLI Help Agent.                                                          | `true`  |
+
+### Hooks
+
+| UI Label           | Setting               | Description                                      | Default |
+| ------------------ | --------------------- | ------------------------------------------------ | ------- |
+| Hook Notifications | `hooks.notifications` | Show visual indicators when hooks are executing. | `true`  |
+
+<!-- SETTINGS-AUTOGEN:END -->

package/dist/docs/cli/skills.md

@@ -0,0 +1,188 @@
+# Agent Skills
+
+_Note: This is an experimental feature enabled via `experimental.skills`. You
+can also search for "Skills" within the `/settings` interactive UI to toggle
+this and manage other skill-related settings._
+
+Agent Skills allow you to extend Cell CLI with specialized expertise, procedural
+workflows, and task-specific resources. Based on the
+[Agent Skills](https://agentskills.io) open standard, a "skill" is a
+self-contained directory that packages instructions and assets into a
+discoverable capability.
+
+## Overview
+
+Unlike general context files ([`GEMINI.md`](./gemini-md.md)), which provide
+persistent project-wide background, Skills represent **on-demand expertise**.
+This allows Gemini to maintain a vast library of specialized capabilities—such
+as security auditing, cloud deployments, or codebase migrations—without
+cluttering the model's immediate context window.
+
+Gemini autonomously decides when to employ a skill based on your request and the
+skill's description. When a relevant skill is identified, the model "pulls in"
+the full instructions and resources required to complete the task using the
+`activate_skill` tool.
+
+## Key Benefits
+
+- **Shared Expertise:** Package complex workflows (like a specific team's PR
+  review process) into a folder that anyone can use.
+- **Repeatable Workflows:** Ensure complex multi-step tasks are performed
+  consistently by providing a procedural framework.
+- **Resource Bundling:** Include scripts, templates, or example data alongside
+  instructions so the agent has everything it needs.
+- **Progressive Disclosure:** Only skill metadata (name and description) is
+  loaded initially. Detailed instructions and resources are only disclosed when
+  the model explicitly activates the skill, saving context tokens.
+
+## Skill Discovery Tiers
+
+Cell CLI discovers skills from three primary locations:
+
+1.  **Project Skills** (`.cell-cli/skills/`): Project-specific skills that are
+    typically committed to version control and shared with the team.
+2.  **User Skills** (`~/.cell-cli/skills/`): Personal skills available across
+    all your projects.
+3.  **Extension Skills**: Skills bundled within installed
+    [extensions](../extensions/index.md).
+
+**Precedence:** If multiple skills share the same name, higher-precedence
+locations override lower ones: **Project > User > Extension**.
+
+## Managing Skills
+
+### In an Interactive Session
+
+Use the `/skills` slash command to view and manage available expertise:
+
+- `/skills list` (default): Shows all discovered skills and their status.
+- `/skills disable <name>`: Prevents a specific skill from being used.
+- `/skills enable <name>`: Re-enables a disabled skill.
+- `/skills reload`: Refreshes the list of discovered skills from all tiers.
+
+_Note: `/skills disable` and `/skills enable` default to the `user` scope. Use
+`--scope project` to manage project-specific settings._
+
+### From the Terminal
+
+The `gemini skills` command provides management utilities:
+
+```bash
+# List all discovered skills
+gemini skills list
+
+# Install a skill from a Git repository, local directory, or zipped skill file (.skill)
+# Uses the user scope by default (~/.cell-cli/skills)
+gemini skills install https://github.com/user/repo.git
+gemini skills install /path/to/local/skill
+gemini skills install /path/to/local/my-expertise.skill
+
+# Install a specific skill from a monorepo or subdirectory using --path
+gemini skills install https://github.com/my-org/my-skills.git --path skills/frontend-design
+
+# Install to the workspace scope (.cell-cli/skills)
+gemini skills install /path/to/skill --scope workspace
+
+# Uninstall a skill by name
+gemini skills uninstall my-expertise --scope workspace
+
+# Enable a skill (globally)
+gemini skills enable my-expertise
+
+# Disable a skill. Can use --scope to specify project or user (defaults to project)
+gemini skills disable my-expertise --scope project
+```
+
+## Creating a Skill
+
+A skill is a directory containing a `SKILL.md` file at its root. This file uses
+YAML frontmatter for metadata and Markdown for instructions.
+
+### Folder Structure
+
+Skills are self-contained directories. At a minimum, a skill requires a
+`SKILL.md` file, but can include other resources:
+
+```text
+my-skill/
+├── SKILL.md       (Required) Instructions and metadata
+├── scripts/       (Optional) Executable scripts/tools
+├── references/    (Optional) Static documentation and examples
+└── assets/        (Optional) Templates and binary resources
+```
+
+### Basic Structure (SKILL.md)
+
+```markdown
+---
+name: <unique-name>
+description: <what the skill does and when Gemini should use it>
+---
+
+<your instructions for how the agent should behave / use the skill>
+```
+
+- **`name`**: A unique identifier (lowercase, alphanumeric, and dashes).
+- **`description`**: The most critical field. Gemini uses this to decide when
+  the skill is relevant. Be specific about the expertise provided.
+- **Body**: Everything below the second `---` is injected as expert procedural
+  guidance for the model.
+
+### Example: Team Code Reviewer
+
+Create `~/.cell-cli/skills/code-reviewer/SKILL.md`:
+
+```markdown
+---
+name: code-reviewer
+description:
+  Expertise in reviewing code for style, security, and performance. Use when the
+  user asks for "feedback," a "review," or to "check" their changes.
+---
+
+# Code Reviewer
+
+You are an expert code reviewer. When reviewing code, follow this workflow:
+
+1.  **Analyze**: Review the staged changes or specific files provided. Ensure
+    that the changes are scoped properly and represent minimal changes required
+    to address the issue.
+2.  **Style**: Ensure code follows the project's conventions and idiomatic
+    patterns as described in the `GEMINI.md` file.
+3.  **Security**: Flag any potential security vulnerabilities.
+4.  **Tests**: Verify that new logic has corresponding test coverage and that
+    the test coverage adequately validates the changes.
+
+Provide your feedback as a concise bulleted list of "Strengths" and
+"Opportunities."
+```
+
+### Resource Conventions
+
+While you can structure your skill directory however you like, the Agent Skills
+standard encourages these conventions:
+
+- **`scripts/`**: Executable scripts (bash, python, node) the agent can run.
+- **`references/`**: Static documentation, schemas, or example data for the
+  agent to consult.
+- **`assets/`**: Code templates, boilerplate, or binary resources.
+
+When a skill is activated, Cell CLI provides the model with a tree view of the
+entire skill directory, allowing it to discover and utilize these assets.
+
+## How it Works (Security & Privacy)
+
+1.  **Discovery**: At the start of a session, Cell CLI scans the discovery tiers
+    and injects the name and description of all enabled skills into the system
+    prompt.
+2.  **Activation**: When Gemini identifies a task matching a skill's
+    description, it calls the `activate_skill` tool.
+3.  **Consent**: You will see a confirmation prompt in the UI detailing the
+    skill's name, purpose, and the directory path it will gain access to.
+4.  **Injection**: Upon your approval:
+    - The `SKILL.md` body and folder structure is added to the conversation
+      history.
+    - The skill's directory is added to the agent's allowed file paths, granting
+      it permission to read any bundled assets.
+5.  **Execution**: The model proceeds with the specialized expertise active. It
+    is instructed to prioritize the skill's procedural guidance within reason.

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

@@ -0,0 +1,94 @@
+# System Prompt Override (CELL_SYSTEM_MD)
+
+The core system instructions that guide Cell CLI can be completely replaced with
+your own Markdown file. This feature is controlled via the `CELL_SYSTEM_MD`
+environment variable.
+
+## Overview
+
+The `CELL_SYSTEM_MD` variable instructs the CLI to use an external Markdown file
+for its system prompt, completely overriding the built-in default. This is a
+full replacement, not a merge. If you use a custom file, none of the original
+core instructions will apply unless you include them yourself.
+
+This feature is intended for advanced users who need to enforce strict,
+project-specific behavior or create a customized persona.
+
+> Tip: You can export the current default system prompt to a file first, review
+> it, and then selectively modify or replace it (see
+> [“Export the default prompt”](#export-the-default-prompt-recommended)).
+
+## How to enable
+
+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).
+
+- Use the project default path (`.cell-cli/system.md`):
+  - `CELL_SYSTEM_MD=true` or `CELL_SYSTEM_MD=1`
+  - The CLI reads `./.cell-cli/system.md` (relative to your current project
+    directory).
+
+- Use a custom file path:
+  - `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`).
+
+- Disable the override (use built‑in prompt):
+  - `CELL_SYSTEM_MD=false` or `CELL_SYSTEM_MD=0` or unset the variable.
+
+If the override is enabled but the target file does not exist, the CLI will
+error with: `missing system prompt file '<path>'`.
+
+## Quick examples
+
+- One‑off session using a project file:
+  - `CELL_SYSTEM_MD=1 gemini`
+- Persist for a project using `.cell-cli/.env`:
+  - 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`
+
+## UI indicator
+
+When `CELL_SYSTEM_MD` is active, the CLI shows a `|⌐■_■|` indicator in the UI to
+signal custom system‑prompt mode.
+
+## Export the default prompt (recommended)
+
+Before overriding, export the current default prompt so you can review required
+safety and workflow rules.
+
+- Write the built‑in prompt to the project default path:
+  - `CELL_WRITE_SYSTEM_MD=1 gemini`
+- Or write to a custom path:
+  - `CELL_WRITE_SYSTEM_MD=~/prompts/DEFAULT_SYSTEM.md gemini`
+
+This creates the file and writes the current built‑in system prompt to it.
+
+## Best practices: SYSTEM.md vs GEMINI.md
+
+- 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.
+
+Keep SYSTEM.md minimal but complete for safety and tool operation. Keep
+GEMINI.md focused on high‑level guidance and project specifics.
+
+## Troubleshooting
+
+- Error: `missing system prompt file '…'`
+  - Ensure the referenced path exists and is readable.
+  - For `CELL_SYSTEM_MD=1|true`, create `./.cell-cli/system.md` in your project.
+- Override not taking effect
+  - Confirm the variable is loaded (use `.cell-cli/.env` or export in your
+    shell).
+  - Paths are resolved from the current working directory; try an absolute path.
+- Restore defaults
+  - Unset `CELL_SYSTEM_MD` or set it to `0`/`false`.