@thacio/auditaria 0.30.12 → 0.30.13

package/bundle/docs/cli/tutorials/shell-commands.md

@@ -0,0 +1,107 @@
+# Execute shell commands
+
+Use the CLI to run builds, manage git, and automate system tasks without leaving
+the conversation. In this guide, you'll learn how to run commands directly,
+automate complex workflows, and manage background processes safely.
+
+## Prerequisites
+
+- Gemini CLI installed and authenticated.
+- Basic familiarity with your system's shell (Bash, Zsh, PowerShell, etc.).
+
+## How to run commands directly (`!`)
+
+Sometimes you just need to check a file size or git status without asking the AI
+to do it for you. You can pass commands directly to your shell using the `!`
+prefix.
+
+**Example:** `!ls -la`
+
+This executes `ls -la` immediately and prints the output to your terminal. The
+AI doesn't "see" this output unless you paste it back into the chat or use it in
+a prompt.
+
+### Scenario: Entering Shell mode
+
+If you're doing a lot of manual work, toggle "Shell Mode" by typing `!` and
+pressing **Enter**. Now, everything you type is sent to the shell until you exit
+(usually by pressing **Esc** or typing `exit`).
+
+## How to automate complex tasks
+
+You can automate tasks using a combination of Gemini CLI and shell commands.
+
+### Scenario: Run tests and fix failures
+
+You want to run tests and fix any failures.
+
+**Prompt:**
+`Run the unit tests. If any fail, analyze the error and try to fix the code.`
+
+**Workflow:**
+
+1.  Gemini calls `run_shell_command('npm test')`.
+2.  You see a confirmation prompt: `Allow command 'npm test'? [y/N]`.
+3.  You press `y`.
+4.  The tests run. If they fail, Gemini reads the error output.
+5.  Gemini uses `read_file` to inspect the failing test.
+6.  Gemini uses `replace` to fix the bug.
+7.  Gemini runs `npm test` again to verify the fix.
+
+This loop turns Gemini into an autonomous engineer.
+
+## How to manage background processes
+
+You can ask Gemini to start long-running tasks, like development servers or file
+watchers.
+
+**Prompt:** `Start the React dev server in the background.`
+
+Gemini will run the command (e.g., `npm run dev`) and detach it.
+
+### Scenario: Viewing active shells
+
+To see what's running in the background, use the `/shells` command.
+
+**Command:** `/shells`
+
+This opens a dashboard where you can view logs or kill runaway processes.
+
+## How to handle interactive commands
+
+Gemini CLI attempts to handle interactive commands (like `git add -p` or
+confirmation prompts) by streaming the output to you. However, for highly
+interactive tools (like `vim` or `top`), it's often better to run them yourself
+in a separate terminal window or use the `!` prefix.
+
+## Safety first
+
+Giving an AI access to your shell is powerful but risky. Gemini CLI includes
+several safety layers.
+
+### Confirmation prompts
+
+By default, **every** shell command requested by the agent requires your
+explicit approval.
+
+- **Allow once:** Runs the command one time.
+- **Allow always:** Trusts this specific command for the rest of the session.
+- **Deny:** Stops the agent.
+
+### Sandboxing
+
+For maximum security, especially when running untrusted code or exploring new
+projects, we strongly recommend enabling Sandboxing. This runs all shell
+commands inside a secure Docker container.
+
+**Enable sandboxing:** Use the `--sandbox` flag when starting the CLI:
+`gemini --sandbox`.
+
+## Next steps
+
+- Learn about [Sandboxing](../../cli/sandbox.md) to safely run destructive
+  commands.
+- See the [Shell tool reference](../../tools/shell.md) for configuration options
+  like timeouts and working directories.
+- Explore [Task planning](task-planning.md) to see how shell commands fit into
+  larger workflows.

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

@@ -1,23 +1,27 @@
-# Getting Started with Agent Skills
+# Get started with Agent Skills
 
-Agent Skills allow you to extend Gemini CLI with specialized expertise. This
-tutorial will guide you through creating your first skill and using it in a
-session.
+Agent Skills extend Gemini 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.
 
-## 1. Create your first skill
+## How to create a skill
 
-A skill is a directory containing a `SKILL.md` file. Let's create an **API
-Auditor** skill that helps you verify if local or remote endpoints are
+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.
 
