@grepr/cli 1.11.5-de00b67 → 1.11.5-e13e9ae

package/build/dist/docs-index/0d54792f-2e35-42fb-bd9d-c91d8c806ef0.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/{a8f318c4-5398-4d02-b92e-086111883680.txt → 10110d98-33ec-4c1c-b607-c2ad92eee6cb.txt}

@@ -26,6 +26,10 @@ The payload containing integration data.
   type: string
   description: Client token for Datadog
 
+- name: dashboardFreshnessWindow (optional)
+  type: string
+  description: Only dashboards viewed within this window are imported as parsed queries. When unset, every dashboard is imported. Minimum one day.
+
 - name: exceptions (optional)
   type: object
   description: The imported exceptions from Datadog. This is a map from the vendor resource Id to the exception.
@@ -34,6 +38,10 @@ The payload containing integration data.
   type: string
   description: Filter to apply when reading any data from the Datadog API
 
+- name: includeNeverViewedDashboards (optional)
+  type: boolean
+  description: When the dashboard window is set, whether dashboards that were never viewed are still imported. Unset means they are.
+
 - name: sendKeyId (optional)
   type: string
   description: Identifier of the API key used to send data back to Datadog. Defaults to the only key when unset.

package/build/dist/docs-index/{951cfc27-da1b-4230-8999-7574f3409f77.txt → 128ad096-ead8-4399-8949-c1c98d508701.txt}

@@ -169,6 +169,16 @@ The **Default Strategy** section defines the strategies that apply to every attr
 
 As with path-specific strategies, you can add multiple default strategies. When you add multiple default strategies, each strategy produces a suffixed attribute in the summary, and the first strategy also writes to the base attribute name.
 
+## Send new-pattern signals to AI agents \[#agent-signals]
+
+The reducer identifies the patterns in your logs, which also makes it the first place a pattern that has never occurred before becomes visible. You can have the pipeline report each new pattern to your Grepr AI agents, so an agent investigates behavior that is new in your systems without you writing an alert for it first.
+
+To turn this on, on the reducer step of your pipeline, open the **Advanced** settings and select **Emit new-pattern signals to AI agents**.
+
+Turning it on emits nothing by itself. A signal reaches an agent only when that agent is subscribed to the pipeline, and Grepr refuses a subscription to a pipeline that has this setting off. So turn it on first, then subscribe the agent.
+
+Each pattern signals an agent once rather than on every occurrence, for as long as the reducer keeps that pattern in its state, so a pattern that keeps matching does not keep starting investigations. To learn how signals reach an agent and how to bound the volume, see [_](/ai-agents/subscriptions).
+
 ## Frequently Asked Questions
 
 ### What is the aggregation window?

package/build/dist/docs-index/1a49b2fc-1e09-4853-ac4e-7bc6b1eebfbe.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/1f4e0366-20ac-4329-aa4c-71a32267f9f6.txt

