chore(alpha update command): add option to use ai with gh models

Assisted-by: ChatGPT (OpenAI)

Co-authored-by: Vitor Floriano <vitorfloriano@users.noreply.github.com>

Author: camilamacedo86

docs/book/src/plugins/available/autoupdate-v1-alpha.md

@@ -11,10 +11,12 @@ refresh your project scaffold, and wraps it in a GitHub Actions workflow that op
 
 - When you don’t deviate too much from the default scaffold — ensure that you see the note about customization [here](https://book.kubebuilder.io/versions_compatibility_supportability#project-customizations).
 - When you want to reduce the burden of keeping the project updated and well-maintained.
+- When you want to guidance and help from AI to know what changes are needed to keep your project up to date
+as to solve conflicts.
 
 ## How to Use It
 
-0 If you want to add the `autoupdate` plugin to your project:
+- If you want to add the `autoupdate` plugin to your project:
 
 ```shell
 kubebuilder edit --plugins="autoupdate.kubebuilder.io/v1-alpha"
@@ -34,6 +36,11 @@ Pull Request compare link so you can create the PR and review it, such as:
 
 <img width="638" height="482" alt="Example Issue" src="https://github.com/user-attachments/assets/589fd16b-7709-4cd5-b169-fd53d69790d4" />
 
+More over AI models will be used to help you understand what changes are needed to keep your project up to date
+as to solve conflicts if any be faced, such as in the following example:
+
+<img width="447" height="716" alt="Example AI summary" src="https://github.com/user-attachments/assets/fc553ee1-5149-48cb-9f76-2c1cd2587f6b" />
+
 The workflow will check once a week for new releases, and if there are any, it will create an Issue with a Pull Request compare link so you can create the PR and review it.
 The command called by the workflow is:
 
@@ -45,12 +52,14 @@ The command called by the workflow is:
 		# --force: Completes the merge even if conflicts occur, leaving conflict markers.
 		# --push: Automatically pushes the resulting output branch to the 'origin' remote.
 		# --restore-path: Preserves specified paths (e.g., CI workflow files) when squashing.
-		# --open-gh-issue: Creates a GitHub issue with a link to the generated PR for review.
+		# --open-gh-models: Adds an AI-generated comment to the created Issue with
+		#   a short overview of the scaffold changes and conflict-resolution guidance (If Any).
         kubebuilder alpha update \
           --force \
           --push \
           --restore-path .github/workflows \
-          --open-gh-issue
+          --open-gh-issue \
+          --use-gh-models
 ```
 
 <aside class="warning">

docs/book/src/reference/commands/alpha_update.md

@@ -17,6 +17,9 @@ You can reduce the burden of keeping your project up to date by using the
 automates the process of running `kubebuilder alpha update` on a schedule
 workflow when new Kubebuilder releases are available.
 
+Moreover, you will be able to get help from AI models to understand what changes are needed to keep your project up to date
+and how to solve conflicts if any be faced.
+
 </aside>
 
 ## When to Use It
@@ -27,6 +30,7 @@ Use this command when you:
 - Prefer automation over manual file editing
 - Want to review scaffold changes on a separate branch
 - Want to focus on resolving merge conflicts (not re-applying your custom code)
+- Want an **AI-generated** overview of changes and guidance for resolving conflicts
 
 ## How It Works
 
@@ -64,6 +68,9 @@ The command creates three temporary branches:
     - `--output-branch`: pick a custom branch name.
     - `--push`: push the result to `origin` automatically.
     - `--git-config`: sets git configurations.
+    - `--open-gh-issue`: create a GitHub issue with a checklist and compare link (requires `gh`).
+    - `--use-gh-models[=<model>]`: add an AI overview **comment** to that issue using `gh models`
+    (requires the `gh-models` extension). If used without a value, default
 
 ### Step 5: Cleanup
 - Once the output branch is ready, all the temporary working branches are deleted.
@@ -143,7 +150,32 @@ make manifests generate fmt vet lint-fix
 make all
 ```
 
-### Changing Extra Git configs only during the run (does not change your ~/.gitconfig)_
+## Using with GitHub Issues (`--open-gh-issue`) and AI (`--use-gh-models`) assistance
+
+If you pass `--open-gh-issue`, the command creates an issue in your repository with a pre-filled checklist and a compare link so you can open a PR and review the update.
+
+If you also pass `--use-gh-models[=<model>]`, the tool posts a follow-up comment on that issue with an AI-generated overview of the most important changes and brief conflict-resolution guidance. When the flag is provided without a value, the default model is `openai/gpt-4o`. The AI comment uses simple, Kubebuilder-style wording and, when relevant, adds a short **Conflicts** section with commands to regenerate files. *(If the `gh models` command isn’t available, the issue is still created; only the AI comment is skipped.)*
+
+This integrates cleanly with automation. The [`autoupdate.kubebuilder.io/v1-alpha`][autoupdate-plugin] plugin can scaffold a GitHub Actions workflow that runs the command on a schedule (e.g., weekly). When a new Kubebuilder release is available, it opens an issue with a compare link so you can create the PR and review it, for example:
+
+<img width="638" height="482" alt="Example Issue" src="https://github.com/user-attachments/assets/589fd16b-7709-4cd5-b169-fd53d69790d4" />
+
+With `--use-gh-models`, an AI comment helps you understand key changes and how to resolve conflicts (e.g., which files to regenerate and which commands to run), for example:
+
+<img width="447" height="716" alt="Example AI summary" src="https://github.com/user-attachments/assets/fc553ee1-5149-48cb-9f76-2c1cd2587f6b" />
+
+```
+# Create an issue after the update
+kubebuilder alpha update --open-gh-issue
+
+# Create an issue and add an AI overview comment (default model)
+kubebuilder alpha update --open-gh-issue --use-gh-models
+
+# Create an issue and add an AI overview comment with a specific model
+kubebuilder alpha update --open-gh-issue --use-gh-models openai/gpt-4o-mini
+```
+
+## Changing Extra Git configs only during the run (does not change your ~/.gitconfig)_
 
 By default, `kubebuilder alpha update` applies safe Git configs:
 `merge.renameLimit=999999`, `diff.renameLimit=999999`.
@@ -171,18 +203,20 @@ kubebuilder alpha update \
 
 ## Flags
 
-| Flag               | Description                                                                                                                                                                                                                            |
-|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `--from-version`   | Kubebuilder release to update **from** (e.g., `v4.6.0`). If unset, read from the `PROJECT` file when possible.                                                                                                                         |
-| `--to-version`     | Kubebuilder release to update **to** (e.g., `v4.7.0`). If unset, defaults to the latest available release.                                                                                                                             |
-| `--from-branch`    | Git branch that holds your current project code. Defaults to `main`.                                                                                                                                                                   |
-| `--force`          | Continue even if merge conflicts happen. Conflicted files are committed with conflict markers (CI/cron friendly).                                                                                                                      |
-| `--show-commits`   | Keep full history (do not squash). **Not compatible** with `--preserve-path`.                                                                                                                                                          |
-| `--restore-path`   | Repeatable. Paths to preserve from the base branch (repeatable). Not supported with --show-commits. (e.g., `.github/workflows`).                                                                                                       |
-| `--output-branch`  | Name of the output branch. Default: `kubebuilder-update-from-<from-version>-to-<to-version>`.                                                                                                                                          |
-| `--push`           | Push the output branch to the `origin` remote after the update completes.                                                                                                                                                              |
-| `--git-config`     | Repeatable. Pass per-invocation Git config as `-c key=value`. **Default** (if omitted): `-c merge.renameLimit=999999 -c diff.renameLimit=999999`. Your configs are applied on top. To disable defaults, include `--git-config disable` |
-| `-h, --help`       | Show help for this command.                                                                                                                                                                                                            |
+| Flag               | Description                                                                                                                                                                                                                                      |
+|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--force`          | Continue even if merge conflicts happen. Conflicted files are committed with conflict markers (CI/cron friendly).                                                                                                                                |
+| `--from-branch`    | Git branch that holds your current project code. Defaults to `main`.                                                                                                                                                                             |
+| `--from-version`   | Kubebuilder release to update **from** (e.g., `v4.6.0`). If unset, read from the `PROJECT` file when possible.                                                                                                                                   |
+| `--git-config`     | Repeatable. Pass per-invocation Git config as `-c key=value`. **Default** (if omitted): `-c merge.renameLimit=999999 -c diff.renameLimit=999999`. Your configs are applied on top. To disable defaults, include `--git-config disable`.          |
+| `--open-gh-issue`  | Create a GitHub issue with a pre-filled checklist and compare link after the update completes (requires `gh`).                                                                                                                                   |
+| `--output-branch`  | Name of the output branch. Default: `kubebuilder-update-from-<from-version>-to-<to-version>`.                                                                                                                                                    |
+| `--push`           | Push the output branch to the `origin` remote after the update completes.                                                                                                                                                                        |
+| `--restore-path`   | Repeatable. Paths to preserve from the base branch when squashing (e.g., `.github/workflows`). **Not supported** with `--show-commits`.                                                                                                          |
+| `--show-commits`   | Keep full history (do not squash). **Not compatible** with `--restore-path`.                                                                                                                                                                     |
+| `--to-version`     | Kubebuilder release to update **to** (e.g., `v4.7.0`). If unset, defaults to the latest available release.                                                                                                                                       |
+| `--use-gh-models`  | Post an AI overview as an issue comment using `gh models`. Provide a model name; if the flag is used without a value it defaults to `openai/gpt-4o`. Requires `gh` + `gh-models` extension. Effective only when `--open-gh-issue` is also set.   |
+| `-h, --help`       | Show help for this command.                                                                                                                                                                                                                      |
 
 <aside class="note warning">
 <h1>You might need to upgrade your project first</h1>