-1.  **Create the skill directory structure:**
+### Create the directory structure
+
+1.  Run the following command to create the folders:
 
     ```bash
     mkdir -p .gemini/skills/api-auditor/scripts
     ```
 
-2.  **Create the `SKILL.md` file:** Create a file at
-    `.gemini/skills/api-auditor/SKILL.md` with the following content:
+### Create the definition
+
+1.  Create a file at `.gemini/skills/api-auditor/SKILL.md`. This tells the agent
+    _when_ to use the skill and _how_ to behave.
 
     ```markdown
     ---
@@ -40,9 +44,12 @@ responding correctly.
         without an `https://` protocol.
     ```
 
-3.  **Create the bundled Node.js script:** Create a file at
-    `.gemini/skills/api-auditor/scripts/audit.js`. This script will be used by
-    the agent to perform the actual check:
+### Add the tool logic
+
+Skills can bundle resources like scripts.
+
+1.  Create a file at `.gemini/skills/api-auditor/scripts/audit.js`. This is the
+    code the agent will run.
 
     ```javascript
     // .gemini/skills/api-auditor/scripts/audit.js
@@ -59,39 +66,37 @@ responding correctly.
       .catch((e) => console.error(`Result: Failed (${e.message})`));
     ```
 
-## 2. Verify the skill is discovered
-
-Use the `/skills` slash command (or `gemini skills list` from your terminal) to
-see if Gemini CLI has found your new skill.
+## How to verify discovery
 
-In a Gemini CLI session:
+Gemini CLI automatically discovers skills in the `.gemini/skills` directory. You
+can also use `.agents/skills` as a more generic alternative. Check that it found
+your new skill.
 
-```
-/skills list
-```
+**Command:** `/skills list`
 
 You should see `api-auditor` in the list of available skills.
 
-## 3. Use the skill in a chat
+## How to use the skill
 
-Now, let's see the skill in action. Start a new session and ask a question about
-an endpoint.
+Now, try it out. Start a new session and ask a question that triggers the
+skill's description.
 
-**User:** "Can you audit http://geminili.com"
+**User:** "Can you audit http://geminicli.com"
 
-Gemini will recognize the request matches the `api-auditor` description and will
-ask for your permission to activate it.
+Gemini recognizes the request matches the `api-auditor` description and asks for
+permission to activate it.
 
 **Model:** (After calling `activate_skill`) "I've activated the **api-auditor**
 skill. I'll run the audit script now..."
 
-Gemini will then use the `run_shell_command` tool to execute your bundled Node
+Gemini then uses the `run_shell_command` tool to execute your bundled Node
 script:
 
 `node .gemini/skills/api-auditor/scripts/audit.js http://geminili.com`
 
-## Next Steps
+## Next steps
 
-- Explore [Agent Skills Authoring Guide](../skills.md#creating-a-skill) to learn
-  about more advanced skill features.
+- 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).

package/bundle/docs/cli/tutorials/task-planning.md

