@terminai/core 0.21.0

package/dist/docs/cli/terminaI-md.md

@@ -0,0 +1,109 @@
+# Provide context with terminaI.md files
+
+Context files, which use the default name `terminaI.md`, are a powerful feature
+for providing instructional context to the Gemini model. You can use these files
+to give project-specific instructions, define a persona, or provide coding style
+guides to make the AI's responses more accurate and tailored to your needs.
+
+Instead of repeating instructions in every prompt, you can define them once in a
+context file.
+
+## Understand the context hierarchy
+
+The CLI uses a hierarchical system to source context. It loads various context
+files from several locations, concatenates the contents of all found files, and
+sends them to the model with every prompt. The CLI loads files in the following
+order:
+
+1.  **Global context file:**
+    - **Location:** `~/.terminai/terminaI.md` (in your user home directory).
+    - **Scope:** Provides default instructions for all your projects.
+
+2.  **Project root and ancestor context files:**
+    - **Location:** The CLI searches for a `terminaI.md` file in your current
+      working directory and then in each parent directory up to the project root
+      (identified by a `.git` folder).
+    - **Scope:** Provides context relevant to the entire project.
+
+3.  **Sub-directory context files:**
+    - **Location:** The CLI also scans for `terminaI.md` files in subdirectories
+      below your current working directory. It respects rules in `.gitignore`
+      and `.geminiignore`.
+    - **Scope:** Lets you write highly specific instructions for a particular
+      component or module.
+
+The CLI footer displays the number of loaded context files, which gives you a
+quick visual cue of the active instructional context.
+
+### Example `terminaI.md` file
+
+Here is an example of what you can include in a `terminaI.md` file at the root
+of a TypeScript project:
+
+```markdown
+# Project: My TypeScript Library
+
+## General Instructions
+
+- When you generate new TypeScript code, follow the existing coding style.
+- Ensure all new functions and classes have JSDoc comments.
+- Prefer functional programming paradigms where appropriate.
+
+## Coding Style
+
+- Use 2 spaces for indentation.
+- Prefix interface names with `I` (for example, `IUserService`).
+- Always use strict equality (`===` and `!==`).
+```
+
+## Manage context with the `/memory` command
+
+You can interact with the loaded context files by using the `/memory` command.
+
+- **`/memory show`**: Displays the full, concatenated content of the current
+  hierarchical memory. This lets you inspect the exact instructional context
+  being provided to the model.
+- **`/memory refresh`**: Forces a re-scan and reload of all `terminaI.md` files
+  from all configured locations.
+- **`/memory add <text>`**: Appends your text to your global
+  `~/.terminai/terminaI.md` file. This lets you add persistent memories on the
+  fly.
+
+## Modularize context with imports
+
+You can break down large `terminaI.md` files into smaller, more manageable
+components by importing content from other files using the `@file.md` syntax.
+This feature supports both relative and absolute paths.
+
+**Example `terminaI.md` with imports:**
+
+```markdown
+# Main terminaI.md file
+
+This is the main content.
+
+@./components/instructions.md
+
+More content here.
+
+@../shared/style-guide.md
+```
+
+For more details, see the [Memory Import Processor](../core/memport.md)
+documentation.
+
+## Customize the context file name
+
+While `terminaI.md` is the default filename, you can configure this in your
+`settings.json` file. To specify a different name or a list of names, use the
+`context.fileName` property.
+
+**Example `settings.json`:**
+
+```json
+{
+  "context": {
+    "fileName": ["AGENTS.md", "CONTEXT.md", "terminaI.md"]
+  }
+}
+```

package/dist/docs/cli/themes.md

