From 7178b77527c09495d0a3232ce0842835a3bcc67c Mon Sep 17 00:00:00 2001
From: Rahul Kamat <rahulkamat@google.com>
Date: Wed, 11 Mar 2026 11:56:19 -0700
Subject: [PATCH] docs(cli): generalize profile documentation examples

---
 docs/cli/profiles.md | 79 ++++++++++++++++++++++++++++++++++++++++++++
 docs/sidebar.json    |  1 +
 2 files changed, 80 insertions(+)
 create mode 100644 docs/cli/profiles.md

diff --git a/docs/cli/profiles.md b/docs/cli/profiles.md
new file mode 100644
index 0000000000..27756bde3f
--- /dev/null
+++ b/docs/cli/profiles.md
@@ -0,0 +1,79 @@
+# Profiles
+
+Profiles allow you to maintain separate configurations for different workflows,
+tasks, or personas. Each profile can define its own set of allowed extensions, a
+default model, and a custom system instruction (persona).
+
+Profiles are particularly useful for:
+
+- Switching between domain-specific setups (e.g., frontend development vs.
+  system administration).
+- Defining specialized AI personas for different tasks.
+- Restricting available tools/extensions for specific projects.
+
+## Profile structure
+
+Profiles are Markdown files (`.md`) that use YAML frontmatter for configuration
+and the file body for system instructions.
+
+**Location**: `~/.gemini/profiles/[profile-name].md`
+
+### Example profile (`coder.md`)
+
+```markdown
+---
+name: Web Developer
+default_model: gemini-2.0-flash
+extensions:
+  - github
+  - web-search
+---
+
+You are a world-class Web Developer. Focus on React, TypeScript, and modern CSS.
+Always prefer functional components and explain your reasoning.
+```
+
+### Configuration fields
+
+| Field           | Description                                                                                     |
+| :-------------- | :---------------------------------------------------------------------------------------------- |
+| `name`          | (Optional) A display name for the profile.                                                      |
+| `default_model` | (Optional) The model to use when this profile is active.                                        |
+| `extensions`    | (Optional) A list of allowed extension IDs. If specified, only these extensions will be loaded. |
+
+The **body** of the Markdown file is injected into the system prompt, allowing
+you to define a specific persona or set of instructions that the AI will always
+follow when the profile is active.
+
+## Usage
+
+### Single session usage
+
+Use the `--profiles` flag (or `-P`) to use a profile for a single session:
+
+```bash
+gemini --profiles coder
+```
+
+### Persistent default
+
+You can set a profile as your default for all sessions:
+
+```bash
+gemini profiles enable coder
+```
+
+To return to the standard configuration:
+
+```bash
+gemini profiles disable
+```
+
+## Commands
+
+| Command                            | Description                                              |
+| :--------------------------------- | :------------------------------------------------------- |
+| `gemini profiles list`             | List all available profiles and see which one is active. |
+| `gemini profiles enable <name>`    | Set a profile as the persistent default.                 |
+| `gemini profiles disable`          | Clear the persistent default profile.                    |
+| `gemini profiles uninstall <name>` | Delete a profile from your local storage.                |
diff --git a/docs/sidebar.json b/docs/sidebar.json
index 7c201e0071..1eaefc2ee4 100644
--- a/docs/sidebar.json
+++ b/docs/sidebar.json
@@ -149,6 +149,7 @@
             "label": "Project context (GEMINI.md)",
             "slug": "docs/cli/gemini-md"
           },
+          { "label": "Profiles", "slug": "docs/cli/profiles" },
           { "label": "Settings", "slug": "docs/cli/settings" },
           {
             "label": "System prompt override",