@dgxo/mashadevcli 1.1.0

package/bundle/docs/cli/plan-mode.md

@@ -0,0 +1,375 @@
+# Plan Mode (experimental)
+
+Plan Mode is a read-only environment for architecting robust solutions before
+implementation. With Plan Mode, you can:
+
+- **Research:** Explore the project in a read-only state to prevent accidental
+  changes.
+- **Design:** Understand problems, evaluate trade-offs, and choose a solution.
+- **Plan:** Align on an execution strategy before any code is modified.
+
+> **Note:** This is a preview feature currently under active development. Your
+> feedback is invaluable as we refine this feature. If you have ideas,
+> suggestions, or encounter issues:
+>
+> - [Open an issue] on GitHub.
+> - Use the **/bug** command within Gemini CLI to file an issue.
+
+## How to enable Plan Mode
+
+Enable Plan Mode in **Settings** or by editing your configuration file.
+
+- **Settings:** Use the `/settings` command and set **Plan** to `true`.
+- **Configuration:** Add the following to your `settings.json`:
+
+  ```json
+  {
+    "experimental": {
+      "plan": true
+    }
+  }
+  ```
+
+## How to enter Plan Mode
+
+Plan Mode integrates seamlessly into your workflow, letting you switch between
+planning and execution as needed.
+
+You can either configure Gemini CLI to start in Plan Mode by default or enter
+Plan Mode manually during a session.
+
+### Launch in Plan Mode
+
+To start Gemini CLI directly in Plan Mode by default:
+
+1.  Use the `/settings` command.
+2.  Set **Default Approval Mode** to `Plan`.
+
+To launch Gemini CLI in Plan Mode once:
+
+1. Use `gemini --approval-mode=plan` when launching Gemini CLI.
+
+### Enter Plan Mode manually
+
+To start Plan Mode while using Gemini CLI:
+
+- **Keyboard shortcut:** Press `Shift+Tab` to cycle through approval modes
+  (`Default` -> `Auto-Edit` -> `Plan`).
+
+  > **Note:** Plan Mode is automatically removed from the rotation when Gemini
+  > CLI is actively processing or showing confirmation dialogs.
+
+- **Command:** Type `/plan` in the input box.
+
+- **Natural Language:** Ask Gemini CLI to "start a plan for...". Gemini CLI
+  calls the [`enter_plan_mode`] tool to switch modes.
+  > **Note:** This tool is not available when Gemini CLI is in [YOLO mode].
+
+## How to use Plan Mode
+
+Plan Mode lets you collaborate with Gemini CLI to design a solution before
+Gemini CLI takes action.
+
+1.  **Provide a goal:** Start by describing what you want to achieve. Gemini CLI
+    will then enter Plan Mode (if it's not already) to research the task.
+2.  **Review research and provide input:** As Gemini CLI analyzes your codebase,
+    it may ask you questions or present different implementation options using
+    [`ask_user`]. Provide your preferences to help guide the design.
+3.  **Review the plan:** Once Gemini CLI has a proposed strategy, it creates a
+    detailed implementation plan as a Markdown file in your plans directory. You
+    can open and read this file to understand the proposed changes.
+4.  **Approve or iterate:** Gemini CLI will present the finalized plan for your
+    approval.
+    - **Approve:** If you're satisfied with the plan, approve it to start the
+      implementation immediately: **Yes, automatically accept edits** or **Yes,
+      manually accept edits**.
+    - **Iterate:** If the plan needs adjustments, provide feedback. Gemini CLI
+      will refine the strategy and update the plan.
+    - **Cancel:** You can cancel your plan with `Esc`.
+
+For more complex or specialized planning tasks, you can
+[customize the planning workflow with skills](#custom-planning-with-skills).
+
+## How to exit Plan Mode
+
+You can exit Plan Mode at any time, whether you have finalized a plan or want to
+switch back to another mode.
+
+- **Approve a plan:** When Gemini CLI presents a finalized plan, approving it
+  automatically exits Plan Mode and starts the implementation.
+- **Keyboard shortcut:** Press `Shift+Tab` to cycle to the desired mode.
+- **Natural language:** Ask Gemini CLI to "exit plan mode" or "stop planning."
+
+## Customization and best practices
+
+Plan Mode is secure by default, but you can adapt it to fit your specific
+workflows. You can customize how Gemini CLI plans by using skills, adjusting
+safety policies, or changing where plans are stored.
+
+## Commands
+
+- **`/plan copy`**: Copy the currently approved plan to your clipboard.
+
+## Tool Restrictions
+
+Plan Mode enforces strict safety policies to prevent accidental changes.
+
+These are the only allowed tools:
+
+- **FileSystem (Read):** [`read_file`], [`list_directory`], [`glob`]
+- **Search:** [`grep_search`], [`google_web_search`]
+- **Research Subagents:** [`codebase_investigator`], [`cli_help`]
+- **Interaction:** [`ask_user`]
+- **MCP tools (Read):** Read-only [MCP tools] (for example, `github_read_issue`,
+  `postgres_read_schema`) are allowed.
+- **Planning (Write):** [`write_file`] and [`replace`] only allowed for `.md`
+  files in the `~/.gemini/tmp/<project>/<session-id>/plans/` directory or your
+  [custom plans directory](#custom-plan-directory-and-policies).
+- **Memory:** [`save_memory`]
+- **Skills:** [`activate_skill`] (allows loading specialized instructions and
+  resources in a read-only manner)
+
+### Custom planning with skills
+
+You can use [Agent Skills] to customize how Gemini CLI approaches planning for
+specific types of tasks. When a skill is activated during Plan Mode, its
+specialized instructions and procedural workflows will guide the research,
+design, and planning phases.
+
+For example:
+
+- A **"Database Migration"** skill could ensure the plan includes data safety
+  checks and rollback strategies.
+- A **"Security Audit"** skill could prompt Gemini CLI to look for specific
+  vulnerabilities during codebase exploration.
+- A **"Frontend Design"** skill could guide Gemini CLI to use specific UI
+  components and accessibility standards in its proposal.
+
+To use a skill in Plan Mode, you can explicitly ask Gemini CLI to "use the
+`<skill-name>` skill to plan..." or Gemini CLI may autonomously activate it
+based on the task description.
+
+### Custom policies
+
+Plan Mode's default tool restrictions are managed by the [policy engine] and
+defined in the built-in [`plan.toml`] file. The built-in policy (Tier 1)
+enforces the read-only state, but you can customize these rules by creating your
+own policies in your `~/.gemini/policies/` directory (Tier 2).
+
+#### Example: Automatically approve read-only MCP tools
+
+By default, read-only MCP tools require user confirmation in Plan Mode. You can
+use `toolAnnotations` and the `mcpName` wildcard to customize this behavior for
+your specific environment.
+
+`~/.gemini/policies/mcp-read-only.toml`
+
+```toml
+[[rule]]
+mcpName = "*"
+toolAnnotations = { readOnlyHint = true }
+decision = "allow"
+priority = 100
+modes = ["plan"]
+```
+
+For more information on how the policy engine works, see the [policy engine]
+docs.
+
+#### Example: Allow git commands in Plan Mode
+
+This rule lets you check the repository status and see changes while in Plan
+Mode.
+
+`~/.gemini/policies/git-research.toml`
+
+```toml
+[[rule]]
+toolName = "run_shell_command"
+commandPrefix = ["git status", "git diff"]
+decision = "allow"
+priority = 100
+modes = ["plan"]
+```
+
+#### Example: Enable custom subagents in Plan Mode
+
+Built-in research [subagents] like [`codebase_investigator`] and [`cli_help`]
+are enabled by default in Plan Mode. You can enable additional [custom
+subagents] by adding a rule to your policy.
+
+`~/.gemini/policies/research-subagents.toml`
+
+```toml
+[[rule]]
+toolName = "my_custom_subagent"
+decision = "allow"
+priority = 100
+modes = ["plan"]
+```
+
+Tell Gemini CLI it can use these tools in your prompt, for example: _"You can
+check ongoing changes in git."_
+
+### Custom plan directory and policies
+
+By default, planning artifacts are stored in a managed temporary directory
+outside your project: `~/.gemini/tmp/<project>/<session-id>/plans/`.
+
+You can configure a custom directory for plans in your `settings.json`. For
+example, to store plans in a `.gemini/plans` directory within your project:
+
+```json
+{
+  "general": {
+    "plan": {
+      "directory": ".gemini/plans"
+    }
+  }
+}
+```
+
+To maintain the safety of Plan Mode, user-configured paths for the plans
+directory are restricted to the project root. This ensures that custom planning
+locations defined within a project's workspace cannot be used to escape and
+overwrite sensitive files elsewhere. Any user-configured directory must reside
+within the project boundary.
+
+Using a custom directory requires updating your [policy engine] configurations
+to allow `write_file` and `replace` in that specific location. For example, to
+allow writing to the `.gemini/plans` directory within your project, create a
+policy file at `~/.gemini/policies/plan-custom-directory.toml`:
+
+```toml
+[[rule]]
+toolName = ["write_file", "replace"]
+decision = "allow"
+priority = 100
+modes = ["plan"]
+# Adjust the pattern to match your custom directory.
+# This example matches any .md file in a .gemini/plans directory within the project.
+argsPattern = "\"file_path\":\"[^\"]+[\\\\/]+\\.gemini[\\\\/]+plans[\\\\/]+[\\w-]+\\.md\""
+```
+
+## Planning workflows
+
+Plan Mode provides building blocks for structured research and design. These are
+implemented as [extensions] using core planning tools like [`enter_plan_mode`],
+[`exit_plan_mode`], and [`ask_user`].
+
+### Built-in planning workflow
+
+The built-in planner uses an adaptive workflow to analyze your project, consult
+you on trade-offs via [`ask_user`], and draft a plan for your approval.
+
+### Custom planning workflows
+
+You can install or create specialized planners to suit your workflow.
+
+#### Conductor
+
+[Conductor] is designed for spec-driven development. It organizes work into
+"tracks" and stores persistent artifacts in your project's `conductor/`
+directory:
+
+- **Automate transitions:** Switches to read-only mode via [`enter_plan_mode`].
+- **Streamline decisions:** Uses [`ask_user`] for architectural choices.
+- **Maintain project context:** Stores artifacts in the project directory using
+  [custom plan directory and policies](#custom-plan-directory-and-policies).
+- **Handoff execution:** Transitions to implementation via [`exit_plan_mode`].
+
+#### Build your own
+
+Since Plan Mode is built on modular building blocks, you can develop your own
+custom planning workflow as an [extensions]. By leveraging core tools and
+[custom policies](#custom-policies), you can define how Gemini CLI researches
+and stores plans for your specific domain.
+
+To build a custom planning workflow, you can use:
+
+- **Tool usage:** Use core tools like [`enter_plan_mode`], [`ask_user`], and
+  [`exit_plan_mode`] to manage the research and design process.
+- **Customization:** Set your own storage locations and policy rules using
+  [custom plan directories](#custom-plan-directory-and-policies) and
+  [custom policies](#custom-policies).
+
+> **Note:** Use [Conductor] as a reference when building your own custom
+> planning workflow.
+
+By using Plan Mode as its execution environment, your custom methodology can
+enforce read-only safety during the design phase while benefiting from
+high-reasoning model routing.
+
+## Automatic Model Routing
+
+When using an [auto model], Gemini CLI automatically optimizes [model routing]
+based on the current phase of your task:
+
+1.  **Planning Phase:** While in Plan Mode, the CLI routes requests to a
+    high-reasoning **Pro** model to ensure robust architectural decisions and
+    high-quality plans.
+2.  **Implementation Phase:** Once a plan is approved and you exit Plan Mode,
+    the CLI detects the existence of the approved plan and automatically
+    switches to a high-speed **Flash** model. This provides a faster, more
+    responsive experience during the implementation of the plan.
+
+This behavior is enabled by default to provide the best balance of quality and
+performance. You can disable this automatic switching in your settings:
+
+```json
+{
+  "general": {
+    "plan": {
+      "modelRouting": false
+    }
+  }
+}
+```
+
+## Cleanup
+
+By default, Gemini CLI automatically cleans up old session data, including all
+associated plan files and task trackers.
+
+- **Default behavior:** Sessions (and their plans) are retained for **30 days**.
+- **Configuration:** You can customize this behavior via the `/settings` command
+  (search for **Session Retention**) or in your `settings.json` file. See
+  [session retention] for more details.
+
+Manual deletion also removes all associated artifacts:
+
+- **Command Line:** Use `gemini --delete-session <index|id>`.
+- **Session Browser:** Press `/resume`, navigate to a session, and press `x`.
+
+If you use a [custom plans directory](#custom-plan-directory-and-policies),
+those files are not automatically deleted and must be managed manually.
+
+[`list_directory`]: ../tools/file-system.md#1-list_directory-readfolder
+[`read_file`]: ../tools/file-system.md#2-read_file-readfile
+[`grep_search`]: ../tools/file-system.md#5-grep_search-searchtext
+[`write_file`]: ../tools/file-system.md#3-write_file-writefile
+[`glob`]: ../tools/file-system.md#4-glob-findfiles
+[`google_web_search`]: ../tools/web-search.md
+[`replace`]: ../tools/file-system.md#6-replace-edit
+[MCP tools]: ../tools/mcp-server.md
+[`save_memory`]: ../tools/memory.md
+[`activate_skill`]: ./skills.md
+[`codebase_investigator`]: ../core/subagents.md#codebase_investigator
+[`cli_help`]: ../core/subagents.md#cli_help
+[subagents]: ../core/subagents.md
+[custom subagents]: ../core/subagents.md#creating-custom-subagents
+[policy engine]: ../reference/policy-engine.md
+[`enter_plan_mode`]: ../tools/planning.md#1-enter_plan_mode-enterplanmode
+[`exit_plan_mode`]: ../tools/planning.md#2-exit_plan_mode-exitplanmode
+[`ask_user`]: ../tools/ask-user.md
+[YOLO mode]: ../reference/configuration.md#command-line-arguments
+[`plan.toml`]:
+  https://github.com/DGameGT/mashadev-cli/blob/main/packages/core/src/policy/policies/plan.toml
+[auto model]: ../reference/configuration.md#model-settings
+[model routing]: ./telemetry.md#model-routing
+[preferred external editor]: ../reference/configuration.md#general
+[session retention]: ./session-management.md#session-retention
+[extensions]: ../extensions/index.md
+[Conductor]: https://github.com/gemini-cli-extensions/conductor
+[open an issue]: https://github.com/DGameGT/mashadev-cli/issues
+[Agent Skills]: ./skills.md

package/bundle/docs/cli/rewind.md

@@ -0,0 +1,51 @@
+# Rewind
+
+The `/rewind` command lets you go back to a previous state in your conversation
+and, optionally, revert any file changes made by the AI during those
+interactions. This is a powerful tool for undoing mistakes, exploring different
+approaches, or simply cleaning up your session history.
+
+## Usage
+
+To use the rewind feature, simply type `/rewind` into the input prompt and press
+**Enter**.
+
+Alternatively, you can use the keyboard shortcut: **Press `Esc` twice**.
+
+## Interface
+
+When you trigger a rewind, an interactive list of your previous interactions
+appears.
+
+1.  **Select interaction:** Use the **Up/Down arrow keys** to navigate through
+    the list. The most recent interactions are at the bottom.
+2.  **Preview:** As you select an interaction, you'll see a preview of the user
+    prompt and, if applicable, the number of files changed during that step.
+3.  **Confirm selection:** Press **Enter** on the interaction you want to rewind
+    back to.
+4.  **Action selection:** After selecting an interaction, you'll be presented
+    with a confirmation dialog with up to three options:
+    - **Rewind conversation and revert code changes:** Reverts both the chat
+      history and the file modifications to the state before the selected
+      interaction.
+    - **Rewind conversation:** Only reverts the chat history. File changes are
+      kept.
+    - **Revert code changes:** Only reverts the file modifications. The chat
+      history is kept.
+    - **Do nothing (esc):** Cancels the rewind operation.
+
+If no code changes were made since the selected point, the options related to
+reverting code changes will be hidden.
+
+## Key considerations
+
+- **Destructive action:** Rewinding is a destructive action for your current
+  session history and potentially your files. Use it with care.
+- **Agent awareness:** When you rewind the conversation, the AI model loses all
+  memory of the interactions that were removed. If you only revert code changes,
+  you may need to inform the model that the files have changed.
+- **Manual edits:** Rewinding only affects file changes made by the AI's edit
+  tools. It does **not** undo manual edits you've made or changes triggered by
+  the shell tool (`!`).
+- **Compression:** Rewind works across chat compression points by reconstructing
+  the history from stored session data.

package/bundle/docs/cli/sandbox.md

@@ -0,0 +1,257 @@
+# Sandboxing in the Gemini CLI
+
+This document provides a guide to sandboxing in the Gemini CLI, including
+prerequisites, quickstart, and configuration.
+
+## Prerequisites
+
+Before using sandboxing, you need to install and set up the Gemini CLI:
+
+```bash
+npm install -g @dgxo/mashadevcli
+```
+
+To verify the installation:
+
+```bash
+gemini --version
+```
+
+## Overview of sandboxing
+
+Sandboxing isolates potentially dangerous operations (such as shell commands or
+file modifications) from your host system, providing a security barrier between
+AI operations and your environment.
+
+The benefits of sandboxing include:
+
+- **Security**: Prevent accidental system damage or data loss.
+- **Isolation**: Limit file system access to project directory.
+- **Consistency**: Ensure reproducible environments across different systems.
+- **Safety**: Reduce risk when working with untrusted code or experimental
+  commands.
+
+## Sandboxing methods
+
+Your ideal method of sandboxing may differ depending on your platform and your
+preferred container solution.
+
+### 1. macOS Seatbelt (macOS only)
+
+Lightweight, built-in sandboxing using `sandbox-exec`.
+
+**Default profile**: `permissive-open` - restricts writes outside project
+directory but allows most other operations.
+
+### 2. Container-based (Docker/Podman)
+
+Cross-platform sandboxing with complete process isolation.
+
+**Note**: Requires building the sandbox image locally or using a published image
+from your organization's registry.
+
+### 3. LXC/LXD (Linux only, experimental)
+
+Full-system container sandboxing using LXC/LXD. Unlike Docker/Podman, LXC
+containers run a complete Linux system with `systemd`, `snapd`, and other system
+services. This is ideal for tools that don't work in standard Docker containers,
+such as Snapcraft and Rockcraft.
+
+**Prerequisites**:
+
+- Linux only.
+- LXC/LXD must be installed (`snap install lxd` or `apt install lxd`).
+- A container must be created and running before starting Gemini CLI. Gemini
+  does **not** create the container automatically.
+
+**Quick setup**:
+
+```bash
+# Initialize LXD (first time only)
+lxd init --auto
+
+# Create and start an Ubuntu container
+lxc launch ubuntu:24.04 gemini-sandbox
+
+# Enable LXC sandboxing
+export GEMINI_SANDBOX=lxc
+gemini -p "build the project"
+```
+
+**Custom container name**:
+
+```bash
+export GEMINI_SANDBOX=lxc
+export GEMINI_SANDBOX_IMAGE=my-snapcraft-container
+gemini -p "build the snap"
+```
+
+**Limitations**:
+
+- Linux only (LXC is not available on macOS or Windows).
+- The container must already exist and be running.
+- The workspace directory is bind-mounted into the container at the same
+  absolute path — the path must be writable inside the container.
+- Used with tools like Snapcraft or Rockcraft that require a full system.
+
+## Quickstart
+
+```bash
+# Enable sandboxing with command flag
+gemini -s -p "analyze the code structure"
+```
+
+**Use environment variable**
+
+**macOS/Linux**
+
+```bash
+export GEMINI_SANDBOX=true
+gemini -p "run the test suite"
+```
+
+**Windows (PowerShell)**
+
+```powershell
+$env:GEMINI_SANDBOX="true"
+gemini -p "run the test suite"
+```
+
+**Configure in settings.json**
+
+```json
+{
+  "tools": {
+    "sandbox": "docker"
+  }
+}
+```
+
+## Configuration
+
+### Enable sandboxing (in order of precedence)
+
+1. **Command flag**: `-s` or `--sandbox`
+2. **Environment variable**:
+   `GEMINI_SANDBOX=true|docker|podman|sandbox-exec|lxc`
+3. **Settings file**: `"sandbox": true` in the `tools` object of your
+   `settings.json` file (e.g., `{"tools": {"sandbox": true}}`).
+
+### macOS Seatbelt profiles
+
+Built-in profiles (set via `SEATBELT_PROFILE` env var):
+
+- `permissive-open` (default): Write restrictions, network allowed
+- `permissive-proxied`: Write restrictions, network via proxy
+- `restrictive-open`: Strict restrictions, network allowed
+- `restrictive-proxied`: Strict restrictions, network via proxy
+- `strict-open`: Read and write restrictions, network allowed
+- `strict-proxied`: Read and write restrictions, network via proxy
+
+### Custom sandbox flags
+
+For container-based sandboxing, you can inject custom flags into the `docker` or
+`podman` command using the `SANDBOX_FLAGS` environment variable. This is useful
+for advanced configurations, such as disabling security features for specific
+use cases.
+
+**Example (Podman)**:
+
+To disable SELinux labeling for volume mounts, you can set the following:
+
+**macOS/Linux**
+
+```bash
+export SANDBOX_FLAGS="--security-opt label=disable"
+```
+
+**Windows (PowerShell)**
+
+```powershell
+$env:SANDBOX_FLAGS="--security-opt label=disable"
+```
+
+Multiple flags can be provided as a space-separated string:
+
+**macOS/Linux**
+
+```bash
+export SANDBOX_FLAGS="--flag1 --flag2=value"
+```
+
+**Windows (PowerShell)**
+
+```powershell
+$env:SANDBOX_FLAGS="--flag1 --flag2=value"
+```
+
+## Linux UID/GID handling
+
+The sandbox automatically handles user permissions on Linux. Override these
+permissions with:
+
+**macOS/Linux**
+
+```bash
+export SANDBOX_SET_UID_GID=true   # Force host UID/GID
+export SANDBOX_SET_UID_GID=false  # Disable UID/GID mapping
+```
+
+**Windows (PowerShell)**
+
+```powershell
+$env:SANDBOX_SET_UID_GID="true"   # Force host UID/GID
+$env:SANDBOX_SET_UID_GID="false"  # Disable UID/GID mapping
+```
+
+## Troubleshooting
+
+### Common issues
+
+**"Operation not permitted"**
+
+- Operation requires access outside sandbox.
+- Try more permissive profile or add mount points.
+
+**Missing commands**
+
+- Add to custom Dockerfile.
+- Install via `sandbox.bashrc`.
+
+**Network issues**
+
+- Check sandbox profile allows network.
+- Verify proxy configuration.
+
+### Debug mode
+
+```bash
+DEBUG=1 gemini -s -p "debug command"
+```
+
+**Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect
+gemini-cli due to automatic exclusion. Use `.gemini/.env` files for gemini-cli
+specific debug settings.
+
+### Inspect sandbox
+
+```bash
+# Check environment
+gemini -s -p "run shell command: env | grep SANDBOX"
+
+# List mounts
+gemini -s -p "run shell command: mount | grep workspace"
+```
+
+## Security notes
+
+- Sandboxing reduces but doesn't eliminate all risks.
+- Use the most restrictive profile that allows your work.
+- Container overhead is minimal after first build.
+- GUI applications may not work in sandboxes.
+
+## Related documentation
+
+- [Configuration](../reference/configuration.md): Full configuration options.
+- [Commands](../reference/commands.md): Available commands.
+- [Troubleshooting](../resources/troubleshooting.md): General troubleshooting.