@grepr/cli 1.11.5-de00b67 → 1.11.5-df90175

package/build/dist/docs-index/3c925c59-0717-4d5b-9b6f-4bdecaed390c.txt

@@ -0,0 +1,136 @@
+Control what a Grepr AI agent can reach with a service account, tools, skills, and MCP integrations, and whether its pipeline changes need approval.
+
+# Control what an AI agent can do
+
+An agent's reach is bounded in layers, and a capability has to be allowed by every layer to work:
+
+1. The **service account** the agent acts as. Its roles are the outer boundary and cap everything the agent can reach in Grepr.
+2. The **tools and skills** you enable. These narrow the agent to specific operations within what the service account permits.
+3. The **MCP integrations** you enable, and the tools you allow on each. These decide what the agent can reach in other systems.
+
+A fourth setting, the change approval mode, decides whether the agent can make automatic changes to your pipeline.
+
+These settings are on the agent's **Capabilities** step, and on the matching step of the create wizard.
+
+## Choose the service account an agent acts as \[#service-account]
+
+Every call an agent makes to Grepr authenticates as the service account you select in the **Service account** field. The service account's roles decide which pipelines, datasets, and integrations the agent can read and write to.
+
+The service account is the boundary that holds even if a tool grant is over-permissive. An agent with the pipeline editing tool but a service account that can only view jobs cannot change a pipeline. Grant the narrowest role that lets the agent finish its job. To create one, see [_](/admin/service-accounts).
+
+If the **Service account** menu is empty, create a service account before you continue.
+
+## What every agent can already do \[#sandbox-baseline]
+
+Each investigation runs in its own sandbox, and inside that sandbox an agent can:
+
+* Run shell commands.
+* Run Python for local analysis and scripting.
+* Query files it downloaded with DuckDB.
+* Read, create, and edit files in its own workspace.
+
+These are part of the sandbox and cannot be turned off. They act only on the sandbox, which is discarded when the investigation ends, so they do not reach your data or your pipelines. Everything that does reach Grepr is granted separately, as described next.
+
+## Grant access to Grepr with tools and skills \[#grepr-access]
+
+The **Grepr access** section is where you decide what the agent can do. You grant access in two ways, and most agents use both:
+
+* Enable a skill, which gives the agent guidance for a task and, when the skill needs them, the tools that task requires.
+* Pin an individual tool, which grants that tool with no accompanying guidance.
+
+Prefer skills. A skill tells the agent how to use what it grants, so an agent with a skill usually needs fewer turns than one holding the bare tool. Pin a tool when you want a capability that no skill attached covers.
+
+### Abilities and reference skills \[#skill-kinds]
+
+Skills are grouped by whether enabling one is a permission decision:
+
+* **Abilities** carry tools. Enabling one grants the agent the operations that skill needs, so treat it as granting access.
+* **Reference** skills carry only knowledge. Enabling one changes what the agent knows, never what it can do, so it is safe to enable freely.
+
+To read what a skill covers and what it grants before you enable it, open its detail from the selector. To learn what skills exist and how to write your own, see [_](/ai-agents/skills).
+
+### How much a skill grants \[#grant-scope]
+
+How wide a skill's grant is depends on its scope, and the difference matters when you are reasoning about least privilege:
+
+* A **platform skill**, which Grepr maintains, grants exactly the operations its definition lists. A skill that needs only to preview a pipeline change gets the preview operation and not the one that applies it.
+* An **organization skill**, which you create, grants the whole *tool family* behind each tool you approve on it, meaning every operation that tool covers rather than only the ones the skill uses. Approving the pipeline editing tool on your own skill grants everything that tool covers, not only the part your instructions use.
+
+So an organization skill is as broad as the tools you approve on it. To keep a grant narrow, approve fewer tools on the skill rather than relying on the skill's instructions to limit the agent.
+
+Enabling a tool directly always grants its whole family, the same way an organization skill does.
+
+### Tool reference \[#tool-table]
+
+| Tool | What it lets the agent do |
+| --- | --- |
+| `query_logs` | Query the logs in your Grepr datasets. |
+| `get_pipeline` | Read the configuration of your pipelines and templates. |
+| `edit_pipeline` | Propose a change to a pipeline's configuration, and preview a change before proposing it. |
+| `grok` | Build and test Grok parsers. |
+| `datasets` | List, read, and manage your Grepr datasets. |
+| `integrations` | List and read your Grepr integrations. |
+| `docs` | Search the Grepr documentation and validate SQL. |
+| `backfill` | Replay logs from the data lake to a vendor destination. |
+| `investigations` | Read agent configuration, past investigations, and their transcripts. |
+| `github_code` | Clone, edit, and publish source repositories. Requires an enabled GitHub MCP integration. |
+
+An agent's pipeline changes are scoped to a pipeline's Grok parsers and its SQL transforms, so granting the pipeline editing tool keeps the rest of the pipeline configuration out of the agent's reach. Both are add-only. An agent can add a Grok rule or add a SQL transform, and it cannot change or remove one that is already there, so its proposals accumulate alongside your configuration rather than rewriting it.
+
+A SQL transform an agent adds is a filter and nothing further. It reads the pipeline's logs and selects them unchanged against a single condition, so it cannot join, aggregate, read a dataset, register a function, or keep state. It routes the events it matches to the agent signal sink, which you configure yourself when you set the pipeline up. An agent can add routes to that sink, and it cannot create, change, or remove the sink. That limit is on what an agent adds by itself. A SQL output you route to the agent signal sink yourself carries no such restriction, so you can build the event an agent receives however you need. See [_](/ai-agents/subscriptions#agent-signal-sink).
+
+The tools an agent uses to record and search its memory are not in this list. They are granted by the agent's memory settings instead, so that turning memory on is the single decision that controls them. See [_](/ai-agents/memory).
+
+## Let an agent call an MCP server's tools \[#mcp-integrations]
+
+The **MCP integrations** section lists the MCP integrations in your organization and which of their tools the agent can use. Two agents can share one integration with different tool access enabled.
+
+Edit the integration's allowed tools and choose either every tool the server publishes or only the ones you select. Grepr reads the tool list from the server and marks each tool as read only or writing; for example, you can allow an agent to read incidents without allowing it to change them.
+
+Allowing every tool means the agent gains any tool the server adds later, which is convenient for a read-only server and worth avoiding for one that can make changes. Selecting individual tools keeps the enabled tools fixed until it is manually changed.
+
+Two rules apply to GitHub:
+
+* An agent can enable at most one GitHub MCP integration.
+* The `github_code` tool needs an enabled GitHub MCP integration, because that integration is how it reaches source code.
+
+To create an integration, see [_](/integrations/mcp).
+
+## Decide whether pipeline changes need approval \[#change-approval]
+
+An agent that decides a pipeline needs a configuration update does not edit it directly. It submits the change, and the **Pipeline changes** setting decides what happens next:
+
+| Mode | What happens when the agent proposes a change |
+| --- | --- |
+| **Require human approval** | Grepr records the change as a suggestion on the pipeline. Nothing changes until you review and apply it. |
+| **Auto-apply** | Grepr verifies the change and applies it. A running pipeline restarts to pick it up. No person is involved. |
+
+**Require human approval** is the default, and it is the right setting while you are learning how an agent behaves. Auto-apply an agent's changes only after its suggestions have consistently been ones you would have made yourself.
+
+Grepr enforces the mode at the operation level, so while an agent can always preview pipeline changes, it cannot bypass **Require human approval** to apply them.
+
+A change that lands on a running pipeline restarts it, which interrupts processing briefly.
+
+To review suggestions, see [_](/ai-agents/investigations#suggestions).
+
+## Frequently Asked Questions
+
+### How do I limit what a Grepr AI agent can reach?
+
+Reach is bounded in layers. The service account the agent acts as is the outer boundary and caps everything it can reach in Grepr. Within that, the tools and skills you enable narrow it to specific operations, and the MCP integrations you enable with their allowed tools decide what it can reach in other systems.
+
+### What can a Grepr AI agent do without any tools enabled?
+
+Inside its own sandbox it can always run shell commands and Python, query downloaded files with DuckDB, and read and write files in its workspace. These act only on the sandbox, which is discarded when the investigation ends, and they do not reach your data or pipelines.
+
+### What is the difference between an ability and a reference skill?
+
+An ability carries tools, so enabling one grants the agent the operations that skill needs and is a permission decision. A reference skill carries only knowledge, so enabling one changes what the agent knows but never what it can do.
+
+### Do platform skills and organization skills grant the same access?
+
+No. A platform skill grants exactly the operations its definition lists, which can be narrower than a whole tool. An organization skill grants the whole tool family behind each tool you approve on it, so keep its grant narrow by approving fewer tools.
+
+### Can a Grepr AI agent change my pipeline without approval?
+
+Only when you set its change approval mode to Auto-apply. The default, Require human approval, records every proposed change as a suggestion for you to review. Grepr enforces the mode server-side, so an agent has no route around it whatever its instructions say.

package/build/dist/docs-index/{7a5dda3d-e88b-4e96-adb3-358a18bc4ec0.txt → 3ffc53b9-367f-45f2-a7e8-e03618cd18d9.txt}

@@ -8,6 +8,8 @@ Before sending log data to the destination platform, Grepr uses machine learning
 
 Grepr supports popular observability platforms, including Datadog, Splunk, New Relic, Sumo Logic, Grafana Cloud, and OpenTelemetry-compatible platforms.
 
+Grepr AI agents build on the same data. An agent examines your logs and pipeline configuration with the capabilities you grant it and reports what it found. Start an investigation yourself, or connect an agent to a pipeline or another system so it investigates on its own. To learn more, see [_](/ai-agents).
+
 If you're just getting started with Grepr, follow the **Get started** guides below. If you're already using Grepr and need information on creating pipelines to process logs or to query raw logs stored in Grepr, see the guides under **Process and explore your logs**. If you need to automate your Grepr tasks or implement clients that use Grepr features, or use JavaScript to code reusable components for your pipelines, see the **Developers** documentation.
 
 ## Get started
@@ -24,6 +26,8 @@ If you're just getting started with Grepr, follow the **Get started** guides bel
 
 [Query logs in the data lake](/queries)
 
+[Grepr AI agents](/ai-agents)
+
 ## Developers
 
 [Use the Grepr Rest API](/apis)

package/build/dist/docs-index/{c2ebcb58-71da-491c-aafc-7503459394b8.txt → 44e0a0ea-df58-4668-8dc3-7669b1369ea3.txt}

@@ -10,6 +10,10 @@ An example of a pipeline is a log or trace reduction pipeline that reduces the v
 
 Trace reduction pipelines process the APM data produced by your applications and agents by applying configured transformations, sampling to create representative subsets of the data, and forwarding the results to your observability platform. Grepr uses a novel approach to identify and sample every path through your system. Sampling reduces the volume and cost of data sent to your observability platform, while the complete set of raw traces is retained in a Grepr data lake. If you use Datadog, you can also derive and forward metrics from your trace data to track trends across your traces without forwarding every trace. See [_](/pipelines/trace-pipelines).
 
+## AI agent signals and suggestions
+
+A log reduction pipeline can report each newly detected log pattern to your Grepr AI agents, so an agent investigates behavior that is new in your systems. An agent can also propose a change to the pipeline it investigated, such as a new Grok parser or an added SQL transform, which appears on the pipeline's **Suggestions** step for you to review and apply. To turn on signals, see [_](/transforms/reducer/configuration#agent-signals). To review a proposed change, see [_](/ai-agents/investigations#suggestions).
+
 ## Agent sessions pipelines
 
 Agent sessions pipelines process the telemetry produced by coding agents such as Claude Code, Codex, and OpenCode. A coding agent reports its conversation as OpenTelemetry log events and its execution as OpenTelemetry spans, and neither signal is readable as a session on its own. An agent sessions pipeline reads both signals, reconstructs each run into a single session, and stores it in a Grepr data lake, so you can read the transcript, measure the tokens and cost the run consumed, and find the runs that failed. See [_](/pipelines/agent-sessions).

package/build/dist/docs-index/{92b9b54a-c802-4e7d-8d7f-6101c18987fa.txt → 4ec440f2-0749-43eb-968b-dacff323ab6b.txt}

@@ -60,6 +60,15 @@ Grepr parses structured logs into an attribute document. Address a single attrib
 
 The shorthand reads one value out of the parsed document. The `attributes` column is the whole document, so use `@` when you want a field and `attributes` when you want the object itself.
 
+An attribute name is a dotted path of letters, digits, and underscores. A hyphen or a slash can join characters inside a segment, so `@trace-id` and `@app.kubernetes.io/name` are each one name. Because `-` and `/` are name characters, put whitespace around them when you mean subtraction or division: write `@bytes / 1024`, not `@bytes/1024` (which reads `bytes/1024` as one name). Every other character ends the name, so `@status=500` and `@duration_ms*2` work without spaces.
+
+To read a key that uses any other character, such as a space, comma, or bracket, reference it through the `attributes` column with a single-quoted key in brackets. The bracketed key can be any string, dots included, and names exactly one key; double a single quote to include one. Add one bracketed key per level of a nested path:
+
+```sql
+attributes['service.status']
+attributes['special outer key']['special inner key']
+```
+
 An attribute has no declared type, because two logs in the same dataset can carry different types under the same name. Grepr infers a type from how you use the value, so `SUM(@duration_ms)` reads it as a number and `LOWER(@user.email)` reads it as a string.
 
 Cast the attribute when you need a specific type or precision, and when you sort:
@@ -72,6 +81,8 @@ CAST(@duration_ms AS BIGINT)
 MIN(CAST(@duration_ms AS DOUBLE))
 ```
 
+Grepr reads a numeric attribute as a 64-bit floating point value, which represents whole numbers exactly only up to 9,007,199,254,740,992. Above that limit, two different whole numbers can compare as equal. Store large identifiers such as trace ids and 64-bit request ids as strings, which always match exactly. If an attribute already holds a large whole number, cast it to `BIGINT` to compare it exactly.
+
 > Sorting by an attribute you have not cast sorts it as text, so `100` sorts before `99`. Cast it to sort numerically.
 
 A path segment is a name or a number, and the segments are separated by dots.

package/build/dist/docs-index/5255d738-743a-49dd-b9d9-c2df3ca21c27.txt

@@ -0,0 +1,30 @@
+# Get parsed-query import state
+
+**GET** `/v1/integrations/{integrationId}/parsed-queries/import`
+
+**Operation ID**: `getParsedQueryImportStatus`
+**Summary**: Get parsed-query import state
+Says whether this vendor's parsed queries can be imported, whether the credential the import needs is saved, whether an import is already under way, and which integrations an import covers. Poll this while an import is running; what it imported is reported in the integration's activity log.
+
+## Tags
+- Integrations
+## Parameters
+
+- **integrationId** (required) - path
+  - Integration id
+  - Type: string
+
+## Responses
+
+### 200
+
+State retrieved
+
+- **Content-Type**: `application/json` / `ParsedQueryImportStatus`
+### 401
+
+Unauthorized
+
+### 404
+
+Not Found - Integration not found.

package/build/dist/docs-index/{c2e85183-cda1-45b6-8e67-efd406f202ed.txt → 8b1470a0-e89c-40c8-a90b-cf05f340f231.txt}

@@ -4,6 +4,8 @@
 
 **Operation ID**: `currentWindow`
 **Summary**: Get the current maxTokens window of one LLM integration
+## Tags
+- LLM Usage
 ## Parameters
 
 - **integrationId** (required) - path

package/build/dist/docs-index/{70ba46ea-b9ea-416f-9018-cf7c5d16cc04.txt → 8ddeea2c-3c85-4f2c-9430-24f3739d11d9.txt}

@@ -4,6 +4,8 @@
 
 **Operation ID**: `archive`
 **Summary**: Archive an organization skill
+## Tags
+- Skills
 ## Parameters
 
 - **id** (required) - path

package/build/dist/docs-index/{59964fe7-025b-4079-990d-68243df22568.txt → 97bc2023-512d-4286-a01b-8458891e24e7.txt}

@@ -43,6 +43,21 @@ This table lists all available permissions for organization and team-level roles
 | Edit | Datasets | Organization or Team |
 | View | Datasets | Organization or Team |
 
+## Permissions for AI agent resources \[#ai-agent-permissions]
+
+AI agents, skills, and agent memory do not have permissions of their own. They are governed by the permissions already in the table:
+
+| To do this | You need |
+| --- | --- |
+| View an agent, its investigations, or its skills | View on integrations |
+| Create, edit, or delete an agent or an organization skill | Edit on integrations |
+| Create or edit an LLM, MCP, or Grepr Agent integration | Edit on integrations |
+| Subscribe an agent to a pipeline, or unsubscribe it | Edit on jobs |
+| View the pipeline changes an agent proposed | View on jobs |
+| Apply or reject a pipeline change an agent proposed | Edit on jobs |
+
+An agent's own reach is separate from yours. An agent acts as the service account you assign it, and that account's roles cap what the agent can read and change, whatever tools it holds. To learn more, see [_](/ai-agents/capabilities#service-account).
+
 ## Permissions by role
 
 The following are the permissions granted to each role type in the Grepr platform:

package/build/dist/docs-index/9f1eb407-581b-4626-af0d-5fb8cc500d48.txt

@@ -0,0 +1,171 @@
+Start, follow, and read Grepr AI agent investigations, guide a running one, understand each state, and review the pipeline changes an agent proposes.
+
+# Run and review investigations
+
+An *investigation* is one run of an agent. It holds the signals that triggered it, every turn the agent took, every tool it called, the changes it made outside the sandbox that Grepr recognizes, and the summary it finished with. Investigations are listed on the agent's **Investigations** step.
+
+An investigation is a record, not a conversation. You can interrupt one to add guidance, but most investigations run to completion unattended and you read them afterwards.
+
+## Start an investigation manually \[#start-manual]
+
+Start one manually to try out an agent before subscribing it to anything, or to point an agent at something you already know about.
+
+1. On the agent's page, click **Run investigation**.
+2. Optionally enter **Context**, which is what the agent starts from, such as the service to look at or the symptom you saw.
+3. Click **Start investigation**.
+
+Context is the only instruction an investigation started manually receives beyond the agent's system prompt, so include the service, the time range, and the symptom. An investigation with no context relies entirely on the agent's prompt to decide what to examine.
+
+An investigation you start manually is not subject to the maximum queue wait, but it is subject to the concurrency limit and the token budgets. When a budget is exhausted, a manual investigation is discarded rather than queued, so you find out immediately instead of waiting. See [_](/ai-agents/create-an-agent#limits).
+
+## Investigation states \[#states]
+
+| State | What it means | What you can do |
+| --- | --- | --- |
+| Queued | Accepted and waiting for a free slot on the agent. No sandbox exists yet. | Cancel it. |
+| Running | The agent is working. | Stop it or cancel it. |
+| Stopping | A stop was requested and is being applied. | Cancel it. |
+| Cancelling | A cancel was requested and is being applied. | Wait for it to finish. |
+| Stopped | Either paused and waiting for instruction, or ended after waiting too long. | Resume a paused one, or continue a finished one in a new investigation. |
+| Completed | The agent finished and wrote a summary. | Continue it in a new investigation. |
+| Failed | The investigation ended with an error. | Read the reason, then continue it in a new investigation. |
+| Cancelled | You cancelled it. | Continue it in a new investigation. |
+| Discarded | Recorded but never ran. | Read why, then address the cause. |
+
+Stopped covers two situations, and the status icon tells them apart. A stopped investigation that is still waiting for instruction is paused and can be resumed, carrying on from where it left off while its sandbox is still there. If the sandbox is lost while the investigation is paused, the resumed agent restarts from the triggering signals and whatever you resume it with, so give it what it needs rather than assuming it still remembers. One that waited too long without instruction has ended, and the work it did is readable but no longer resumable. So resume a stopped investigation while you still want its context, rather than leaving it paused indefinitely.
+
+Completed, Failed, Cancelled, Discarded, and a timed-out Stopped are final. Nothing restarts them, though you can start a fresh investigation seeded with what one learned. See [Continue in a new investigation](#continue).
+
+## Read an investigation \[#read]
+
+Open an investigation from the agent's **Investigations** step. It reads top to bottom: what the agent concluded, what set it off, then how it got there.
+
+### The summary \[#summary]
+
+A finished investigation opens with the agent's own account of what it found. An investigation that failed or was discarded carries the reason it ended instead of a conclusion, which is the first thing to read when a run did not work.
+
+The summary is what the agent wrote for you to read, so it is the part to read when you want the conclusion. Read the timeline when you want to check the conclusion.
+
+### The triggering signal \[#trigger]
+
+The triggering signal is the event that started the run. A webhook signal shows the payload the sending system posted. A log pattern signal shows the pattern the reducer detected and a sample log line that matched it. An investigation you started manually shows the context you typed.
+
+Read the signal when a conclusion surprises you. An agent reasoning from a payload whose fields it cannot interpret often produces a plausible but wrong summary, and the fix is usually the integration's schema description rather than the agent's prompt. See [_](/integrations/grepr-agent-webhooks#schema-description).
+
+### The timeline \[#timeline]
+
+The timeline is every step in order: what the agent was told, what it said, each tool it called with the arguments it passed, and what each tool returned. Tool output is collapsed, so you can scan the shape of a run and expand only the calls that matter. Each call reports how long it took.
+
+Read the timeline to answer why an agent concluded what it did. Two patterns are worth recognizing:
+
+* Repeated similar tool calls usually mean the agent is missing a capability or some knowledge, and is working around the gap. Consider enabling a skill that covers the task or using a better model.
+* A run that ends without a conclusion usually means it reached its turn or token limit. The last turn shows where it was.
+
+### Recorded actions \[#actions]
+
+An *action* is a consequential change the agent made outside its own sandbox: a pipeline version it applied, a pipeline change it proposed for review, or a write it made through a connected MCP integration. Reads are not actions, and neither is everything an agent can do from a shell, so treat the count as a record of the changes Grepr recognizes rather than a complete audit. Actions appear beneath the tool call that made them and are counted in the **Actions** column of the list, so you can find the investigations that changed something without reading any transcripts.
+
+Actions record successful changes, not attempts. A tool call that failed appears in the timeline but produces no action.
+
+## Guide a running investigation \[#guide]
+
+### Stop and resume \[#stop-resume]
+
+Stopping ends the agent's session and pauses the investigation. Work already in flight is abandoned rather than finished, so a tool call that was running might not complete. Everything the investigation had recorded up to that point is kept, which is what a resume continues from.
+
+To continue it, click **Resume**. You can add a message to steer it, such as naming the service it should focus on, or resume with no message to let it carry on. Stop and resume when an agent is heading the wrong way but its work so far is worth keeping.
+
+### Cancel \[#end-for-good]
+
+Cancelling ends an investigation for good. Use it when the run is not worth finishing. The transcript remains readable.
+
+To cancel several at once, select them in the list and cancel the selection. This is how you clear a backlog that built up, such as from a misconfigured source. Cancelling is permanent, and an investigation that has already finished is left alone.
+
+### Continue in a new investigation \[#continue]
+
+A finished investigation cannot be resumed, but you can start a new one seeded from it. The new investigation begins with the earlier conversation, and you can add a message to direct it, such as asking it to verify that a change worked.
+
+The seed carries what the agent and you said to each other, not the tool calls it made or the results they returned, and a long conversation is trimmed to its most recent part. Put anything the new investigation must not lose into the message you start it with.
+
+Use this to carry an investigation forward after you have acted on it, rather than starting from nothing and paying for the same discovery twice.
+
+## Find investigations \[#find]
+
+The list holds one row per investigation, with its identifier, what triggered it, its summary, when it was created, how long it ran and how long it waited in the queue, its state, and how many actions it recorded.
+
+Three filters narrow it:
+
+* **Status** limits the list to the states you select.
+* **Actions** separates investigations that recorded a change from those that did not.
+* **Trigger** limits the list to investigations started manually, by a webhook, or by a log pattern.
+
+Filter on recorded actions when you want to review what an agent has changed, and on failed status when you are diagnosing an agent that is not working.
+
+## Why an investigation was discarded \[#discarded]
+
+A discarded investigation was recorded but never ran. There are three reasons, and each has a different fix:
+
+| Reason | What to do |
+| --- | --- |
+| The agent was at its concurrency limit and set to discard extra signals. | Raise the concurrency limit, switch to queueing, or reduce what the source emits. |
+| A queued investigation waited longer than the maximum queue wait. | Raise or remove the maximum queue wait, or raise the concurrency limit so the queue drains faster. |
+| A token budget was exhausted. | Raise the budget that blocked it, or wait for the window to reset. Check which budget it was on the agent's page. |
+
+A rise in discarded investigations usually means a source is emitting more than the agent can handle. Reducing what the source emits keeps the signal you want, whereas raising the limits keeps the volume and increases the cost. See [_](/ai-agents/subscriptions#volume).
+
+## Review the pipeline changes an agent proposes \[#suggestions]
+
+An agent set to require human approval records each pipeline change it proposes as a *suggestion* on that pipeline, and changes nothing until you apply it. Suggestions are on the pipeline's **Suggestions** step, not on the agent, because the decision is about the pipeline.
+
+Each suggestion lists when it was proposed, what it changes, and the investigation that produced it. To decide, review the proposed change as a difference against the pipeline's configuration, and read the investigation that produced it to see the evidence the agent based it on.
+
+Then either apply it or reject it:
+
+* Applying re-verifies the change against the pipeline's configuration as it is now, not as it was when the agent proposed it, and a running pipeline then restarts to pick it up. A suggestion whose assumptions no longer hold is refused rather than applied blindly, and it stays pending, so you can retry it after the pipeline settles.
+* Rejecting leaves the pipeline untouched and closes the suggestion.
+
+Reviewing a suggestion changes nothing on the live pipeline, so read as many as you like before deciding. Suggestions do not expire, but an old one is more likely to be refused on apply, because the pipeline's configuration has likely drifted. Review them while they still match the pipeline.
+
+To let an agent apply its own changes instead, see [_](/ai-agents/capabilities#change-approval).
+
+## Read investigations from the CLI \[#cli]
+
+The Grepr CLI reads investigations, which is useful for auditing many runs at once or feeding them into your own tooling.
+
+```bash
+# List an agent's failed investigations
+grepr investigation:list --agent-id <agent-id> --status FAILED --page-size 10
+
+# Read one investigation's metadata, summary, and recorded actions
+grepr investigation:get <investigation-id>
+
+# Read the turns, including tool calls and their results
+grepr investigation:turns <investigation-id> --page-size 10
+
+# Export a transcript to a file
+grepr investigation:transcript <investigation-id> --all --output investigation.json
+```
+
+To follow a running investigation as it progresses, add `--follow` to `investigation:turns`. To learn more about the CLI, see [_](/cli).
+
+## Frequently Asked Questions
+
+### How do I start a Grepr AI agent investigation manually?
+
+On the agent's page, click Run investigation, optionally enter the context the agent should start from, and click Start investigation. Context is the only instruction beyond the agent's system prompt, so include the service, the time range, and the symptom.
+
+### What does a stopped investigation mean in Grepr?
+
+Stopped covers two situations. An investigation that is still waiting for instruction is paused and can be resumed, carrying on from where it left off while its sandbox is still there. If the sandbox is lost while it is paused, the resumed agent restarts from the triggering signals and the message you resume it with. One that waited too long without instruction has ended, and remains readable but is no longer resumable. The status icon tells the two apart.
+
+### Can I resume a completed Grepr AI agent investigation?
+
+No. Completed, failed, cancelled, discarded, and timed-out stopped investigations are final. You can start a new investigation seeded from the finished one, and add a message to direct it, such as asking it to verify that a change worked.
+
+### Why was my investigation discarded?
+
+There are three reasons: the agent was at its concurrency limit and set to discard extra signals, a queued investigation waited longer than the maximum queue wait, or a token budget was exhausted. The agent's page reports which token budget blocked it and when the window resets.
+
+### How do I review a pipeline change proposed by a Grepr AI agent?
+
+Suggestions appear on the pipeline's Suggestions step. Review the proposed change as a difference against the current configuration and read the investigation that produced it, then apply or reject it. Applying re-verifies the change against the pipeline as it is now, and a running pipeline restarts to pick it up. A suggestion that no longer verifies is refused and stays pending, leaving the pipeline untouched.

package/build/dist/docs-index/{38d8ed1d-43cd-4702-87b3-7f6a3a01cd73.txt → 9fe63f74-179b-4e00-bca8-acc71b97bbf1.txt}

@@ -10,10 +10,13 @@ You can use the Grepr UI or the REST API to create and manage integrations. To u
 
 ## Integration types
 
-The Grepr platform includes two integration types:
+The Grepr platform includes the following integration types:
 
 * Observability platform integrations: Connections to monitoring, logging, and APM platforms, such as Datadog, Splunk, New Relic, and Sumo Logic.
 * Cloud storage integrations: Connections to cloud storage. The Grepr data lake uses cloud storage to store your raw data and metadata.
+* AI integrations: Connections that Grepr AI agents use, covering the model providers they reason with, the MCP servers they call, the webhook endpoints that trigger them, and the vector indexes that store their memories. See [Supported AI integrations](#ai-integrations).
+
+Observability platform and cloud storage integrations become the sources and sinks of your pipelines. AI integrations are used by AI agents instead, so they are not selectable as a pipeline source or sink.
 
 ## Supported platform and storage integrations \[#supported-integrations]
 
@@ -75,6 +78,34 @@ To configure the Grepr-hosted integration, you only need to assign a name to the
 
 Using the integration with your own S3 bucket requires that you deploy and configure an S3 bucket in your AWS account, but it provides more control over your data. See [Host a Grepr data lake with the Amazon S3 integration](/integrations/aws-s3).
 
+## Supported AI integrations \[#ai-integrations]
+
+The following integrations support Grepr AI agents. They appear on the **Integrations** page only when AI agents are enabled for your organization. To turn on AI agents, contact <support@grepr.ai>. To learn what AI agents do, see [_](/ai-agents).
+
+### LLM providers
+
+An LLM integration holds the credentials for a large language model provider. Grepr AI agents use generative models for reasoning and embedding models for memories.
+
+See [_](/integrations/llm).
+
+### MCP servers
+
+An MCP integration connects Grepr to a MCP server run by another system, so an agent can call that system's tools during an investigation. You set each integration's server URL, so you can point one at a self-hosted or regional endpoint.
+
+See [_](/integrations/mcp).
+
+### Grepr Agent webhooks
+
+A Grepr Agent integration is a webhook endpoint that turns events from another system, such as an alerting platform or a Kubernetes event forwarder, into AI agent investigations.
+
+See [_](/integrations/grepr-agent-webhooks).
+
+### Vector indexes
+
+A vector index integration stores the search index for agent memory, which is what lets an agent find past investigations that reached a similar conclusion. You create one in the **S3 Vector Index** section of the **Integrations** page.
+
+See [_](/ai-agents/memory#vector-index).
+
 ## Manage integrations in the Grepr UI \[#manage-integrations-in-ui]
 
 The **Integrations** page displays your integrations as cards, organized by observability vendor integrations and storage integrations. In each section, cards are ordered by recent activity, with the most active integrations appearing first.