Update README.md to show usage and list tools more clearly (#44)

Update README based on DevRel and product bug bash feedback

Author: twerske

README.md

@@ -2,101 +2,125 @@
 
 Help Gemini CLI create, build, test, and run Flutter apps.
 
-## Status: Experimental
+*   **Status: Experimental** - This is an experimental project. Features and commands may change drastically. We welcome your feedback!
 
-This is an experimental repository, which means the things will change
-(sometimes drastically). Feedback very welcome!
+## ✨ Features
 
-## Contribute
+-   **🚀 Project Bootstrapping**: Create new Flutter projects from scratch with built-in best practices, including linters, documentation, and design planning.
+-   **🔧 Guided Refactoring**: Execute complex refactoring tasks with automated planning, git branch management, and step-by-step implementation guides for your approval.
+-   **✅ Automated Pre-Commit Checks**: Automatically format, analyze, and test your code before committing to maintain codebase quality.
+-   **✍️ Smart Commit Messaging**: Generate descriptive, conventional commit messages based on your staged changes.
+-   **🧠 Context Priming**: Initializes Gemini with specific rules and context for Dart and Flutter, ensuring high-quality, idiomatic code generation.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md)
+## 📋 Prerequisites
 
-## Installation
+1.  **Gemini CLI 0.4.0+** installed and configured.
+2.  **Flutter & Dart SDK** installed on your system.
+3.  **Git** installed and available in your PATH.
 
-First, make sure you are using Gemini CLI 0.4.0 or greater. You can check your
-version of Gemini CLI this way: `gemini --version`.
+## 🚀 Installation
 
-Now install the extension:
+### 1. Install from GitHub
 
-```shell-command
+Use the `gemini extensions install` command to install directly from the source repository:
+
+```bash
 gemini extensions install --source https://github.com/gemini-cli-extensions/flutter.git
 ```
 
-Once installed, run this to update it:
+You can manage the extension with the following commands:
 
-```shell-command
+```bash
+# Update to the latest version
 gemini extensions update flutter
+
+# Uninstall the extension
+gemini extensions uninstall flutter
 ```
 
-To uninstall it:
+### 2. Available Commands
 
