@thacio/auditaria 0.30.11 → 0.30.13

package/bundle/docs/extensions/releasing.md

@@ -1,146 +1,117 @@
-# Extension releasing
-
-There are two primary ways of releasing extensions to users:
-
-- [Git repository](#releasing-through-a-git-repository)
-- [Github Releases](#releasing-through-github-releases)
-
-Git repository releases tend to be the simplest and most flexible approach,
-while GitHub releases can be more efficient on initial install as they are
-shipped as single archives instead of requiring a git clone which downloads each
-file individually. Github releases may also contain platform specific archives
-if you need to ship platform specific binary files.
-
-## Releasing through a git repository
-
-This is the most flexible and simple option. All you need to do is create a
-publicly accessible git repo (such as a public github repository) and then users
-can install your extension using `auditaria extensions install <your-repo-uri>`.
-They can optionally depend on a specific ref (branch/tag/commit) using the
-`--ref=<some-ref>` argument, this defaults to the default branch.
-
-Whenever commits are pushed to the ref that a user depends on, they will be
-prompted to update the extension. Note that this also allows for easy rollbacks,
-the HEAD commit is always treated as the latest version regardless of the actual
-version in the `gemini-extension.json` file.
-
-### Managing release channels using a git repository
-
-Users can depend on any ref from your git repo, such as a branch or tag, which
-allows you to manage multiple release channels.
-
-For instance, you can maintain a `stable` branch, which users can install this
-way `auditaria extensions install <your-repo-uri> --ref=stable`. Or, you could
-make this the default by treating your default branch as your stable release
-branch, and doing development in a different branch (for instance called `dev`).
-You can maintain as many branches or tags as you like, providing maximum
-flexibility for you and your users.
-
-Note that these `ref` arguments can be tags, branches, or even specific commits,
-which allows users to depend on a specific version of your extension. It is up
-to you how you want to manage your tags and branches.
-
-### Example releasing flow using a git repo
-
-While there are many options for how you want to manage releases using a git
-flow, we recommend treating your default branch as your "stable" release branch.
-This means that the default behavior for
-`auditaria extensions install <your-repo-uri>` is to be on the stable release
-branch.
-
-Lets say you want to maintain three standard release channels, `stable`,
-`preview`, and `dev`. You would do all your standard development in the `dev`
-branch. When you are ready to do a preview release, you merge that branch into
-your `preview` branch. When you are ready to promote your preview branch to
-stable, you merge `preview` into your stable branch (which might be your default
-branch or a different branch).
-
-You can also cherry pick changes from one branch into another using
-`git cherry-pick`, but do note that this will result in your branches having a
-slightly divergent history from each other, unless you force push changes to
-your branches on each release to restore the history to a clean slate (which may
-not be possible for the default branch depending on your repository settings).
-If you plan on doing cherry picks, you may want to avoid having your default
-branch be the stable branch to avoid force-pushing to the default branch which
-should generally be avoided.
-
-## Releasing through GitHub releases
-
-Auditaria extensions can be distributed through
-[GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases).
-This provides a faster and more reliable initial installation experience for
-users, as it avoids the need to clone the repository.
-
-Each release includes at least one archive file, which contains the full
-contents of the repo at the tag that it was linked to. Releases may also include
-[pre-built archives](#custom-pre-built-archives) if your extension requires some
-build step or has platform specific binaries attached to it.
-
-When checking for updates, auditaria will just look for the "latest" release on
-github (you must mark it as such when creating the release), unless the user
-installed a specific release by passing `--ref=<some-release-tag>`.
-
-You may also install extensions with the `--pre-release` flag in order to get
-the latest release regardless of whether it has been marked as "latest". This
-allows you to test that your release works before actually pushing it to all
-users.
+# Release extensions
 
-### Custom pre-built archives
+Release Auditaria CLI extensions to your users through a Git repository or
+GitHub Releases.
+
+Git repository releases are the simplest approach and offer the most flexibility
+for managing development branches. GitHub Releases are more efficient for
+initial installations because they ship as single archives rather than requiring
+a full `git clone`. Use GitHub Releases if you need to include platform-specific
+binary files.
+
+## List your extension in the gallery
+
+The [Gemini CLI extension gallery](https://geminicli.com/extensions/browse/)
+automatically indexes public extensions to help users discover your work. You
+don't need to submit an issue or email us to list your extension.
+
+To have your extension automatically discovered and listed:
+
+1.  **Use a public repository:** Ensure your extension is hosted in a public
+    GitHub repository.
+2.  **Add the GitHub topic:** Add the `gemini-cli-extension` topic to your
+    repository's **About** section. Our crawler uses this topic to find new
+    extensions.
+3.  **Place the manifest at the root:** Ensure your `gemini-extension.json` file
+    is in the absolute root of the repository or the release archive.
+
+Our system crawls tagged repositories daily. Once you tag your repository, your
+extension will appear in the gallery if it passes validation.
+
+## Release through a Git repository
+
+Releasing through Git is the most flexible option. Create a public Git
+repository and provide the URL to your users. They can then install your
+extension using `auditaria extensions install <your-repo-uri>`.
+
+Users can optionally depend on a specific branch, tag, or commit using the
+`--ref` argument. For example:
+
+```bash
+auditaria extensions install <your-repo-uri> --ref=stable
+```
 
-Custom archives must be attached directly to the github release as assets and
-must be fully self-contained. This means they should include the entire
-extension, see [archive structure](#archive-structure).
+Whenever you push commits to the referenced branch, the CLI prompts users to
+update their installation. The `HEAD` commit is always treated as the latest
+version.
 
-If your extension is platform-independent, you can provide a single generic
-asset. In this case, there should be only one asset attached to the release.
+### Manage release channels
 
-Custom archives may also be used if you want to develop your extension within a
-larger repository, you can build an archive which has a different layout from
-the repo itself (for instance it might just be an archive of a subdirectory
-containing the extension).
+You can use branches or tags to manage different release channels, such as
+`stable`, `preview`, or `dev`.
 
-#### Platform specific archives
+We recommend using your default branch as the stable release channel. This
+ensures that the default installation command always provides the most reliable
+version of your extension. You can then use a `dev` branch for active
+development and merge it into the default branch when you are ready for a
+release.
 
-To ensure Auditaria can automatically find the correct release asset for
-each platform, you must follow this naming convention. The CLI will search for
-assets in the following order:
+## Release through GitHub Releases
 
-1.  **Platform and architecture-Specific:**
+Distributing extensions through
+[GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases)
+provides a faster installation experience by avoiding a repository clone.
+
+Auditaria CLI checks for updates by looking for the **Latest** release on
+GitHub. Users can also install specific versions using the `--ref` argument with
+a release tag. Use the `--pre-release` flag to install the latest version even
+if it isn't marked as **Latest**.
+
+### Custom pre-built archives
+
+You can attach custom archives directly to your GitHub Release as assets. This
+is useful if your extension requires a build step or includes platform-specific
+binaries.
+
+Custom archives must be fully self-contained and follow the required
+[archive structure](#archive-structure). If your extension is
+platform-independent, provide a single generic asset.
+
+#### Platform-specific archives
+
+To let Auditaria CLI find the correct asset for a user's platform, use the
+following naming convention:
+
+1.  **Platform and architecture-specific:**
     `{platform}.{arch}.{name}.{extension}`
 2.  **Platform-specific:** `{platform}.{name}.{extension}`
-3.  **Generic:** If only one asset is provided, it will be used as a generic
-    fallback.
-
-- `{name}`: The name of your extension.
-- `{platform}`: The operating system. Supported values are:
-  - `darwin` (macOS)
-  - `linux`
-  - `win32` (Windows)
-- `{arch}`: The architecture. Supported values are:
-  - `x64`
-  - `arm64`
-- `{extension}`: The file extension of the archive (e.g., `.tar.gz` or `.zip`).
+3.  **Generic:** A single asset will be used as a fallback if no specific match
+    is found.
+
+Use these values for the placeholders:
+
+- `{name}`: Your extension name.
+- `{platform}`: Use `darwin` (macOS), `linux`, or `win32` (Windows).
+- `{arch}`: Use `x64` or `arm64`.
+- `{extension}`: Use `.tar.gz` or `.zip`.
 
 **Examples:**
 
 - `darwin.arm64.my-tool.tar.gz` (specific to Apple Silicon Macs)
-- `darwin.my-tool.tar.gz` (for all Macs)
+- `darwin.my-tool.tar.gz` (fallback for all Macs, e.g. Intel)
 - `linux.x64.my-tool.tar.gz`
 - `win32.my-tool.zip`
 
 #### Archive structure
 
-Archives must be fully contained extensions and have all the standard
-requirements - specifically the `gemini-extension.json` file must be at the root
-of the archive.
-
-The rest of the layout should look exactly the same as a typical extension, see
-[extensions.md](extension.md).
+Archives must be fully contained extensions. The `gemini-extension.json` file
+must be at the root of the archive. The rest of the layout should match a
+standard extension structure.
 
 #### Example GitHub Actions workflow
 
-Here is an example of a GitHub Actions workflow that builds and releases an
-Auditaria extension for multiple platforms:
+Use this example workflow to build and release your extension for multiple
+platforms:
 
 ```yaml
 name: Release Extension

package/bundle/docs/extensions/writing-extensions.md

@@ -1,18 +1,19 @@
-# Getting started with Gemini CLI extensions
+# Build Gemini CLI extensions
 
-This guide will walk you through creating your first Gemini CLI extension.
-You'll learn how to set up a new extension, add a custom tool via an MCP server,
-create a custom command, and provide context to the model with a `GEMINI.md`
-file.
+Gemini CLI extensions let you expand the capabilities of Gemini CLI by adding
+custom tools, commands, and context. This guide walks you through creating your
+first extension, from setting up a template to adding custom functionality and
+linking it for local development.
 
 ## Prerequisites
 
-Before you start, make sure you have the Gemini CLI installed and a basic
+Before you start, ensure you have the Gemini CLI installed and a basic
 understanding of Node.js.
 
-## When to use what
+## Extension features
 
-Extensions offer a variety of ways to customize Gemini CLI.
+Extensions offer several ways to customize Gemini CLI. Use this table to decide
+which features your extension needs.
 
 | Feature                                                        | What it is                                                                                                         | When to use it                                                                                                                                                                                                                                                                                 | Invoked by            |
 | :------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------- |
@@ -21,11 +22,12 @@ Extensions offer a variety of ways to customize Gemini CLI.
 | **[Context file (`GEMINI.md`)](reference.md#contextfilename)** | A markdown file containing instructions that are loaded into the model's context at the start of every session.    | Use this to define the "personality" of your extension, set coding standards, or provide essential knowledge that the model should always have.                                                                                                                                                | CLI provides to model |
 | **[Agent skills](../cli/skills.md)**                           | A specialized set of instructions and workflows that the model activates only when needed.                         | Use this for complex, occasional tasks (like "create a PR" or "audit security") to avoid cluttering the main context window when the skill isn't being used.                                                                                                                                   | Model                 |
 | **[Hooks](../hooks/index.md)**                                 | A way to intercept and customize the CLI's behavior at specific lifecycle events (e.g., before/after a tool call). | Use this when you want to automate actions based on what the model is doing, like validating tool arguments, logging activity, or modifying the model's input/output.                                                                                                                          | CLI                   |
+| **[Custom themes](reference.md#themes)**                       | A set of color definitions to personalize the CLI UI.                                                              | Use this to provide a unique visual identity for your extension or to offer specialized high-contrast or thematic color schemes.                                                                                                                                                               | User (via /theme)     |
 
 ## Step 1: Create a new extension
 
-The easiest way to start is by using one of the built-in templates. We'll use
-the `mcp-server` example as our foundation.
+The easiest way to start is by using a built-in template. We'll use the
+`mcp-server` example as our foundation.
 
 Run the following command to create a new directory called `my-first-extension`
 with the template files:
@@ -34,7 +36,7 @@ with the template files:
 gemini extensions new my-first-extension mcp-server
 ```
 
-This will create a new directory with the following structure:
+This creates a directory with the following structure:
 
 ```
 my-first-extension/
@@ -45,12 +47,11 @@ my-first-extension/
 
 ## Step 2: Understand the extension files
 
-Let's look at the key files in your new extension.
+Your new extension contains several key files that define its behavior.
 
 ### `gemini-extension.json`
 
-This is the manifest file for your extension. It tells Gemini CLI how to load
-and use your extension.
+The manifest file tells Gemini CLI how to load and use your extension.
 
 ```json
 {
@@ -68,17 +69,15 @@ and use your extension.
 
 - `name`: The unique name for your extension.
 - `version`: The version of your extension.
-- `mcpServers`: This section defines one or more Model Context Protocol (MCP)
-  servers. MCP servers are how you can add new tools for the model to use.
-  - `command`, `args`, `cwd`: These fields specify how to start your server.
-    Notice the use of the `${extensionPath}` variable, which Gemini CLI replaces
-    with the absolute path to your extension's installation directory. This
-    allows your extension to work regardless of where it's installed.
+- `mcpServers`: Defines Model Context Protocol (MCP) servers to add new tools.
+  - `command`, `args`, `cwd`: Specify how to start your server. The
+    `${extensionPath}` variable is replaced with the absolute path to your
+    extension's directory.
 
 ### `example.js`
 
-This file contains the source code for your MCP server. It's a simple Node.js
-server that uses the `@modelcontextprotocol/sdk`.
+This file contains the source code for your MCP server. It uses the
+`@modelcontextprotocol/sdk` to define tools.
 
 ```javascript
 /**
@@ -120,24 +119,49 @@ server.registerTool(
   },
 );
 
-// ... (prompt registration omitted for brevity)
-
 const transport = new StdioServerTransport();
 await server.connect(transport);
 ```
 
-This server defines a single tool called `fetch_posts` that fetches data from a
-public API.
-
 ### `package.json`
 
-This is the standard configuration file for a Node.js project. It defines
-dependencies and scripts.
+The standard configuration file for a Node.js project. It defines dependencies
+and scripts for your extension.
+
+## Step 3: Add extension settings
+
+Some extensions need configuration, such as API keys or user preferences. Let's
+add a setting for an API key.
+
+1.  Open `gemini-extension.json`.
+2.  Add a `settings` array to the configuration:
+
+    ```json
+    {
+      "name": "mcp-server-example",
+      "version": "1.0.0",
+      "settings": [
+        {
+          "name": "API Key",
+          "description": "The API key for the service.",
+          "envVar": "MY_SERVICE_API_KEY",
+          "sensitive": true
+        }
+      ],
+      "mcpServers": {
+        // ...
+      }
+    }
+    ```
+
+When a user installs this extension, Gemini CLI will prompt them to enter the
+"API Key". The value will be stored securely in the system keychain (because
+`sensitive` is true) and injected into the MCP server's process as the
+`MY_SERVICE_API_KEY` environment variable.
 
-## Step 3: Link your extension
+## Step 4: Link your extension
 
-Before you can use the extension, you need to link it to your Gemini CLI
-installation for local development.
+Link your extension to your Gemini CLI installation for local development.
 
 1.  **Install dependencies:**
 
@@ -149,20 +173,19 @@ installation for local development.
 2.  **Link the extension:**
 
     The `link` command creates a symbolic link from the Gemini CLI extensions
-    directory to your development directory. This means any changes you make
-    will be reflected immediately without needing to reinstall.
+    directory to your development directory. Changes you make are reflected
+    immediately.
 
     ```bash
     gemini extensions link .
     ```
 
-Now, restart your Gemini CLI session. The new `fetch_posts` tool will be
-available. You can test it by asking: "fetch posts".
+Restart your Gemini CLI session to use the new `fetch_posts` tool. Test it by
+asking: "fetch posts".
 
-## Step 4: Add a custom command
+## Step 5: Add a custom command
 
-Custom commands provide a way to create shortcuts for complex prompts. Let's add
-a command that searches for a pattern in your code.
+Custom commands create shortcuts for complex prompts.
 
 1.  Create a `commands` directory and a subdirectory for your command group:
 
@@ -181,18 +204,17 @@ a command that searches for a pattern in your code.
     """
     ```
 
-    This command, `/fs:grep-code`, will take an argument, run the `grep` shell
-    command with it, and pipe the results into a prompt for summarization.
+    This command, `/fs:grep-code`, takes an argument, runs the `grep` shell
+    command, and pipes the results into a prompt for summarization.
 
-After saving the file, restart the Gemini CLI. You can now run
-`/fs:grep-code "some pattern"` to use your new command.
+After saving the file, restart Gemini CLI. Run `/fs:grep-code "some pattern"` to
+use your new command.
 
-## Step 5: Add a custom `GEMINI.md`
+## Step 6: Add a custom `GEMINI.md`
 
-You can provide persistent context to the model by adding a `GEMINI.md` file to
-your extension. This is useful for giving the model instructions on how to
-behave or information about your extension's tools. Note that you may not always
-need this for extensions built to expose commands and prompts.
+Provide persistent context to the model by adding a `GEMINI.md` file to your
+extension. This is useful for setting behavior or providing essential tool
+information.
 
 1.  Create a file named `GEMINI.md` in the root of your extension directory:
 
@@ -203,7 +225,7 @@ need this for extensions built to expose commands and prompts.
     posts, use the `fetch_posts` tool. Be concise in your responses.
     ```
 
-2.  Update your `gemini-extension.json` to tell the CLI to load this file:
+2.  Update your `gemini-extension.json` to load this file:
 
     ```json
     {
@@ -220,14 +242,13 @@ need this for extensions built to expose commands and prompts.
     }
     ```
 
-Restart the CLI again. The model will now have the context from your `GEMINI.md`
-file in every session where the extension is active.
+Restart Gemini CLI. The model now has the context from your `GEMINI.md` file in
+every session where the extension is active.
 
-## (Optional) Step 6: Add an Agent Skill
+## (Optional) Step 7: Add an Agent Skill
 
-[Agent Skills](../cli/skills.md) let you bundle specialized expertise and
-procedural workflows. Unlike `GEMINI.md`, which provides persistent context,
-skills are activated only when needed, saving context tokens.
+[Agent Skills](../cli/skills.md) bundle specialized expertise and workflows.
+Skills are activated only when needed, which saves context tokens.
 
 1.  Create a `skills` directory and a subdirectory for your skill:
 
@@ -254,28 +275,18 @@ skills are activated only when needed, saving context tokens.
     3. Suggest remediation steps for any findings.
     ```
 
-Skills bundled with your extension are automatically discovered and can be
-activated by the model during a session when it identifies a relevant task.
-
-## Step 7: Release your extension
-
-Once you're happy with your extension, you can share it with others. The two
-primary ways of releasing extensions are via a Git repository or through GitHub
-Releases. Using a public Git repository is the simplest method.
-
-For detailed instructions on both methods, please refer to the
-[Extension Releasing Guide](./releasing.md).
+Gemini CLI automatically discovers skills bundled with your extension. The model
+activates them when it identifies a relevant task.
 
-## Conclusion
+## Step 8: Release your extension
 
-You've successfully created a Gemini CLI extension! You learned how to:
+When your extension is ready, share it with others via a Git repository or
+GitHub Releases. Refer to the [Extension Releasing Guide](./releasing.md) for
+detailed instructions and learn how to list your extension in the gallery.
 
-- Bootstrap a new extension from a template.
-- Add custom tools with an MCP server.
-- Create convenient custom commands.
-- Provide persistent context to the model.
-- Bundle specialized Agent Skills.
-- Link your extension for local development.
+## Next steps
 
-From here, you can explore more advanced features and build powerful new
-capabilities into the Gemini CLI.
+- [Extension reference](reference.md): Deeply understand the extension format,
+  commands, and configuration.
+- [Best practices](best-practices.md): Learn strategies for building great
+  extensions.