@@ -0,0 +1,116 @@
+Connect a model provider with a Grepr LLM integration, and cap how many tokens your agents consume per time window.
+
+# Configure LLM provider connections with a Grepr integration
+
+An LLM integration holds the credentials Grepr uses to call a large language model provider. Grepr AI agents can use LLM integrations for two purposes: a generative model used for reasoning, or an embedding model used for similarity analysis.
+
+An LLM integration can be assigned a token budget, which is a mechanism that caps the amount of tokens your agents can spend. When several agents share one integration, the budget applies to all of them together.
+
+> LLM integrations, along with the rest of the Grepr AI agent features, are in a closed beta. To request access, contact <support@grepr.ai>.
+
+## Requirements
+
+To create an LLM integration, you need:
+
+* The credential your provider requires, which is an API key for most providers, or a gateway URL and a key for the gateway.
+
+## Choose a provider \[#providers]
+
+An LLM integration serves one of two purposes, so create the one that matches what you need.
+
+For the model an agent reasons with, create an integration for your model provider. You can also create a gateway integration to route your agents through a gateway you run, which reaches whatever models you configure it with, so use one to choose the model yourself, apply your own routing rules, or keep model traffic inside your own infrastructure.
+
+For the embedding model that agent memory uses, create an integration for a provider that supplies embeddings. One integration can serve both purposes, so a single integration is often enough to run an agent with memory turned on.
+
+The **Type** menu in the **Add LLM** dialog lists the providers available to you.
+
+Don't see your provider in the list? Send a request to <support@grepr.ai>.
+
+## Create an LLM integration \[#create]
+
+1. On the **Integrations** page, next to the **LLMs** section heading, click **Add new**.
+2. In the **Add LLM** dialog, select the provider from the **Type** menu.
+3. Complete the remaining fields, which depend on the provider you selected.
+4. Click **Create**.
+
+You cannot change an integration's type after you create it. To move to a different provider, create a new integration and point your agents at it.
+
+Select the tab for your provider to see the fields it requires:
+
+| Field | Description |
+| --- | --- |
+| **Name** | A name for the integration, used to identify it when you configure an agent. |
+| **API Key** | Your Gemini API key. |
+| **Max tokens per window** | The total tokens that all agents using this integration can consume in each window. Leave empty for the default of 20,000,000. |
+| **Max tokens window (hours)** | The length of the budget window. Leave empty for the default of 1 hour. |
+
+A Gemini integration can serve as both an agent's model and the embedding model for agent memory.
+
+| Field | Description |
+| --- | --- |
+| **Name** | A name for the integration, used to identify it when you configure an agent. |
+| **Gateway URL** | The base URL of your LiteLLM proxy, such as `https://litellm.example.com/team-a`. Required. |
+| **Virtual key** | The LiteLLM virtual key Grepr authenticates with. |
+| **Validate virtual key when saving** | Turn this on to have Grepr verify the virtual key against the gateway before it saves the integration. |
+| **Max tokens per window** | The total tokens that all agents using this integration can consume in each window. Leave empty for the default of 20,000,000. |
+| **Max tokens window (hours)** | The length of the budget window. Leave empty for the default of 1 hour. |
+
+Grepr reaches whatever models your gateway exposes, so the model names available to an agent are the ones your LiteLLM configuration routes.
+
+| Field | Description |
+| --- | --- |
+| **Name** | A name for the integration, used to identify it when you configure an agent. |
+| **API Key** | Your OpenAI API key. |
+
+An OpenAI integration provides the embedding model that agent memory uses.
+
+## Cap token consumption with a budget window \[#max-tokens]
+
+An integration that serves an agent's model carries a token budget, which is what caps the spend of every agent sharing it. The budget has two settings:
+
+* **Max tokens per window** is the total tokens every agent sharing the integration can consume in one window.
+* **Max tokens window (hours)** is the length of that window. The value must divide 24 evenly, so the valid lengths are 1, 2, 3, 4, 6, 8, 12, and 24 hours. Windows are aligned to UTC.
+
+Before it starts an investigation, Grepr reserves the tokens that investigation is allowed to consume and checks the reservation against two budgets: the integration's budget, and the agent's per-window budget. Both must have room. An agent whose own budget is untouched still waits when the shared integration has none left, so when investigations stop starting, check which of the two is exhausted on the agent's page before you raise a limit. To learn more about the agent-level settings, see [_](/ai-agents/create-an-agent#limits).
+
+## Update an API key \[#update-key]
+
+To replace a key, click the three-dot menu on the integration card, select **Edit**, enter the new key, and click **Save**. Every agent using the integration picks up the new key automatically.
+
+## Grant team access \[#team-access]
+
+When you have teams in your Grepr organization, you can grant access to the integration to one or more of those teams. To configure team access when you create or edit an integration:
+
+1. In the **Grant Team Access** section, click the plus sign icon (+).
+
+2. Select the team or teams that should be granted access to the integration.
+
+3. Click **Create**.
+
+To learn more, see [Manage teams in the Grepr platform](/admin/manage-teams) and [Permissions in the Grepr platform](/grepr-platform/permissions).
+
+## View token usage \[#usage]
+
+Each LLM integration card on the **Integrations** page charts the tokens its agents consumed, broken down by token type, and shows how much of the budget window remains. The card totals every agent sharing the integration and lists which agents those are, so to see how much one agent is spending, open that agent's page.
+
+## Frequently Asked Questions
+
+### Which LLM providers can a Grepr AI agent use as its model?
+
+Create an LLM integration for your model provider, or a gateway integration to route your agents through a gateway you run, which reaches whatever models you configure it with. Use a gateway to choose the model yourself, apply your own routing rules, or keep model traffic inside your own infrastructure. The Type menu in the Add LLM dialog lists the providers available to you, and Grepr adds integrations continuously, so contact support\@grepr.ai to get connected to the provider you use.
+
+### Which LLM providers can Grepr use for agent memory embeddings?
+
+Create an LLM integration for a provider that supplies embeddings. One integration can serve as both an agent's reasoning model and its embedding model, so a single integration is often enough to run an agent with memory turned on.
+
+### How does Grepr cap the tokens my AI agents consume?
+
+An LLM integration that serves an agent's model carries a max-tokens budget and a window length in hours that must divide 24 evenly. Grepr reserves an investigation's tokens up front and requires room in both the shared integration budget and the agent's own per-window budget before the investigation starts.
+
+### Can I change an LLM integration's provider after creating it?
+
+No. The type is fixed when you create the integration. To move to a different provider, create a new integration and point your agents at it.
+
+### Why have my agent's investigations stopped starting?
+
+The most common cause is an exhausted token budget. Because several agents can share one LLM integration, the shared budget can run out while the agent's own budget is untouched. The agent's page reports which of the two blocked the investigation and when the window resets.