@@ -0,0 +1,93 @@
+# Plan tasks with todos
+
+Keep complex jobs on the rails with Gemini CLI's built-in task planning. In this
+guide, you'll learn how to ask for a plan, execute it step-by-step, and monitor
+progress with the todo list.
+
+## Prerequisites
+
+- Gemini CLI installed and authenticated.
+- A complex task in mind (e.g., a multi-file refactor or new feature).
+
+## Why use task planning?
+
+Standard LLMs have a limited context window and can "forget" the original goal
+after 10 turns of code generation. Task planning provides:
+
+1.  **Visibility:** You see exactly what the agent plans to do _before_ it
+    starts.
+2.  **Focus:** The agent knows exactly which step it's working on right now.
+3.  **Resilience:** If the agent gets stuck, the plan helps it get back on
+    track.
+
+## How to ask for a plan
+
+The best way to trigger task planning is to explicitly ask for it.
+
+**Prompt:**
+`I want to migrate this project from JavaScript to TypeScript. Please make a plan first.`
+
+Gemini will analyze your codebase and use the `write_todos` tool to generate a
+structured list.
+
+**Example Plan:**
+
+1.  [ ] Create `tsconfig.json`.
+2.  [ ] Rename `.js` files to `.ts`.
+3.  [ ] Fix type errors in `utils.js`.
+4.  [ ] Fix type errors in `server.js`.
+5.  [ ] Verify build passes.
+
+## How to review and iterate
+
+Once the plan is generated, it appears in your CLI. Review it.
+
+- **Missing steps?** Tell the agent: "You forgot to add a step for installing
+  `@types/node`."
+- **Wrong order?** Tell the agent: "Let's verify the build _after_ each file,
+  not just at the end."
+
+The agent will update the todo list dynamically.
+
+## How to execute the plan
+
+Tell the agent to proceed.
+
+**Prompt:** `Looks good. Start with the first step.`
+
+As the agent works, you'll see the todo list update in real-time above the input
+box.
+
+- **Current focus:** The active task is highlighted (e.g.,
+  `[IN_PROGRESS] Create tsconfig.json`).
+- **Progress:** Completed tasks are marked as done.
+
+## How to monitor progress (`Ctrl+T`)
+
+For a long-running task, the full todo list might be hidden to save space. You
+can toggle the full view at any time.
+
+**Action:** Press **Ctrl+T**.
+
+This shows the complete list, including pending, in-progress, and completed
+items. It's a great way to check "how much is left?" without scrolling back up.
+
+## How to handle unexpected changes
+
+Plans change. Maybe you discover a library is incompatible halfway through.
+
+**Prompt:**
+`Actually, let's skip the 'server.js' refactor for now. It's too risky.`
+
+The agent will mark that task as `cancelled` or remove it, and move to the next
+item. This dynamic adjustment is what makes the todo system powerful—it's a
+living document, not a static text block.
+
+## Next steps
+
+- Explore [Session management](session-management.md) to save your plan and
+  finish it tomorrow.
+- See the [Todo tool reference](../../tools/todos.md) for technical schema
+  details.
+- Learn about [Memory management](memory-management.md) to persist planning
+  preferences (e.g., "Always create a test plan first").

package/bundle/docs/cli/tutorials/web-tools.md

@@ -0,0 +1,78 @@
+# Web search and fetch
+
+Access the live internet directly from your prompt. In this guide, you'll learn
+how to search for up-to-date documentation, fetch deep context from specific
+URLs, and apply that knowledge to your code.
+
+## Prerequisites
+
+- Gemini CLI installed and authenticated.
+- An internet connection.
+
+## How to research new technologies
+
+Imagine you want to use a library released yesterday. The model doesn't know
+about it yet. You need to teach it.
+
+### Scenario: Find documentation
+
+**Prompt:**
+`Search for the 'Bun 1.0' release notes and summarize the key changes.`
+
+Gemini uses the `google_web_search` tool to find relevant pages and synthesizes
+an answer. This "grounding" process ensures the agent isn't hallucinating
+features that don't exist.
+
+**Prompt:** `Find the documentation for the 'React Router v7' loader API.`
+
+## How to fetch deep context
+
+Search gives you a summary, but sometimes you need the raw details. The
+`web_fetch` tool lets you feed a specific URL directly into the agent's context.
+
+### Scenario: Reading a blog post
+
+You found a blog post with the exact solution to your bug.
+
+**Prompt:**
+`Read https://example.com/fixing-memory-leaks and explain how to apply it to my code.`
+
+Gemini will retrieve the page content (stripping away ads and navigation) and
+use it to answer your question.
+
+### Scenario: Comparing sources
+
+You can even fetch multiple pages to compare approaches.
+
+**Prompt:**
+`Compare the pagination patterns in https://api.example.com/v1/docs and https://api.example.com/v2/docs.`
+
+## How to apply knowledge to code
+
+The real power comes when you combine web tools with file editing.
+
+**Workflow:**
+
+1.  **Search:** "How do I implement auth with Supabase?"
+2.  **Fetch:** "Read this guide: https://supabase.com/docs/guides/auth."
+3.  **Implement:** "Great. Now use that pattern to create an `auth.ts` file in
+    my project."
+
+## How to troubleshoot errors
+
+When you hit an obscure error message, paste it into the chat.
+
+**Prompt:**
+`I'm getting 'Error: hydration mismatch' in Next.js. Search for recent solutions.`
+
+The agent will search sources such as GitHub issues, StackOverflow, and forums
+to find relevant fixes that might be too new to be in its base training set.
+
+## Next steps
+
+- Explore [File management](file-management.md) to see how to apply the code you
+  generate.
+- See the [Web search tool reference](../../tools/web-search.md) for citation
+  details.
+- See the [Web fetch tool reference](../../tools/web-fetch.md) for technical
+  limitations.

