Agent-Started Trials: Document mirrord operator uninstall

[iniw]

Problem

Documents COR-1970 and COR-1969 for the Agent-Started Trials page that #396 adds, so this PR is based on its branch.

The mirrord PRs metalbear-co/mirrord#4989 and metalbear-co/mirrord#4990 change mirrord operator install and add mirrord operator uninstall:

• --context installs into a different kubecontext.
• In a terminal, the command asks to confirm the kubecontext and the namespace before it starts a trial or changes the cluster. --yes skips the question, and it does not ask without a terminal.
• mirrord operator uninstall removes what the installation created, also after an installation that failed half-way.
• After a failed trial installation, retrying with --api-key alone fails, because the failed installation left objects behind. The command now prints two steps: mirrord operator uninstall, then mirrord operator install --api-key <key>.

The page also says that the command sends the name of the current kubecontext as the cluster hint. It sends the cluster ID (the UID of the default namespace), because a kubecontext name can contain account details, for example the AWS account ID in an EKS context name.

Change

• "What the agent does" mentions --context, the confirmation prompt and --yes, the new retry steps, the cluster ID as the default cluster hint, and that the "already installed" and "leftover objects" errors point to mirrord operator uninstall.
• A new section, "Removing the Operator", explains mirrord operator uninstall: it lets the Operator end its sessions first, then deletes everything the installation created, including the CRDs and so the mirrord policies and profiles. It takes --context and --yes too. An installation that was moved to Helm is removed with helm uninstall.

This must not merge before a mirrord release that has #4989 and #4990.

Testing

I checked each statement against the CLI code in the mirrord PRs, and I ran the commands on a kind cluster while I tested those PRs.

[linear-code]

COR-1969

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can show, collapse, or hide each part of a finding: code, evidence, and all

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

PR Summary by Qodo

Document Operator uninstall and agent-started trial recovery

📝 Documentation 🕐 10-20 Minutes

AI Description

• Document context selection, confirmation, and the cluster ID used as the trial hint.
• Explain how to uninstall a partial installation and retry with the existing trial key.
• Clarify uninstall's effects on sessions, policies, and profiles, plus the Helm-managed exception.

Diagram

graph TD
  A["Install command"] --> B["Trial signup"] --> C["Operator deployment"]
  C -->|"failure or removal"| D["Uninstall command"] --> E["End sessions"] --> F["Delete resources"] --> G["Retry with key"]
  G -->|"reuse trial"| C

Loading

High-Level Assessment

Keep the guidance on the agent-started trials page: uninstall is both the recovery step for a failed trial installation and the cleanup path for the installation this page describes. A separate page would split that workflow without adding a distinct audience.

Files changed (1) +18 / -4

Documentation (1) +18 / -4

agent-started-trials.mdExplain Operator uninstall and trial installation recovery +18/-4

Explain Operator uninstall and trial installation recovery

• Documents context selection, confirmation behavior, the cluster ID used as the default hint, and the uninstall-then-retry steps after a failed installation. Adds a removal section covering session shutdown, deletion of CRDs and their policies and profiles, and the need to use Helm for installations moved to Helm management.

docs/using-mirrord-with-ai/agent-started-trials.md

[greptile-apps]

[Low risk] Documents agent-started trial workflow and operator commands.

The PR should not merge until its retry guidance preserves the selected kubecontext, in addition to the stated mirrord release prerequisite.

Findings

1.  Retry loses the selected context ▶
2.  Stopped installs print no retry steps ▶
3.  Cluster hint is not guaranteed ▶

Fix with agent prompt

### Issue 1
docs/using-mirrord-with-ai/agent-started-trials.md:23
**Retry loses the selected context.** If the first install uses `--context` to target another cluster, these retry commands omit it. Following them can leave the partial installation in that cluster and run cleanup or installation against the current kubecontext instead. Show how to pass the same context to both steps. Greptile automatically discovered a related ticket stating that `--context` selects the cluster for install and uninstall, which informed this comment.

### Issue 2
docs/using-mirrord-with-ai/agent-started-trials.md:23
**Stopped installs print no retry steps.** The [install implementation](https://github.com/metalbear-co/mirrord/blob/HEAD/mirrord/cli/src/operator/install.rs) prints retry instructions only when installation returns an error. If the process is stopped after signup, the agent has the trial details but not the promised cleanup and retry steps. State those steps in the guide for interrupted installs.

### Issue 3
docs/using-mirrord-with-ai/agent-started-trials.md:25
**Cluster hint is not guaranteed.** The [CLI lookup](https://github.com/metalbear-co/mirrord/blob/HEAD/mirrord/cli/src/operator/install/cluster.rs) returns no cluster ID if it cannot read the `default` namespace or its UID; signup then proceeds without a hint. Qualify this statement so users do not rely on the claim page identifying their cluster in that case.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

This PR extends the agent-started trials guide with context selection, confirmation, retry guidance, and Operator removal.

• The retry examples need to retain an explicitly selected kubecontext.
• The interruption and default cluster-hint descriptions promise behavior the available install implementation does not guarantee.
• Greptile automatically discovered a related ticket that helped explain the purpose of this PR: adding Operator uninstall and recovery after partial installations.

_{Reviews (1) · Last reviewed commit: "Agent-Started Trials: Document `mirrord ..."}