> ## Documentation Index
> Fetch the complete documentation index at: https://docs.repost.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Discovery and self-description

> Learn the command surface and output schemas directly from the binary, and install a repo-local agent primer.

The installed binary describes itself. An agent should learn the surface from `repost` rather than from a possibly-stale copy of these docs — the manifest and schemas always match the version in front of it.

## Read the command manifest

`capabilities` is the first machine-readable inventory to fetch for a binary. It always emits JSON.

```bash theme={null}
repost capabilities --json
```

The manifest lists command paths, usage, descriptions, command kind, group IDs, output mode, agent contract status, output schema names, and flags.

```json theme={null}
{
  "schema": "repost.capabilities/v1",
  "version": "8cf7709",
  "commands": [
    {
      "path": "events search",
      "use": "repost events search [QUERY]",
      "short": "Search received events",
      "kind": "command",
      "group_id": "search_debug",
      "output_mode": "json_envelope_or_table",
      "agent_contract": true,
      "output_schema": "repost.events.search/v1",
      "flags": [
        { "name": "bucket", "shorthand": "b", "type": "string", "usage": "Bucket slug or ID to search" },
        { "name": "limit", "type": "int", "default": "20", "usage": "Maximum events to return" }
      ]
    }
  ]
}
```

Cache the manifest by `version`. Refresh it after `repost update`, after installing a different binary, or when a workflow needs a command that is not present.

## Read one command's schema

Use `docs schema` when generated code needs field-level expectations for a single command.

```bash theme={null}
repost docs schema "events search"
```

The response gives the command path, output schema, output mode, runtime envelope shape, and a documented data shape when one exists.

```json theme={null}
{
  "schema": "repost.command_schema/v1",
  "command": "events search",
  "output_schema": "repost.events.search/v1",
  "output_mode": "json_envelope_or_table",
  "envelope": {
    "schema": "string",
    "data": "object",
    "error": "object"
  },
  "data_shape": {
    "items": "EventSearchItem[]",
    "total": "integer",
    "next_cursor": "string|null",
    "has_more": "boolean",
    "item": {
      "id": "string",
      "bucket_id": "string",
      "method": "string",
      "path": "string",
      "received_at": "RFC3339 timestamp",
      "response_status": "integer"
    }
  }
}
```

<Note>
  The `envelope` describes the runtime contract exactly. Most commands succeed with `{schema, data}` and fail with `{error}`; exception modes such as `top_level_json`, `single_json_object`, `jsonl`, and `markdown` are declared by `output_mode`. Use `data_shape` when present, and fall back to `output_schema` plus the [Output & errors](/agents/output-and-errors) contract for commands without a field-level shape.
</Note>

## Look up search syntax

`docs search` prints a compact query cheatsheet:

```bash theme={null}
repost docs search
```

The full grammar — searchable fields, boolean operators and wildcards, the live-filter subset for `expect`/`tail`, and cursor pagination — is in [Search & filters](/agents/search-and-filters).

## Install a repo primer

Commit a compact operating manual so every agent run in a repository starts informed.

<CodeGroup>
  ```bash Install into the repo theme={null}
  repost docs agent --install
  # writes .repost/AGENTS.md, then prints an @include line for your AGENTS.md / CLAUDE.md
  ```

  ```bash Print to stdout theme={null}
  repost docs agent --stdout
  ```

  ```bash Operating manual + runbooks theme={null}
  repost docs agent
  repost docs agent --topic runbooks   # dlq-drain, deploy-verify, incident-triage
  ```
</CodeGroup>

`--install` writes `.repost/AGENTS.md` (mode `0600`). Reference it from your existing agent instructions with `@include .repost/AGENTS.md`. The `runbooks` topic ships three ready-made procedures the agent can follow directly.

<Tip>
  Every page in these docs also exposes assistant entry points (top-right **Copy** / **Open in**): copy as Markdown, open in ChatGPT, Claude, Perplexity, Cursor, or VS Code, or use the **MCP** endpoint. Append `.md` to any page URL for its canonical machine-readable form.
</Tip>

The `.md` form of any page (append `.md` to its URL) is the canonical machine-readable version, and pages in this section include agent-only blocks — like this one — that compress the human walkthrough into copy-ready commands. Prefer the `.md` export when ingesting these docs programmatically.

## Continue

<Columns cols={3} className="gap-y-4">
  <Card title="Search & filters" icon="filter" href="/agents/search-and-filters" cta="Write queries" arrow="true">
    The query grammar, the live-filter subset, and cursor pagination.
  </Card>

  <Card title="Output & errors" icon="braces" href="/agents/output-and-errors" cta="Read the contract" arrow="true">
    What the schemas in the manifest resolve to at runtime.
  </Card>

  <Card title="Diagnose a webhook" icon="search-check" href="/agents/diagnose-webhooks" cta="Investigate" arrow="true">
    Put the search and inspect commands to work.
  </Card>
</Columns>