package/bundle/docs/core/policy-engine.md

@@ -208,9 +208,11 @@ commandPrefix = "git "
 
 # (Optional) A regex to match against the entire shell command.
 # This is also syntactic sugar for `toolName = "run_shell_command"`.
-# Note: This pattern is tested against the JSON representation of the arguments (e.g., `{"command":"<your_command>"}`), so anchors like `^` or `$` will apply to the full JSON string, not just the command text.
+# Note: This pattern is tested against the JSON representation of the arguments (e.g., `{"command":"<your_command>"}`).
+# Because it prepends `"command":"`, it effectively matches from the start of the command.
+# Anchors like `^` or `$` apply to the full JSON string, so `^` should usually be avoided here.
 # You cannot use commandPrefix and commandRegex in the same rule.
-commandRegex = "^git (commit|push)"
+commandRegex = "git (commit|push)"
 
 # The decision to take. Must be "allow", "deny", or "ask_user".
 decision = "ask_user"

package/bundle/docs/core/subagents.md

@@ -1,13 +1,13 @@
-# Sub-agents (experimental)
+# Subagents (experimental)
 
-Sub-agents are specialized agents that operate within your main Gemini CLI
+Subagents are specialized agents that operate within your main Gemini CLI
 session. They are designed to handle specific, complex tasks—like deep codebase
 analysis, documentation lookup, or domain-specific reasoning—without cluttering
 the main agent's context or toolset.
 
-> **Note: Sub-agents are currently an experimental feature.**
+> **Note: Subagents are currently an experimental feature.**
 >
-> To use custom sub-agents, you must explicitly enable them in your
+> To use custom subagents, you must explicitly enable them in your
 > `settings.json`:
 >
 > ```json
@@ -16,31 +16,31 @@ the main agent's context or toolset.
 > }
 > ```
 >