@@ -0,0 +1,253 @@
+# Themes
+
+TerminaI inherits the theme system from the upstream Gemini CLI.
+
+You can customize the color scheme via the `/theme` command or the `"theme"`
+setting.
+
+## Available themes
+
+TerminaI comes with a selection of pre-defined themes, which you can list using
+the `/theme` command:
+
+- **Dark themes:**
+  - `ANSI`
+  - `Atom One`
+  - `Ayu`
+  - `Default`
+  - `Dracula`
+  - `GitHub`
+- **Light themes:**
+  - `ANSI Light`
+  - `Ayu Light`
+  - `Default Light`
+  - `GitHub Light`
+  - `Google Code`
+  - `Xcode`
+
+### Changing themes
+
+1.  Enter `/theme` into TerminaI.
+2.  A dialog or selection prompt appears, listing the available themes.
+3.  Using the arrow keys, select a theme. Some interfaces might offer a live
+    preview or highlight as you select.
+4.  Confirm your selection to apply the theme.
+
+**Note:** If a theme is defined in your `settings.json` file (either by name or
+by a file path), you must remove the `"theme"` setting from the file before you
+can change the theme using the `/theme` command.
+
+### Theme persistence
+
+Selected themes are saved in TerminaI's
+[configuration](../get-started/configuration.md) so your preference is
+remembered across sessions.
+
+---
+
+## TerminaI look (recommended)
+
+If you're contributing and want the hacker terminal vibe, pick a high-contrast
+dark theme and keep your terminal background near-black.
+
+Examples (these are generated from the built-in theme set):
+
+<img src="../assets/theme-default.png" alt="Default theme (dark)" width="600" />
+
+<img src="../assets/theme-github.png" alt="GitHub theme (dark)" width="600" />
+
+<img src="../assets/theme-ayu.png" alt="Ayu theme (dark)" width="600" />
+
+---
+
+## Custom color themes
+
+Gemini CLI allows you to create your own custom color themes by specifying them
+in your `settings.json` file. This gives you full control over the color palette
+used in the CLI.
+
+### How to define a custom theme
+
+Add a `customThemes` block to your user, project, or system `settings.json`
+file. Each custom theme is defined as an object with a unique name and a set of
+color keys. For example:
+
+```json
+{
+  "ui": {
+    "customThemes": {
+      "MyCustomTheme": {
+        "name": "MyCustomTheme",
+        "type": "custom",
+        "Background": "#181818",
+        ...
+      }
+    }
+  }
+}
+```
+
+**Color keys:**
+
+- `Background`
+- `Foreground`
+- `LightBlue`
+- `AccentBlue`
+- `AccentPurple`
+- `AccentCyan`
+- `AccentGreen`
+- `AccentYellow`
+- `AccentRed`
+- `Comment`
+- `Gray`
+- `DiffAdded` (optional, for added lines in diffs)
+- `DiffRemoved` (optional, for removed lines in diffs)
+- `DiffModified` (optional, for modified lines in diffs)
+
+You can also override individual UI text roles by adding a nested `text` object.
+This object supports the keys `primary`, `secondary`, `link`, `accent`, and
+`response`. When `text.response` is provided it takes precedence over
+`text.primary` for rendering model responses in chat.
+
+**Required properties:**
+
+- `name` (must match the key in the `customThemes` object and be a string)
+- `type` (must be the string `"custom"`)
+- `Background`
+- `Foreground`
+- `LightBlue`
+- `AccentBlue`
+- `AccentPurple`
+- `AccentCyan`
+- `AccentGreen`
+- `AccentYellow`
+- `AccentRed`
+- `Comment`
+- `Gray`
+
+You can use either hex codes (e.g., `#FF0000`) **or** standard CSS color names
+(e.g., `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.
+
+You can define multiple custom themes by adding more entries to the
+`customThemes` object.
+
+### Loading themes from a file
+
+In addition to defining custom themes in `settings.json`, you can also load a
+theme directly from a JSON file by specifying the file path in your
+`settings.json`. This is useful for sharing themes or keeping them separate from
+your main configuration.
+
+To load a theme from a file, set the `theme` property in your `settings.json` to
+the path of your theme file:
+
+```json
+{
+  "ui": {
+    "theme": "/path/to/your/theme.json"
+  }
+}
+```
+
+The theme file must be a valid JSON file that follows the same structure as a
+custom theme defined in `settings.json`.
+
+**Example `my-theme.json`:**
+
+```json
+{
+  "name": "My File Theme",
+  "type": "custom",
+  "Background": "#282A36",
+  "Foreground": "#F8F8F2",
+  "LightBlue": "#82AAFF",
+  "AccentBlue": "#61AFEF",
+  "AccentPurple": "#BD93F9",
+  "AccentCyan": "#8BE9FD",
+  "AccentGreen": "#50FA7B",
+  "AccentYellow": "#F1FA8C",
+  "AccentRed": "#FF5555",
+  "Comment": "#6272A4",
+  "Gray": "#ABB2BF",
+  "DiffAdded": "#A6E3A1",
+  "DiffRemoved": "#F38BA8",
+  "DiffModified": "#89B4FA",
+  "GradientColors": ["#4796E4", "#847ACE", "#C3677F"]
+}
+```
+
+**Security note:** For your safety, Gemini CLI will only load theme files that
+are located within your home directory. If you attempt to load a theme from
+outside your home directory, a warning will be displayed and the theme will not
+be loaded. This is to prevent loading potentially malicious theme files from
+untrusted sources.
+
+### Example custom theme
+
+<img src="../assets/theme-custom.png" alt="Custom theme example" width="600" />
+
+### Using your custom theme
+
+- Select your custom theme using the `/theme` command in Gemini CLI. Your custom
+  theme will appear in the theme selection dialog.
+- Or, set it as the default by adding `"theme": "MyCustomTheme"` to the `ui`
+  object in your `settings.json`.
+- Custom themes can be set at the user, project, or system level, and follow the
+  same [configuration precedence](../get-started/configuration.md) as other
+  settings.
+
+---
+
+## Dark themes
+
+### ANSI
+
+<img src="/assets/theme-ansi.png" alt="ANSI theme" width="600" />
+
+### Atom OneDark
+
+<img src="/assets/theme-atom-one.png" alt="Atom One theme" width="600">
+
+### Ayu
+
+<img src="/assets/theme-ayu.png" alt="Ayu theme" width="600">
+
+### Default
+
+<img src="/assets/theme-default.png" alt="Default theme" width="600">
+
+### Dracula
+
+<img src="/assets/theme-dracula.png" alt="Dracula theme" width="600">
+
+### GitHub
+
+<img src="/assets/theme-github.png" alt="GitHub theme" width="600">
+
+## Light themes
+
+### ANSI Light
+
+<img src="/assets/theme-ansi-light.png" alt="ANSI Light theme" width="600">
+
+### Ayu Light
+
+<img src="/assets/theme-ayu-light.png" alt="Ayu Light theme" width="600">
+
+### Default Light
+
+<img src="/assets/theme-default-light.png" alt="Default Light theme" width="600">
+
+### GitHub Light
+
+<img src="/assets/theme-github-light.png" alt="GitHub Light theme" width="600">
+
+### Google Code
+
+<img src="/assets/theme-google-light.png" alt="Google Code theme" width="600">
+
+### Xcode
+
+<img src="/assets/theme-xcode-light.png" alt="Xcode Light theme" width="600">

package/dist/docs/cli/token-caching.md

@@ -0,0 +1,20 @@
+# Token caching and cost optimization
+
+Gemini CLI automatically optimizes API costs through token caching when using
+API key authentication (Gemini API key or Vertex AI). This feature reuses
+previous system instructions and context to reduce the number of tokens
+processed in subsequent requests.
+
+**Token caching is available for:**
+
+- API key users (Gemini API key)
+- Vertex AI users (with project and location setup)
+
+**Token caching is not available for:**
+
+- OAuth users (Google Personal/Enterprise accounts) - the Code Assist API does
+  not support cached content creation at this time
+
+You can view your token usage and cached token savings using the `/stats`
+command. When cached tokens are available, they will be displayed in the stats
+output.

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

@@ -0,0 +1,95 @@
+# Trusted Folders
+
+The Trusted Folders feature is a security setting that gives you control over
+which projects can use the full capabilities of the Gemini 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.
+
+## Enabling the feature
+
+The Trusted Folders feature is **disabled by default**. To use it, you must
+first enable it in your settings.
+
+Add the following to your user `settings.json` file:
+
+```json
+{
+  "security": {
+    "folderTrust": {
+      "enabled": true
+    }
+  }
+}
+```
+
+## How it works: The trust dialog
+
+Once the feature is enabled, the first time you run the Gemini 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.,
+  `my-project`).
+- **Trust parent folder**: Grants trust to the parent directory (e.g.,
+  `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
+  restricted "safe mode."
+
+Your choice is saved in a central file (`~/.terminai/trustedFolders.json`), so
+you will only be asked once per folder.
+
+## Why trust matters: The impact of an untrusted workspace
+
+When a folder is **untrusted**, the Gemini 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
+    `.terminai/settings.json` file from the project. This prevents the loading
+    of custom tools and other potentially dangerous configurations.
+
+2.  **Environment variables are ignored**: The CLI will **not** load any `.env`
+    files from the project.
+
+3.  **Extension management is restricted**: You **cannot install, update, or
+    uninstall** extensions.
+
+4.  **Tool auto-acceptance is disabled**: You will always be prompted before any
+    tool is run, even if you have auto-acceptance enabled globally.
+
+5.  **Automatic memory loading is disabled**: The CLI will not automatically
+    load files into context from directories specified in local settings.
+
+6.  **MCP servers do not connect**: The CLI will not attempt to connect to any
+    [Model Context Protocol (MCP)](../tools/mcp-server.md) servers.
+
+7.  **Custom commands are not loaded**: The CLI will not load any custom
+    commands from .toml files, including both project-specific and global user
+    commands.
+
+Granting trust to a folder unlocks the full functionality of the Gemini CLI for
+that workspace.
+
+## Managing your trust settings
+
+If you need to change a decision or see all your settings, you have a couple of
+options:
+
+- **Change the current folder's trust**: Run the `/permissions` command from
+  within the CLI. This will bring up the same interactive dialog, allowing you
+  to change the trust level for the current folder.
+
+- **View all trust rules**: To see a complete list of all your trusted and
+  untrusted folder rules, you can inspect the contents of the
+  `~/.terminai/trustedFolders.json` file in your home directory.
+
+## The trust check process (advanced)
+
+For advanced users, it's helpful to know the exact order of operations for how
+trust is determined:
+
+1.  **IDE trust signal**: If you are using the
+    [IDE Integration](../ide-integration/index.md), the CLI first asks the IDE
+    if the workspace is trusted. The IDE's response takes highest priority.
+
+2.  **Local trust file**: If the IDE is not connected, the CLI checks the
+    central `~/.terminai/trustedFolders.json` file.

package/dist/docs/cli/tutorials.md

@@ -0,0 +1,130 @@
+# Tutorials (System Operator)
+
+These are hands-on, “operator style” tutorials for TerminaI.
+
+> Note on config paths: TerminaI is migrating toward `~/.terminai/` as the
+> primary home. Some installs may still read legacy `~/.gemini/` for
+> compatibility.
+
+---
+
+## Tutorial 1 — Fix a broken WiFi connection (laptop)
+
+Goal: diagnose + repair WiFi, with approvals for risky steps.
+
+1. Start TerminaI:
+
+```bash
+terminai
+```
+
+2. Prompt:
+
+```text
+My WiFi stopped working. Diagnose what’s wrong and fix it.
+Explain what you find. For any destructive step, ask for confirmation first.
+```
+
+3. What “good” looks like:
+
+- TerminaI inspects: interface state, driver/module, rfkill, logs.
+- It proposes steps like:
+  - restart NetworkManager
+  - reload a kernel module
+  - renew DHCP
+- You see confirmations before impactful actions.
+
+---
+
+## Tutorial 2 — Disk cleanup (safe + reversible)
+
+```text
+I’m low on disk space. Find the biggest directories and propose a safe cleanup plan.
+Prefer reversible cleanups (caches/log rotations) before deletes.
+```
+
+Good output includes:
+
+- a ranked list of suspects
+- a plan with “safe → riskier” steps
+- explicit confirmation before deletions
+
+---
+
+## Tutorial 3 — Restart a broken service and verify it’s healthy
+
+```text
+My app is down. Identify the service, restart it safely, and verify it’s healthy.
+If there are errors in logs, summarize the root cause.
+```
+
+---
+
+## Tutorial 4 — Connect an MCP server (add new powers)
+
+> [!CAUTION] Before using a third-party MCP server, ensure you trust its source
+> and understand the tools it provides.
+
+This tutorial demonstrates adding an MCP server using the GitHub MCP server:
+https://github.com/github/github-mcp-server
+
+### Prerequisites
+
+- **Docker:** Install and run [Docker].
+- **GitHub Personal Access Token (PAT):** Create a new [classic] or
+  [fine-grained] PAT.
+
+[Docker]: https://www.docker.com/
+[classic]: https://github.com/settings/tokens/new
+[fine-grained]: https://github.com/settings/personal-access-tokens/new
+
+### Configure `settings.json`
+
+Create or open your settings file:
+
+- preferred: `~/.terminai/settings.json`
+- legacy fallback: `~/.gemini/settings.json`
+
+Add:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+Set your token:
+
+```bash
+export GITHUB_PERSONAL_ACCESS_TOKEN="pat_YourActualGitHubTokenHere"
+```
+
+Then ask:
+
+```text
+List my open GitHub issues assigned to me and summarize them.
+```
+
+---
+
+## Tutorial 5 — Run A2A (drive TerminaI from other clients)
+
+If you want to control TerminaI from a browser/desktop client/IDE integration,
+start the A2A server and follow:
+
+- `docs-terminai/web-remote.md`

package/dist/docs/cli/uninstall.md

@@ -0,0 +1,47 @@
+# Uninstalling the CLI
+
+Your uninstall method depends on how you ran the CLI. Follow the instructions
+for either npx or a global npm installation.
+
+## Method 1: Using npx
+
+npx runs packages from a temporary cache without a permanent installation. To
+"uninstall" the CLI, you must clear this cache, which will remove gemini-cli and
+any other packages previously executed with npx.
+
+The npx cache is a directory named `_npx` inside your main npm cache folder. You
+can find your npm cache path by running `npm config get cache`.
+
+**For macOS / Linux**
+
+```bash
+# The path is typically ~/.npm/_npx
+rm -rf "$(npm config get cache)/_npx"
+```
+
+**For Windows**
+
+_Command Prompt_
+
+```cmd
+:: The path is typically %LocalAppData%\npm-cache\_npx
+rmdir /s /q "%LocalAppData%\npm-cache\_npx"
+```
+
+_PowerShell_
+
+```powershell
+# The path is typically $env:LocalAppData\npm-cache\_npx
+Remove-Item -Path (Join-Path $env:LocalAppData "npm-cache\_npx") -Recurse -Force
+```
+
+## Method 2: Using npm (global install)
+
+If you installed the CLI globally (e.g., `npm install -g @google/gemini-cli`),
+use the `npm uninstall` command with the `-g` flag to remove it.
+
+```bash
+npm uninstall -g @google/gemini-cli
+```
+
+This command completely removes the package from your system.