package/build/dist/docs-index/{f17218cd-b518-4516-9564-568f023b81af.txt → 1f846b4b-c1be-4c64-b1c6-297320256255.txt}

@@ -38,6 +38,14 @@ API key is invalid
 
 No such webhook integration
 
+### 409
+
+The integration has no live target agent to start
+
 ### 413
 
 Body exceeds the size limit
+
+### 503
+
+At least one target agent could not be started for a transient reason; retry

package/build/dist/docs-index/246f4299-ab2e-4d88-90e0-17696d07d873.txt

@@ -0,0 +1,21 @@
+# ParsedQueryImportStatus
+
+**Type**: `object`
+
+## Properties
+
+- name: coveredIntegrationIds (required)
+  type: array of string
+  description: Every integration an import updates. Integrations that share a vendor account share one fetch, so importing for one imports for all of them.
+
+- name: hasCredential (required)
+  type: boolean
+  description: Whether the credential the import needs is saved. For Datadog this is the application key.
+
+- name: importing (required)
+  type: boolean
+  description: Whether an import covering this integration is already under way.
+
+- name: supported (required)
+  type: boolean
+  description: Whether this vendor's parsed queries can be imported at all. False for vendors Grepr cannot read alert queries from.

package/build/dist/docs-index/436e64f1-3bbe-4f3a-bc1b-7ee769027397.txt