-> **Warning:** Sub-agents currently operate in
+> **Warning:** Subagents currently operate in
 > ["YOLO mode"](../get-started/configuration.md#command-line-arguments), meaning
 > they may execute tools without individual user confirmation for each step.
 > Proceed with caution when defining agents with powerful tools like
 > `run_shell_command` or `write_file`.
 
-## What are sub-agents?
+## What are subagents?
 
-Sub-agents are "specialists" that the main Gemini agent can hire for a specific
+Subagents are "specialists" that the main Gemini agent can hire for a specific
 job.
 
-- **Focused context:** Each sub-agent has its own system prompt and persona.
-- **Specialized tools:** Sub-agents can have a restricted or specialized set of
+- **Focused context:** Each subagent has its own system prompt and persona.
+- **Specialized tools:** Subagents can have a restricted or specialized set of
   tools.
-- **Independent context window:** Interactions with a sub-agent happen in a
+- **Independent context window:** Interactions with a subagent happen in a
   separate context loop, which saves tokens in your main conversation history.
 
-Sub-agents are exposed to the main agent as a tool of the same name. When the
-main agent calls the tool, it delegates the task to the sub-agent. Once the
-sub-agent completes its task, it reports back to the main agent with its
+Subagents are exposed to the main agent as a tool of the same name. When the
+main agent calls the tool, it delegates the task to the subagent. Once the
+subagent completes its task, it reports back to the main agent with its
 findings.
 
-## Built-in sub-agents
+## Built-in subagents
 
-Gemini CLI comes with the following built-in sub-agents:
+Gemini CLI comes with the following built-in subagents:
 
 ### Codebase Investigator
 
@@ -75,15 +75,15 @@ Gemini CLI comes with the following built-in sub-agents:
 ### Generalist Agent
 
 - **Name:** `generalist_agent`
-- **Purpose:** Route tasks to the appropriate specialized sub-agent.
+- **Purpose:** Route tasks to the appropriate specialized subagent.
 - **When to use:** Implicitly used by the main agent for routing. Not directly
   invoked by the user.
 - **Configuration:** Enabled by default. No specific configuration options.
 
-## Creating custom sub-agents
+## Creating custom subagents
 
-You can create your own sub-agents to automate specific workflows or enforce
-specific personas. To use custom sub-agents, you must enable them in your
+You can create your own subagents to automate specific workflows or enforce
+specific personas. To use custom subagents, you must enable them in your
 `settings.json`:
 
 ```json
@@ -138,20 +138,20 @@ it yourself; just report it.
 
 ### Configuration schema
 
-| Field          | Type   | Required | Description                                                                                                                |
-| :------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------- |
-| `name`         | string | Yes      | Unique identifier (slug) used as the tool name for the agent. Only lowercase letters, numbers, hyphens, and underscores.   |
-| `description`  | string | Yes      | Short description of what the agent does. This is visible to the main agent to help it decide when to call this sub-agent. |
-| `kind`         | string | No       | `local` (default) or `remote`.                                                                                             |
-| `tools`        | array  | No       | List of tool names this agent can use. If omitted, it may have access to a default set.                                    |
-| `model`        | string | No       | Specific model to use (e.g., `gemini-2.5-pro`). Defaults to `inherit` (uses the main session model).                       |
-| `temperature`  | number | No       | Model temperature (0.0 - 2.0).                                                                                             |
-| `max_turns`    | number | No       | Maximum number of conversation turns allowed for this agent before it must return. Defaults to `15`.                       |
-| `timeout_mins` | number | No       | Maximum execution time in minutes. Defaults to `5`.                                                                        |
+| Field          | Type   | Required | Description                                                                                                               |
+| :------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------ |
+| `name`         | string | Yes      | Unique identifier (slug) used as the tool name for the agent. Only lowercase letters, numbers, hyphens, and underscores.  |
+| `description`  | string | Yes      | Short description of what the agent does. This is visible to the main agent to help it decide when to call this subagent. |
+| `kind`         | string | No       | `local` (default) or `remote`.                                                                                            |
+| `tools`        | array  | No       | List of tool names this agent can use. If omitted, it may have access to a default set.                                   |
+| `model`        | string | No       | Specific model to use (e.g., `gemini-2.5-pro`). Defaults to `inherit` (uses the main session model).                      |
+| `temperature`  | number | No       | Model temperature (0.0 - 2.0).                                                                                            |
+| `max_turns`    | number | No       | Maximum number of conversation turns allowed for this agent before it must return. Defaults to `15`.                      |
+| `timeout_mins` | number | No       | Maximum execution time in minutes. Defaults to `5`.                                                                       |
 
-### Optimizing your sub-agent
+### Optimizing your subagent
 
-The main agent's system prompt encourages it to use an expert sub-agent when one
+The main agent's system prompt encourages it to use an expert subagent when one
 is available. It decides whether an agent is a relevant expert based on the
 agent's description. You can improve the reliability with which an agent is used
 by updating the description to more clearly indicate:
@@ -160,7 +160,7 @@ by updating the description to more clearly indicate:
 - When it should be used.
 - Some example scenarios.
 
-For example, the following sub-agent description should be called fairly
+For example, the following subagent description should be called fairly
 consistently for Git operations.
 
 > Git expert agent which should be used for all local and remote git operations.
@@ -170,13 +170,13 @@ consistently for Git operations.
 > - Searching for regressions with bisect
 > - Interacting with source control and issues providers such as GitHub.
 
-If you need to further tune your sub-agent, you can do so by selecting the model
+If you need to further tune your subagent, you can do so by selecting the model
 to optimize for with `/model` and then asking the model why it does not think
-that your sub-agent was called with a specific prompt and the given description.
+that your subagent was called with a specific prompt and the given description.
 
 ## Remote subagents (Agent2Agent) (experimental)
 
-Gemini CLI can also delegate tasks to remote sub-agents using the Agent-to-Agent
+Gemini CLI can also delegate tasks to remote subagents using the Agent-to-Agent
 (A2A) protocol.
 
 > **Note: Remote subagents are currently an experimental feature.**
@@ -184,8 +184,8 @@ Gemini CLI can also delegate tasks to remote sub-agents using the Agent-to-Agent
 See the [Remote Subagents documentation](/docs/core/remote-agents) for detailed
 configuration and usage instructions.
 
-## Extension sub-agents
+## Extension subagents
 
-Extensions can bundle and distribute sub-agents. See the
-[Extensions documentation](../extensions/index.md#sub-agents) for details on how
+Extensions can bundle and distribute subagents. See the
+[Extensions documentation](../extensions/index.md#subagents) for details on how
 to package agents within an extension.