> ## Documentation Index > Fetch the complete documentation index at: https://docs.withgauge.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For API and SDK launches, integration testing, and ongoing coding-agent checks, start with Gauge Agents: > - [Gauge Agents overview](https://docs.withgauge.com/agents/index.md) > - [Gauge Agents quickstart](https://docs.withgauge.com/agents/quickstart.md) > - [Create and inspect an eval](https://docs.withgauge.com/agents/guides/create-an-eval-and-run-an-experiment.md) > - [Agent Experience: diagnose integration failures](https://docs.withgauge.com/agents/concepts/agent-experience.md) > - [Agent Preference: measure product selection](https://docs.withgauge.com/agents/concepts/agent-preference.md) > - [GitHub PR checks](https://docs.withgauge.com/agents/guides/github-pr-checks.md) > For AI search visibility and AEO, start with [Gauge Chat](https://docs.withgauge.com/introduction/welcome.md). # Improve agent preference > Change what agents read when they choose a product—your home page, pricing, llms.txt, and docs—and rerun their sessions to see if they choose you. [Agent Preference](https://docs.withgauge.com/agents/concepts/agent-preference.md) shows which products agents choose and why. When an agent passes on your product, it gives a reason: an **objection**. An optimization tests whether a change to the pages agents read during research answers that objection. Gauge reruns the same preference sessions with your edits in place and analyzes the reruns. Each original objection comes back **resolved** or **returned**, and new ones show as **introduced**. Nothing deploys. The result is a diff and a summary that you apply through your usual review process. To fix problems agents hit while they use your product, see [Improve agent experience](https://docs.withgauge.com/agents/guides/improve-agent-experience.md). ## What you can change Agents decide from the pages they read while they research. An optimization can edit any page a session fetched, or add a new one: | Page | Common objections it can answer | | - | - | | Home page | Unclear what the product does, or who it is for. | | Pricing page | No free tier, unclear limits, or pricing the agent could not find. | | `llms.txt` | No summary for agents, or no links to the pages that matter. | | Docs pages | A missing integration, framework, or feature, or no quickstart. | Each page is a `page:` file in the optimization's **tree**. Anything not in the tree reruns as the session had it. You can also change a Skill (`skill:`) if the sessions staged one. ## Choose what to improve A **finding** is one reason in one session. An **issue** is the same finding across many sessions. The web app lists issues as themes on the **Findings** tab of Agent Preference. Start with the objections that cost you the most sessions. Each objection shows where agents went instead. Read the findings and their evidence before you name a cause. An agent that chose a competitor because it never found your pricing page needs a different fix than one that read the page and found no free tier. Check what the agents actually read. If they never reached your site, an edit to your pages cannot change the result. You can test an edit to a third-party page, such as a comparison article, as a what-if. You cannot ship that change. ## Start an optimization Click **Optimize** in any of these places: * A theme on the **Findings** tab of Agent Preference. The optimization reruns up to 12 of the theme's most recent sessions. * A finding on a run page. The optimization reruns that session. * The **Optimizations** page, under **Start a new optimization**. Choose a theme on the **Objections** tab. Starting an optimization launches nothing and uses no credits. ## Work with Ask Gauge The optimization opens in an Ask Gauge chat. Tell it what to focus on or which sessions to skip, or reply "start". Ask Gauge works in stages and ends each turn with one question about the next step: 1. **Diagnose and edit.** It reads the objections and the pages the agents fetched before they chose. It says which pages carried the decision and which you own, then edits copies of them. 2. **Rerun.** It asks before every launch, even in auto mode. Reruns use credits like any run. 3. **Read.** Gauge wakes the chat as reruns finish. Ask Gauge compares the findings and updates its notes. 4. **Finish.** It records the result. Reply "yes" to approve the step it names, or type a reply to steer it. The panel beside the chat has three tabs: * **Changes** shows each changed page with its diff against the original. * **Coding Sessions** lists the reruns. Open one to see where it read your change. * **Agent scratchpad** holds the diagnosis, each edit and why, and what each rerun showed. ## Run the loop from the CLI > [!NOTE] > > These CLI commands use hosted Gauge. The CLI uses the local backend by > default, so set hosted once after you sign in, or add `--hosted` to each > command. See [Choose a backend](https://docs.withgauge.com/agents/guides/cli.md#choose-a-backend). > > ```bash theme={null} > gauge config set backend hosted > ``` Find objections and their findings: ```bash theme={null} gauge issues list --type objection # most sessions first gauge issues get # the issue's findings and runs ``` Create an optimization and read its authoring guidance: ```bash theme={null} gauge optimizations create --issue gauge optimizations authoring ``` To start from one finding, pass `--finding --run `; `gauge run insight ` shows finding IDs and the agent's product choices. To start from a goal with no source sessions, pass `--goal ""`. See which pages the agent read and searched for before it chose: ```bash theme={null} gauge run web # every URL the agent fetched, and its searches gauge run trace --seq # events around a finding's evidence seq ``` ### Edit the tree Copy each page into the tree before you edit it, so the diff shows only your change. Gauge copies the version the session read, or the live page if no session read it: ```bash theme={null} gauge optimizations file add --page https://acme.dev/pricing gauge optimizations file read page:https://acme.dev/pricing --text gauge optimizations file read page:https://acme.dev/pricing --query "Free" gauge optimizations file edit --page https://acme.dev/pricing --edits edits.json ``` `edits.json` is a list of `{"find": "...", "replace": "..."}` on the page's exact source. Copy the find text from `file read --query`. Each find must match once, and all edits apply or none do. The output shows how much of the page you kept. For a new page or a full rewrite, write the complete body. For example, to add an `llms.txt`: ```bash theme={null} gauge optimizations file write --page https://acme.dev/llms.txt \ --content-type text/plain --from llms.txt ``` Read a page before you change it, keep its purpose, and source every new fact. A claim your product does not support can win the rerun and still mislead real agents. To drop a page from the tree, use `file rm `. Keep your diagnosis, plan, and each launch's result in the optimization's notes: ```bash theme={null} gauge optimizations notes --from notes.md ``` ### Rerun and compare ```bash theme={null} gauge optimizations launch # asks first; --run reruns a subset gauge optimizations watch ``` A launch reruns each source session with the same prompt, scenario, agent, model, and settings, plus your tree. It lists the changed pages; check that every edit you meant to test is there. Rerun only the sessions your edits address. Pass `--yes` only for a launch that is already approved. `watch` waits until every rerun finishes and is analyzed. It then shows each source objection as resolved or returned, and new findings as introduced. To read a launch again, use `gauge optimizations launches `. Before you credit an edit, run `gauge run web ` to confirm the rerun read the changed page. Then check what the rerun chose with `gauge run insight `. An objection can resolve while the agent still picks a competitor for another reason. Agents choose differently from run to run, so do not trust one rerun. Edit and launch again in the same optimization until the objection resolves. ### Finish ```bash theme={null} gauge optimizations finish --from result.json ``` `result.json` is `{summary, changed, resolved, returned, introduced}`: a PR-style summary, the changed tree keys, and the findings in each group as `{runId, label}`. After you finish, the tree can no longer change. For a coding agent, `gauge instructions issues` and `gauge instructions optimization` describe the full workflow. ## Ship the change In the web app, click **Copy for agent**. It copies the changes and evidence as a prompt for your coding agent, which applies them where your site's files live. Review and publish the change through your usual process. After you publish, run the preference prompt again against the live site. Agent Preference results vary between runs, so compare enough sessions across the agents and models you care about. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.