# guide

Read the reference for this connector: what each tool really does, what a profile or log field means, what a solver option changes.

## What it is for

`guide` returns these reference pages to an assistant: what each tool really does, what a field of a profile or a log means, and what a solver option changes. It is the way to read a page from inside a conversation. It reads nothing from the account and changes nothing.

## What to know first

**The reply is for reading, never for saying.** Its first line says so. Read it, then answer the shooter in one or two short sentences as always. There is no spoken line.

**Start small.** No input gives the map. A topic gives that page's brief: what it is for, what to know first, its section names and the topics it links to. Ask for one section, or the whole page, only when the brief is not enough.

**A topic is a short name.** A tool's page is the tool's name. The other names are on the map: `connector`, `tools`, `profile`, `log`, `options`, and pages such as `profile/zero` or `options/lapse`. In a reply, a link whose target begins `guide:` points at a topic: `guide:solve` is the topic `solve`.

**Examples come one at a time.** `section: "examples"` lists a tool's worked examples by title; `example` with a number gives that one. A whole page never includes them.

**A long reply is cut.** A reply holds at most 24,000 characters. A page too long for that is given with its first sections whole, and the reply names the sections left out.

## Generated table

**Tool:** `guide` · **Family:** The reference · **Scope:** any link · **Save scope:** none · **Changes:** nothing · **Runs:** no solver work in the connector

**Description** (what the connector sends to an assistant, word for word):

```text
Read the reference for this connector: what each tool really does, what a profile or log field means, what a solver option changes. Use it before work not done here before. Saves nothing. It reads nothing from the account. Any link has it. The reply is for the assistant to read, never to read out. No input gives the map of every topic; topic (a tool's name, or a name from the map) gives that page's brief; section, example, full and search narrow or widen it. Guide: guide.
```

**Inputs** (5; read from the input schema the connector sends):

| Input | Type | Required | Bounds | Field |
|---|---|---|---|---|
| `topic` | text | no | at most 80 characters | - (per call) |
| `section` | text | no | at most 80 characters | - (per call) |
| `example` | integer | no | 1 to 99 | - (per call) |
| `full` | boolean | no | - | - (per call) |
| `search` | text | no | at most 120 characters | - (per call) |

