# How to use these docs

**These docs are written for two audiences: people, and the agents people point at them.** Both get first-class formats. This page explains the page types, the conventions each one follows, and how to feed the whole site to a model.

## Page types

Every page is one of five kinds, and knowing which you are on tells you what to expect from it.

| Type | Answers | Example |
| --- | --- | --- |
| **Tutorial** | "Walk me through this once" | [Quickstart](/getting-started/quickstart/) |
| **Guide** | "How do I do this specific thing?" | [Import a project](/cli/import/) |
| **Concept** | "What is this and when does it matter?" | [Agents & orchestration](/concepts/agents/) |
| **Reference** | "What exactly does this accept and return?" | [CLI reference](/reference/cli/), [API reference](/api/reference/) |
| **Status** | "What is true right now?" | [Availability](/releases/availability/), [Changelog](/releases/changelog/) |

Reference pages are exhaustive and boring on purpose. Concept pages tell you *when* something applies before explaining how it works. If you want to get something done, start from a guide and follow its closing cards.

## Conventions every page follows

- **The first sentence is a definition.** If you only read one line, it is that one.
- **Prerequisites are a named section**, never buried in prose.
- **Every command is followed by its expected output.** If you see something different, that difference is the bug.
- **Every page ends with an "If … fails" section** carrying *verbatim* error strings mapped to recovery steps. Search this site for the exact message you saw — it is quoted somewhere.
- **Every page closes with 2–4 cards** pointing at where to go next.
**Nothing here describes a capability that does not exist:** Version numbers and install commands are generated from what actually shipped, and the [API reference](/api/reference/) is generated from the contract the server serves — so neither can drift from the product. Where something is implemented but not reachable from a published surface, the page says so rather than staying quiet.

## For LLMs and agents

Three formats, all generated on every build.

| Format | What it is | Use it for |
| --- | --- | --- |
| [`/llms.txt`](/llms.txt) | An index of every page, with one-line descriptions | Letting a model choose what to read |
| [`/llms-full.txt`](/llms-full.txt) | Every page's Markdown concatenated | One-shot ingestion of the whole site |
| `<page>.md` | The Markdown twin of any page | Fetching a single page cleanly |

Any page's Markdown twin is its URL with `.md` appended:

```bash
curl -sS https://docs.hlix.ai/reference/cli/auth.md
curl -sS https://docs.hlix.ai/llms.txt
```

Expected result: clean Markdown with no navigation chrome, no cookie banner, and no HTML to strip.

The **Copy as Markdown** and **Open in…** actions at the top of every page do the same thing from a browser — copy the page for pasting into a model, or hand it straight to ChatGPT, Claude, Cursor, or Copilot.
**The twins are release-aware, not a raw dump:** The Markdown twins are not the source files. Build-only components — the release-status blocks — are replaced with the same truthful text a human sees, generated from the same ledger. A model reading `install.md` gets the real availability state, not an unrendered component tag.

### Pointing an agent at these docs

The MCP-connected route is the [official hlix MCP server](/mcp/), which gives an agent your actual workspace rather than the documentation. For the docs themselves, `llms-full.txt` in one fetch is usually enough:

```bash
curl -sS https://docs.hlix.ai/llms-full.txt -o hlix-docs.txt
```

For a narrower context window, fetch `/llms.txt` first and let the model pick the handful of `.md` twins it needs.

## Finding things

- **Search** (`/` or `Ctrl` `K`) indexes full page text, not just titles.
- **A verbatim error string** is the fastest search there is — every failure section quotes them exactly.
- **[Troubleshooting](/reference/troubleshooting/)** is symptom-first when you do not yet know which command owns your problem.
- **[Glossary](/concepts/glossary/)** when a word is doing more work than its everyday meaning.

## If a page seems wrong

- **A command behaves differently from its expected output.** Check [Changelog](/releases/changelog/) first; human output can change between releases while the JSON envelope stays fixed.
- **A page describes a package you cannot install.** That is deliberate and marked — see [Availability](/releases/availability/) for what has actually shipped.
- **An endpoint is missing from the API reference.** It is missing from the published contract, which means the SDKs cannot reach it either. [What is not here](/api/reference/#what-is-not-here) lists the known gaps.
- **A `.md` twin still shows a component tag.** That is a build defect, not a documentation choice. The build is supposed to fail on it.
- **The sidebar label and the page title disagree.** They are checked against each other; report it.

## Next steps

[Quickstart: ship your first task](/getting-started/quickstart/)
  [Glossary](/concepts/glossary/)
  [API reference](/api/reference/)
  [Troubleshooting](/reference/troubleshooting/)