-```shell-command
-gemini extensions uninstall flutter
+The new commands will be available in new Gemini CLI sessions. The following commands will be available (with or without the `flutter:` prefix):
+
+-   `/start` - Primes Gemini with the rules and context for Flutter development.
+-   `/create-app` - Guides you through bootstrapping a new Flutter project with best practices.
+-   `/refactor` - Manages a structured refactoring session with automated planning.
+-   `/commit` - Automates pre-commit checks and generates a descriptive commit message.
+
+## 💡 Usage
+
+This extension provides powerful commands to automate key phases of the development lifecycle.
+
+### `/start`
+
+Initializes Gemini with the proper context for Flutter development. It summarizes the coding guidelines, documentation rules, and available tools. **Use this command at the beginning of a session.**
+
+```bash
+/start # Initialize context to start a session
+/start What were we last doing in this app? # Start a session and pick up where you left off
 ```
 
-## Rules
+### `/create-app`
 
-The [flutter.md](./flutter.md) file contains rules for writing Dart and Flutter
-code. Some are very opinionated, so you should probably review them and make
-sure they agree with your style.
+Initiates a guided process to bootstrap a new Flutter application, ensuring your project starts with a solid foundation.
 
-The [override](./override) file contains certain important rules that are
-appended to the end of all of Gemini's rules so that they have more weight.
+**Process:**
+1.  Asks for the package's purpose, details, and desired location on your filesystem.
+2.  Creates a new Flutter project with recommended settings and linter rules.
+3.  Generates starter `pubspec.yaml`, `README.md`, and `CHANGELOG.md` files.
+4.  Produces a `DESIGN.md` and `IMPLEMENTATION.md` for your review and approval before any code is written.
 
-## Available Commands
+```bash
+/create-app I want to create a trip planning app
+```
 
-This extension adds some commands, all of which can be run with or without the
-"flutter:" prefix (as long as there isn't a name collision with another
-extension).
+### `/refactor`
 
-### `/start` (or `/flutter:start` if you have more than one start command)
+Starts a structured session to refactor existing code. It helps you plan and execute changes safely and efficiently.
 
-Initializes Gemini CLI to work on Dart and Flutter code. It will summarize the
-coding guidelines, documentation rules, and the tools it has available for
-Dart and Flutter
-development. Use this command at the beginning of a session to ensure Gemini CLI
-is primed with the correct context.
+**Process:**
+1.  Asks for your high-level refactoring goals and what you want to accomplish.
+2.  Offers to create a new `git` branch for the refactoring work, isolating changes.
+3.  Generates a `REFACTOR.md` design document detailing the proposed changes.
+4.  Creates a phased `REFACTOR_IMPLEMENTATION.md` plan for your review and approval.
 
-### `/create-app` (or `/flutter:create-app` if you have more than one create-app command)
+```bash
+/refactor
+```
 
-Starts the process of creating a new Flutter app. Gemini CLI will:
+### `/commit`
 
-1. Ask for the package's purpose, details, and location.
-2. Create a new project with recommended settings, including linter rules.
-3. Set up the initial `pubspec.yaml`, `README.md`, and `CHANGELOG.md`.
-4. Create a detailed `DESIGN.md` and `IMPLEMENTATION.md` for your review and
-   approval before writing code.
+Prepares your staged `git` changes for a clean, high-quality commit. It acts as an automated pre-commit hook and message generator.
+
+**Process:**
+1.  Runs `dart fix` and `dart format` to clean and format your code.
+2.  Executes the Dart analyzer to check for static analysis issues.
+3.  Runs your project's test suite to ensure all tests are passing.
+4.  Generates a descriptive commit message based on the staged changes for you to review, edit, and approve.
+
+```bash
+/commit
+```
 
-This command is ideal for bootstrapping a new project with best practices from
-the start.
+## ⚙️ Coding Guidelines
 
-### `/refactor` (or `/flutter:refactor` if you have more than one refactor command)
+This extension enforces a specific set of coding standards to ensure consistency and quality. These rules are defined in the extension's repository:
 
-Initiates a guided refactoring session for existing code. Gemini CLI will:
+-   **`flutter.md`**: Contains rules and best practices for writing Dart and Flutter code. These rules are opinionated, and we encourage you to review them to ensure they align with your style.
+-   **`override`**: Contains important, high-priority rules that are appended to the end of all prompts to ensure they have the most weight.
 
-1. Ask for the refactoring goals and what you want to accomplish.
-2. Offer to create a new branch for the refactoring work.
-3. Generate a `REFACTOR.md` design document outlining the proposed changes.
-4. Create a detailed, phased `REFACTOR_IMPLEMENTATION.md` plan for your review
-   and approval.
+## 🐛 Troubleshooting
 
-This command helps structure complex refactoring tasks, ensuring they are
-well-planned and executed.
+### Common Issues
 
-### `/commit` (or `/flutter:commit` if you have more than one commit command)
+1.  **"Command not recognized"**: Ensure the extension is installed correctly and you have restarted the Gemini CLI. Verify the installation with `gemini extensions list`.
 
-Prepares your current changes for a git commit. Gemini CLI will:
+2.  **"Gemini CLI version error"**: This extension requires Gemini CLI version 0.4.0 or greater. Check your version with `gemini --version` and update if necessary.
 
-1. Run `dart fix` and `dart format` to clean up the code.
-2. Run the analyzer to check for any issues.
-3. Run tests to ensure everything is passing.
-4. Generate a descriptive commit message based on the changes for you to review
-   and approve.
+### Filing Issues
 
-This command helps maintain code quality and consistency in your commit history.
+If you have feedback, suggestions, or run into issues, please [file an issue on GitHub](https://github.com/flutter/gemini-cli-extension/issues/new/choose).
 
-## Filing Issues
+## 🤝 Contributing
 
-If you have feedback, suggestions, or run into issues using the extension,
-please file an issue at
-https://github.com/flutter/gemini-cli-extension/issues/new/choose
+Contributions are welcome! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) guide for more details on how to get started.