@@ -0,0 +1,124 @@
+Use the skills Grepr ships and write your own, so a Grepr AI agent loads the guidance and tools a task needs only when that task comes up.
+
+# Extend agents with skills
+
+A *skill* is a directory of instructions that an agent loads only when the task it covers comes up. Grepr ships a set of skills, and you can write your own for the procedures your organization follows.
+
+Skills exist because an agent's system prompt is read at the start of every investigation, so anything you put there costs tokens on every run whether it is relevant or not. Guidance that applies to one kind of task belongs in a skill. A skill can also carry the tools its task needs, which is why enabling one is often how you grant a capability rather than pinning the tool yourself.
+
+Skills are on the **Skills** page, which shares the left rail with **Agents**.
+
+## Skill scopes \[#scopes]
+
+| Scope | Where it comes from | Who can change it |
+| --- | --- | --- |
+| Platform | Maintained by Grepr and available to every agent. | Read only. |
+| Organization | Created and managed by you. | Anyone with the Edit permission on integrations. |
+
+The scope also changes how much a skill grants. To learn more, see [_](/ai-agents/capabilities#grant-scope).
+
+## Platform skills \[#platform]
+
+Grepr maintains a catalog of platform skills, available to every agent. Read the catalog on the **Skills** page, where each skill lists what it covers and which tools it grants. The catalog changes as Grepr adds skills, so treat the page as the authoritative list.
+
+The skills fall into three groups:
+
+* **Investigation approaches.** How to work through a kind of problem. Incident Response covers a log pattern the pipeline has just flagged, and Triage Security Pattern covers a first-seen pattern that might be security relevant.
+* **Pipeline changes.** How to change a pipeline safely. Test Pipeline Change is the safety procedure, which plans a change, reads the preview of the difference, and replays the investigation's own sample logs through the proposed pipeline before submitting it. Others cover a specific kind of change, such as tuning Grok parsing or authoring a SQL transform.
+* **Grepr reference and commands.** What an agent needs to know to use Grepr itself, such as the processing model, the operations reference, and how to query the data lake or read past investigations.
+
+Most agents want an investigation approach plus Test Pipeline Change. The approach gives the agent a way to work through its signals, and Test Pipeline Change stops it submitting a pipeline change it has not verified against real samples.
+
+> An agent proposes changes to a pipeline's Grok parsers and its SQL transforms. The catalog also holds skills for changes you make yourself with the Grepr CLI, such as masking and filtering, so a skill's presence does not by itself mean an agent will make that change. To learn more, see [_](/ai-agents/capabilities#tool-table).
+
+## Create an organization skill \[#create]
+
+1. On the **Skills** page, in the **Organization skills** section, click **Add New Skill**.
+2. Enter a **Display name**. Grepr derives the skill's identifier from this name, and the identifier must be unique across your organization's skills and the platform skills.
+3. Write the skill's files, starting with `SKILL.md` at the root. See [What SKILL.md must contain](#skill-md).
+4. Select the tools the skill needs under **Approved tools**. See [Approve the tools a skill needs](#approved-tools).
+5. Save the skill.
+
+Organize a skill the way you would a short runbook. Keep `SKILL.md` to the approach and put long reference material, such as a table of service names or an example payload, in separate files the agent reads when it needs them.
+
+### What SKILL.md must contain \[#skill-md]
+
+Every skill has a `SKILL.md` file at its root, and that file must begin with front matter containing a `description`:
+
+```markdown
+---
+description: How to respond to a checkout service latency alert - which dashboards to read, which dependencies to rule out, and when to page the on-call engineer. Use when a signal names the checkout service.
+---
+
+# Responding to checkout latency
+
+...
+```
+
+The description is the only part of a skill an agent reads before deciding whether the skill is relevant, so write it to answer two questions: what the skill covers, and when to use it. A description that only names the topic leaves the agent guessing, while one that ends with a sentence starting "Use when" tells it exactly when to load the skill. The description can be up to 1,024 characters.
+
+The body of `SKILL.md` is read after the agent loads the skill, so put the approach there.
+
+### Approve the tools a skill needs \[#approved-tools]
+
+The **Approved tools** field is what grants tools to an agent that enables this skill. Select only the tools the skill's procedure actually uses.
+
+> In an organization skill, the **Approved tools** field is what grants access. An `allowed-tools` entry in the front matter of your `SKILL.md` does not grant anything, so a skill whose front matter lists tools but whose **Approved tools** field is empty grants nothing.
+
+Each tool you approve grants its whole family to any agent that enables the skill, so approving a tool is a permission decision about the agent, not only about the skill. To keep the grant narrow, approve fewer tools. A skill that needs no tools at all grants none, and is safe to enable on any agent.
+
+## Enable a skill on an agent \[#enable]
+
+Enable skills on the agent's **Capabilities** step, where they are grouped into abilities, which carry tools, and reference skills, which carry only knowledge. To learn more, see [_](/ai-agents/capabilities#grepr-access).
+
+A skill takes effect on investigations that start after you save the agent.
+
+## Update a skill \[#update]
+
+Editing a skill replaces its whole directory, so the version you save is the version agents get. Grepr tracks a revision for each skill and refuses a save based on a revision that is no longer the latest, which stops one save overwriting another.
+
+Every agent with the skill enabled picks up the new revision on its next investigation, so a change to a widely enabled skill reaches many agents at once. Change a shared skill the way you would change shared code.
+
+## Delete a skill \[#delete]
+
+Grepr refuses to delete a skill that any active agent still has enabled. Remove it from each of those agents on their **Capabilities** step, then delete it.
+
+Deleting an organization skill archives it, and investigations that already ran keep their transcripts unchanged.
+
+An agent that loses a skill also loses the tools that skill granted, so before you remove a skill that carried tools, decide whether each agent still needs them and grant them another way if so. See [_](/ai-agents/capabilities#grepr-access).
+
+## Limits \[#constraints]
+
+| Limit | Value |
+| --- | --- |
+| Files in one skill | 25 |
+| Directories in one skill | 10 |
+| Directory levels below the root | 3 |
+| Characters in a file path | 240 |
+| Size of one file | 256 KiB |
+| Total size of one skill | 1 MiB |
+| Characters in a description | 1,024 |
+| Skills enabled on one agent | 20 |
+| Total size of the skills enabled on one agent | 8 MiB |
+
+## Frequently Asked Questions
+
+### What is a Grepr AI agent skill?
+
+A skill is a directory of instructions that an agent loads only when the task it covers comes up, and which can also grant the tools that task needs. Guidance that applies to one kind of task belongs in a skill rather than in the system prompt, which is read on every investigation.
+
+### What skills does Grepr provide?
+
+Grepr maintains a catalog of platform skills available to every agent, covering investigation approaches such as Incident Response, pipeline-change procedures such as Test Pipeline Change, and reference material about Grepr itself. Read the catalog on the Skills page, which is the authoritative list because it changes as Grepr adds skills.
+
+### How do I grant tools through my own skill?
+
+Select them in the Approved tools field on the skill. An allowed-tools entry in your SKILL.md front matter does not grant anything in an organization skill, so a skill whose front matter lists tools but whose Approved tools field is empty grants nothing.
+
+### What must a SKILL.md file contain?
+
+Front matter with a description of up to 1,024 characters. The description is the only part an agent reads before deciding whether the skill is relevant, so it should say what the skill covers and when to use it. The body holds the approach and is read after the agent loads the skill.
+
+### How many skills can one Grepr AI agent use?
+
+Up to 20 skills, with a combined size of 8 MiB. A single skill can hold 25 files across 10 directories, no more than 3 levels below the root, up to 256 KiB per file and 1 MiB in total.

package/build/dist/docs-index/{d5f2a9d1-55ad-410b-baed-a261f67c1b34.txt → 46489f8c-4ccb-426f-90ae-1a91d6cce559.txt}

@@ -31,6 +31,9 @@
 - name: double (optional)
   type: number
 
+- name: emptyObject (optional)
+  type: boolean
+
 - name: float (optional)
   type: number
 

package/build/dist/docs-index/5453603f-8f46-4928-9658-db59a83d7cfc.txt

@@ -0,0 +1,118 @@
+Connect a Grepr AI agent to the pipelines and Grepr Agent integrations whose signals it investigates, and control how many signals reach it.
+
+# Subscribe an agent to signal sources
+
+A *signal* is an event that starts an investigation. A *subscription* connects an agent to a source of signals, so that source's events are investigated automatically rather than only when you start an investigation manually.
+
+A subscription carries no filters or conditions of its own. What an agent investigates is decided by what the source emits, so you narrow an agent's work by changing the source rather than the subscription.
+
+## Signal sources \[#sources]
+
+Signals reach an agent in four ways:
+
+| Signal | Where it comes from | How the agent is chosen |
+| --- | --- | --- |
+| Log pattern | A pipeline reducer detected a log pattern it has not seen before. | By subscription. |
+| Pipeline signal | A SQL output in a pipeline is routed to the agent signal and matched an event. | Named in the pipeline's agent signal sink. |
+| Webhook | A Grepr Agent integration received an event. | By subscription. |
+| Manual | You started the investigation. | You chose the agent. |
+
+The log pattern and webhook signals use subscriptions, which you manage on the agent's **Subscriptions** step. The pipeline signal names its agents in the pipeline itself instead, and is described in [_](#agent-signal-sink).
+
+## Subscribe an agent to a pipeline \[#pipeline-sources]
+
+A pipeline can tell your agents when its reducer detects a log pattern it has not seen before, which is how an agent learns about behavior that is new in your systems rather than behavior you already knew to alert on.
+
+### Step 1: Turn on new-pattern signal emission \[#emit-signals]
+
+A pipeline emits nothing to agents until you turn it on, and Grepr refuses a subscription to a pipeline that has it off. Turning it on changes the pipeline's configuration, so Grepr redeploys the pipeline before signals start flowing. Subscribing and unsubscribing afterwards take effect without a restart. A pipeline needs a log reducer or a pattern matcher to emit these signals at all.
+
+To turn it on, go to the pipeline's reducer configuration, open the advanced settings, and select **Emit new-pattern signals to AI agents**.
+
+To learn more about the reducer, see [_](/transforms/reducer/configuration).
+
+### Step 2: Subscribe the agent \[#subscribe-pipeline]
+
+1. On the agent's page, go to the **Subscriptions** step.
+2. In the **Subscribe to a signal source** menu, select the pipeline under **Pipelines**.
+3. Click **Subscribe**.
+
+Subscriptions apply as soon as you make them and are not held by the agent's save bar. A running pipeline picks up a new subscriber without restarting, so you can subscribe an agent to a live pipeline at any time.
+
+### When a pattern produces a signal \[#pattern-emission]
+
+A pattern signals an agent only if the agent subscribed after that pattern last emitted a signal. This has two consequences worth knowing before you rely on it:
+
+* An agent is notified about each pattern once, for as long as the reducer keeps that pattern in its state. A pattern that keeps occurring does not keep starting investigations, so a pattern that matches a high volume of logs does not flood an agent. A pattern the reducer drops from its state and later meets again counts as new, and signals its subscribers a second time.
+* Subscribing gives you no backlog. An agent you subscribe today is never notified about occurrences that already happened. It is notified the next time any pattern matches, including a pattern the pipeline flagged before you subscribed, because that agent is newer than the pattern's last emission.
+
+So subscribing an agent to an established pipeline can produce a burst of investigations, one for each of its recurring patterns as that pattern next matches, and then settle down to one per newly detected pattern. Expect that burst on a busy pipeline and set the agent's concurrency limit before you subscribe. See [Control how many signals reach an agent](#volume).
+
+## Send specific events with an agent signal sink \[#agent-signal-sink]
+
+New-pattern signals tell an agent about behavior that is new. When you want an agent to investigate behavior you can describe instead, route a SQL output in the pipeline to the agent signal. Every event that output emits becomes a signal, so you decide exactly what reaches the agent by writing the SQL.
+
+This mechanism does not use subscriptions. The pipeline names the agents directly, so an agent can receive these signals without appearing in its own **Subscriptions** step.
+
+To configure it:
+
+1. In the pipeline, add a SQL transform whose output is routed to the agent signal. The routed output must produce log events.
+2. In the pipeline's sinks, edit the agent signal sink and select the agents in the **Agents** field.
+3. Optionally enter **Context**, which is guidance sent with every signal from this pipeline, such as which team owns the service or what an acceptable remediation is. A context can be up to 4,096 characters.
+
+The sink and the route are two halves of one configuration, and Grepr saves the pipeline only when both are present. A pipeline with a routed output needs a sink naming at least one agent, and a sink cannot remain after you remove its last route. When you stop sending signals from a pipeline, remove the route and the sink together.
+
+Because every matching event becomes a signal, a SQL output that matches broadly can produce far more investigations than an agent can run. Write the output to match the events you would want to look at yourself, then check the agent's queue after the change. See [Control how many signals reach an agent](#volume).
+
+To learn more about SQL transforms, see [_](/transforms/sql-transform).
+
+## Subscribe an agent to a Grepr Agent integration \[#webhook-sources]
+
+A Grepr Agent integration turns events from another system into investigations. Every event it accepts starts an investigation on each subscribed agent, with no pattern detection or deduplication in between.
+
+1. On the agent's page, go to the **Subscriptions** step.
+2. In the **Subscribe to a signal source** menu, select the integration under **Grepr Agent**.
+3. Click **Subscribe**.
+
+Subscribe more than one agent to an integration when you want different agents to examine the same event differently, such as one that diagnoses and one that checks for a security concern. Each subscribed agent gets its own investigation of the event.
+
+To create an integration and send events to it, see [_](/integrations/grepr-agent-webhooks).
+
+## Unsubscribe an agent \[#unsubscribe]
+
+On the agent's **Subscriptions** step, remove the source from the table and confirm. The agent stops investigating that source's signals. Investigations already running finish.
+
+Detach an agent from its pipelines and from the Grepr Agent integrations that name it before you delete it, because Grepr refuses to delete an agent either one still targets. A pipeline that names the agent in its agent signal sink is not covered by that check, so clear the agent from the sink's **Agents** field yourself. Because a sink keeps at least one agent, name another in its place or remove the sink with the routes that feed it. See [_](/ai-agents/create-an-agent#delete).
+
+## Control how many signals reach an agent \[#volume]
+
+Because subscriptions carry no filters, the number of investigations an agent runs is set by the sources you subscribe it to and the limits on the agent itself:
+
+* Narrow what the source emits. For a pipeline signal, make the SQL output match fewer events. For a webhook, send fewer events from the system at the other end. This is the only way to reduce signals rather than drop them.
+* Cap the agent's concurrency. Choose how many investigations run at once and whether extra signals queue or are discarded. See [_](/ai-agents/create-an-agent#concurrency).
+* Expire stale queued signals. Set a maximum queue wait so a signal that has waited too long is dropped rather than investigated late.
+* Cap the tokens. A per-window token budget on the agent bounds its spend whatever the signal volume. See [_](/ai-agents/create-an-agent#window-limits).
+
+New-pattern signals need less of this than the other sources, because a pattern notifies an agent once rather than on every occurrence.
+
+## Frequently Asked Questions
+
+### How do I make a Grepr pipeline trigger AI agent investigations?
+
+Select Emit new-pattern signals to AI agents in the pipeline reducer's advanced configuration, then subscribe the agent to that pipeline on the agent's Subscriptions step. Grepr refuses a subscription to a pipeline that has the option off, and a pipeline needs a log reducer or a pattern matcher to emit these signals at all.
+
+### Why didn't my agent investigate a log pattern again?
+
+A pattern signals an agent only if the agent subscribed after that pattern last emitted a signal, so a pattern that keeps occurring does not keep starting investigations for an agent that has already seen it. A newly subscribed agent is different: it is newer than every previous emission, so it is notified the next time each pattern matches, which can produce a burst of investigations when you subscribe to an established pipeline.
+
+### Can I filter which signals reach a Grepr AI agent?
+
+Not on the subscription, which carries no filters or conditions. You narrow what an agent investigates by changing the source: make a routed SQL output match fewer events, or send fewer webhook events. You can also cap the agent's concurrency, expire stale queued signals, and cap its token budget.
+
+### What is the difference between a new-pattern signal and an agent signal sink?
+
+A new-pattern signal fires when the reducer detects a log pattern it has not seen before, and the agent is chosen by subscription. An agent signal sink sends every event matched by a SQL output you routed to the agent signal, and the pipeline names the agents directly rather than using subscriptions.
+
+### Do I need to restart a pipeline after subscribing an agent?
+
+No. A running pipeline picks up a new subscriber without restarting, and subscriptions apply as soon as you make them.