**Sent with the inputs** (each input's own description, word for word; an input not listed is sent without one):

```text
topic: A topic name from the map: a tool's name ("solve"), "connector", "tools", "profile/zero", "log/group", "options/lapse". Without it: the map
section: One section of the topic, by its name from the brief; "inputs" for a tool's input table; "examples" for its worked examples
example: With section "examples": which worked example, counted from 1. One per call
full: true: every section of the topic, without its worked examples
search: Words to look for in topic names, titles, summaries and section names; up to 20 topics that hold every word
```

## When to use it, and when not

| The assistant needs | Use | Why |
|---|---|---|
| to know what a tool does beyond its description, before using it the first time | `guide` with `topic` set to the tool's name | The brief holds the facts that stop a mistake |
| a tool's inputs with their bounds | `guide` with `topic` and `section: "inputs"` | The table is read from the connector itself |
| to see a call and its reply | `guide` with `topic`, `section: "examples"` and `example` | Each example was run by the documentation generator |
| the meaning of a field or of a model choice | `guide` with `search`, or the index `profile`, `log` or `options` | An index has a few lines per page |
| a number for the shooter | the tool that computes it, such as `solve` | `guide` holds no account data and computes nothing |

## The inputs

All five inputs are optional. With none, the reply is the map.

**`topic`** names a page. Upper and lower case do not matter. A name that is no topic is answered with the nearest names, not with an error.

**`section`** names one section of the topic, as the brief lists them; a part of a name is enough when only one section holds it. `"inputs"` is the generated table of a tool's inputs, and of an option's values or a record's fields. `"examples"` is the list of worked examples.

**`example`** is the number of one worked example, counted from 1. Given without `section`, it still means an example.

**`full`** set to true gives every section of the topic except its worked examples.

**`search`** is read only when no `topic` is given. Every word must be found in a topic's name, title, summary or section names; the pages' own text is not searched. At most 20 topics are listed.

## What it returns

The reply is Markdown text. Its first line says the text is for the assistant to read and not to read out. The structured reply holds the same text under `text`, with a few facts beside it.

| Key | Holds |
|---|---|
| `form` | Which kind of answer this is: `map`, `brief`, `section`, `examples`, `example`, `full`, `search` or `unknown` |
| `topic` | The topic answered, when there is one |
| `sections` | The topic's section names, with the map, a brief and a whole page |
| `examples` | How many worked examples the topic has |
| `links` | The topics the page links to, with the map, a brief and a whole page; for a search, the topics found |
| `cut` | True when sections were left out, or the text was cut, to keep the reply under its limit |
| `text` | The whole reply text |

The examples below print `text` cut short; a real reply holds it whole.

## Worked examples

Every example below was run by the documentation generator against a made-up account, never a real one. Numbers are rounded to three places; generated ids and times are shown as placeholders. Two things are printed more briefly than the tool sent them, and nothing else is changed. A list of plain values stands on one line, whole up to 12 entries (a longer one, and a list of objects past 3, ends with a count of the rest). A reply that puts stored text in quotation marks also carries a note saying so, which an example leaves out and marks instead; no reply below carried it.

## When it refuses

The tool has no refusal of its own. A topic or a section it does not have, an example number past the last, and a search that finds nothing are each answered in words, with the nearest names or the names to choose from. What the caller typed is repeated only as a quoted label of at most 40 characters. An input of the wrong type is refused by the input check, on [the connector overview](connector.md).

## What it reads and changes

It reads the reference pages built into the connector, the same for every link. It reads no profile, no session, no theme and nothing else of any account, and it reaches no server. It saves nothing and sends no command.

## Below this page

- [the connector overview](connector.md): which tool fits which job, and how the other tools' replies are shaped.
- The map of every topic is the reply of `guide` with no input.

## Worked examples

**1. No input: the map**

Starting point: an account with no profile. Link scopes: `read`.

Call:
```json
{}
```

Reply (no spoken line):
```json
{
 "form": "map",
 "topic": "map",
 "sections": ["How to read it", "The areas", "What these pages are"],
 "examples": 0,
 "links": [],
 "cut": false,
 "text": "For you, the assistant, to read. Do not read this out: answer the shooter in one or two short sentences as always.\n\n# Cold Bore Lab reference\n\nThe map: what the..."
}
```

Saved nothing.

**2. A tool's name: its brief, its section names and the topics it links to**

Starting point: an account with no profile. Link scopes: `read`.

Call:
```json
{"topic":"solve"}
```

Reply (no spoken line):
```json
{
 "form": "brief",
 "topic": "solve",
 "sections": ["What it is for", "What to know first", "Generated table", "When to use it, and when not", "The inputs", "What it returns", "Worked examples", "When it refuses", "What it reads and changes", "Below this page"],
 "examples": 16,
 "links": ["compare_models", "connector", "edit_profile", "explain_dope", "get_context", "list_profiles", "log/air", "log/session", "log/target", "log_group", "options", "options/curvature", "(13 more)"],
 "cut": false,
 "text": "For you, the assistant, to read. Do not read this out: answer the shooter in one or two short sentences as always.\n\n# solve\n\nGive the dial for one range: elevat..."
}
```

Saved nothing.

**3. One section of a page**

Starting point: an account with no profile. Link scopes: `read`.

Call:
```json
{"topic":"profile/zero","section":"What to know first"}
```

Reply (no spoken line):
```json
{
 "form": "section",
 "topic": "profile/zero",
 "examples": 0,
 "cut": false,
 "text": "For you, the assistant, to read. Do not read this out: answer the shooter in one or two short sentences as always.\n\n# Zero: What to know first\n\nWhere the rifle ..."
}
```

Saved nothing.

**4. One worked example of a tool, by its number**

Starting point: an account with no profile. Link scopes: `read`.

Call:
```json
{"topic":"list_assets","section":"examples","example":2}
```

Reply (no spoken line):
```json
{
 "form": "example",
 "topic": "list_assets",
 "examples": 2,
 "cut": false,
 "text": "For you, the assistant, to read. Do not read this out: answer the shooter in one or two short sentences as always.\n\n# list_assets: worked example 2 of 2\n\nList t..."
}
```

Saved nothing.

**5. A search**

Starting point: an account with no profile. Link scopes: `read`.

Call:
```json
{"search":"tall target"}
```

Reply (no spoken line):
```json
{
 "form": "search",
 "links": ["tall_target"],
 "cut": false,
 "text": "For you, the assistant, to read. Do not read this out: answer the shooter in one or two short sentences as always.\n\n1 topic holds every word of \"tall target\":\n\n..."
}
```

Saved nothing.

**6. A name that is no topic: an answer with the nearest names, not an error**

Starting point: an account with no profile. Link scopes: `read`.

Call:
```json
{"topic":"zero"}
```

Reply (no spoken line):
```json
{
 "form": "unknown",
 "cut": false,
 "text": "For you, the assistant, to read. Do not read this out: answer the shooter in one or two short sentences as always.\n\nNo such topic: \"zero\". Nearest: `log/zero-ch..."
}
```

Saved nothing.

---

[All reference pages](index.md)