# Machine-readable docs

> llms.txt, every page as Markdown, and capabilities.json: the files tools and language models read.

URL: https://docs.harthelm.dev/reference/machine-readable/ · Harthelm v1.6.0

These docs also come in forms that programs read without parsing HTML: an index and a full copy for language models,
every page as Markdown, and `capabilities.json`, which describes Harthelm in one JSON file. They are built together
with the pages, from the same release, and every address in them is absolute.

| Path | What |
|---|---|
| `/llms.txt` | The index: what the docs cover, then every page with its description, linked to its Markdown. |
| `/llms-full.txt` | Every page as Markdown, in one file. |
| `/<page>.md` | One page as Markdown. |
| `/capabilities.json` | Harthelm in one JSON file: the release, where releases come from, the features, the `hart` commands and the references. |
| `/openapi.json` | The OpenAPI document of the REST API. |
| `/schemas/harthelm.schema.json` | The JSON Schema of `harthelm.yml`. |

## llms.txt and llms-full.txt

`/llms.txt` follows the llms.txt convention: a title, a summary of what the docs cover, then a section for each part
of the sidebar with every page's description and a link to its Markdown. The release notes are under **Optional**, the
section a tool may skip. Read it first, then fetch the pages you need:

```sh title="Terminal"
curl https://docs.harthelm.dev/llms.txt
```

`/llms-full.txt` holds every page in one file, in the order of the sidebar, each with its title, description and
address. It is large; take it when a tool wants all of the docs at once:

```sh title="Terminal"
curl -O https://docs.harthelm.dev/llms-full.txt
```

## Every page as Markdown

Append `.md` to a page's address, without its trailing slash. The Markdown of
`https://docs.harthelm.dev/getting-started/quickstart/` is:

```sh title="Terminal"
curl https://docs.harthelm.dev/getting-started/quickstart.md
```

The first page of a section also answers with `/index.md` appended (`/reference.md` and `/reference/index.md` are the
same page), and `/index.md` is `/llms.txt`.

Or ask for the page's own address with `Accept: text/markdown`:

```sh title="Terminal"
curl -H 'Accept: text/markdown' https://docs.harthelm.dev/getting-started/quickstart/
```

The site answers with Markdown when the `Accept` header lists `text/markdown` before `text/html`; browsers list
`text/html` first and get the page. The answer's type is `text/markdown; charset=utf-8`, it says `Vary: Accept`, and
like every Markdown copy it carries `X-Robots-Tag: noindex`, so search engines keep to the pages.

A page in Markdown starts with its title, its description, its address and the release it describes, then its text.
Links to other pages are absolute. The operations of the [REST API](https://docs.harthelm.dev/reference/api/) list their method and path,
parameters, request body and responses.

## capabilities.json

`/capabilities.json` describes Harthelm in one file: the release these docs describe, where its images, chart and
files come from, the features with their pages, the `hart` commands, and the addresses of the OpenAPI document, the
`harthelm.yml` schema, the chart values and the release notes. A tool that lands on any page finds it in the page's
head, as `<link rel="alternate" type="application/json">`, and in `/llms.txt`.

```sh title="Terminal"
curl -s https://docs.harthelm.dev/capabilities.json | jq .product
```

The two documents it links are published next to it:

- `/openapi.json` is the OpenAPI document of the release's REST API. Its server is
  `https://console.example.com/api/v1`; use your console's address. Every installation also serves its own at
  `/api/v1/openapi.yaml`.
- `/schemas/harthelm.schema.json` is the JSON Schema of `harthelm.yml`. Every installation also serves it, without
  credentials, at `/api/v1/schemas/harthelm.json`.

### Stability

`schemaVersion` changes only when a field is removed or changes meaning. New fields can appear at any time: read the
fields you know and ignore the others. A field that does not apply is `null`, never left out.

### Fields

Every address is absolute.

| Field | Type | What |
|---|---|---|
| `schemaVersion` | number | The version of this shape: `1`. |
| `generatedAt` | string | The day the file was built, `YYYY-MM-DD`. |
| `product.name` | string | `Harthelm`. |
| `product.summary` | string | What Harthelm is, in one sentence. |
| `product.version` | string | The release these docs describe, for example `1.6.0`. |
| `product.ref` | string | Its tag, for example `v1.6.0`. |
| `product.commit` | string | The commit of the release. |
| `product.committedAt` | string or null | When that commit was made, ISO 8601. |
| `product.stable` | boolean | `true` when the docs describe a release, which the published docs always do. |
| `product.released` | string or null | The release day from the release notes, `YYYY-MM-DD`. |
| `product.apiVersion` | string | The version of the REST API, `info.version` of the OpenAPI document. |
| `docs.home` | string | The docs home page. |
| `docs.llmsTxt` | string | `/llms.txt`. |
| `docs.llmsFullTxt` | string | `/llms-full.txt`. |
| `docs.markdown.urlPattern` | string | The address of a page's Markdown; `{page}` is the page's path without the slashes around it, for example `getting-started/quickstart`. |
| `docs.markdown.accept` | string | The type that asks a page's own address for its Markdown: `text/markdown`. |
| `docs.markdown.example` | string | The Markdown address of one page. |
| `docs.sitemap` | string | The sitemap. |
| `docs.capabilitiesPage` | string | This page. |
| `releaseChannel` | object or null | Where the release comes from; `null` before 1.6.0, the first release published there. |
| `releaseChannel.registry.host` | string | `registry.harthelm.dev`, the OCI registry with the images and the chart. |
| `releaseChannel.registry.images` | string | How the images are named: `registry.harthelm.dev/harthelm/<image>:<tag>`. Harthelm's own images are tagged with the release, for example `1.6.0`; the managed services and the operators keep their vendor's own tag ([the list](https://docs.harthelm.dev/self-hosting/install/get-harthelm/#what-the-registry-holds)). |
| `releaseChannel.registry.chart` | string | The chart: `oci://registry.harthelm.dev/harthelm/charts/harthelm`. |
| `releaseChannel.registry.access` | string | How to get in: a login with your licence id and registry token. |
| `releaseChannel.files.host` | string | `get.harthelm.dev`, the release files. |
| `releaseChannel.files.release` | string or null | The folder of this release's files. |
| `releaseChannel.files.sources` | string | The folder of the source bundles. |
| `releaseChannel.files.access` | string | Public HTTPS, no login. |
| `releaseChannel.signingKey` | string or null | The public key that signs the release's images and chart; `null` for a release without one. |
| `releaseChannel.guide` | string | [Get Harthelm](https://docs.harthelm.dev/self-hosting/install/get-harthelm/). |
| `features[].id` | string | The page's slug, for example `workspaces`. |
| `features[].title` | string | The page's title. |
| `features[].summary` | string | The page's description. |
| `features[].kind` | string | `concept` or `guide`. |
| `features[].group` | string or null | The guide's group in the sidebar, for example `Workspaces`; `null` for a concept. |
| `features[].url` | string | The page. |
| `features[].markdown` | string | The page as Markdown. |
| `cli.name` | string | `hart`. |
| `cli.reference` | string | [The hart reference](https://docs.harthelm.dev/reference/hart/). |
| `cli.install` | string | [Install hart](https://docs.harthelm.dev/getting-started/install-hart/). |
| `cli.commands[].name` | string | A top-level command, for example `hart ws`. |
| `cli.commands[].group` | string or null | Its group in `hart --help`, for example `Workspaces`. |
| `cli.commands[].summary` | string | What it does, in the words of `hart --help`. |
| `cli.commands[].url` | string | Its page in the reference. |
| `cli.commands[].subcommands` | list of strings | Its subcommands, for example `hart ws create`; empty for a command without any. |
| `references.openapi.document` | string | `/openapi.json`. |
| `references.openapi.openapi` | string | The OpenAPI version of that document, for example `3.1.0`. |
| `references.openapi.apiVersion` | string | The version of the REST API. |
| `references.openapi.page` | string | [The REST API reference](https://docs.harthelm.dev/reference/api/). |
| `references.openapi.installationPath` | string | Where an installation's console serves the document, from the document's own server and route: `/api/v1/openapi.yaml`. |
| `references.harthelmYml.schema` | string | `/schemas/harthelm.schema.json`. |
| `references.harthelmYml.id` | string or null | The schema's `$id`. |
| `references.harthelmYml.page` | string | [The harthelm.yml reference](https://docs.harthelm.dev/reference/harthelm-yml/). |
| `references.harthelmYml.installationPath` | string | Where an installation's console serves the schema, from the OpenAPI document's server and route: `/api/v1/schemas/harthelm.json`. |
| `references.chartValues.page` | string | [The chart values](https://docs.harthelm.dev/reference/chart-values/). |
| `references.chartValues.chart` | string or null | The chart in the registry; `null` before 1.6.0. |
| `references.releaseNotes.index` | string | [The release notes](https://docs.harthelm.dev/releases/). |
| `references.releaseNotes.current` | string or null | The release notes of this release. |

`features` lists the concepts and then the guides, in the order of the sidebar; `cli.commands` lists the commands in
the order of `hart --help`.

### Example

The file for Harthelm 1.6.0, shortened to two of its features and one of its commands. `/capabilities.json` itself
always describes the release these docs describe, so its release, dates and lists can differ from this one:

```json title="capabilities.json"
{
  "schemaVersion": 1,
  "generatedAt": "2026-10-21",
  "product": {
    "name": "Harthelm",
    "summary": "Cloud workspaces and hosting for your team, on your own Kubernetes.",
    "version": "1.6.0",
    "ref": "v1.6.0",
    "commit": "273bdc8b21bf03340bec6007b1dffdfd38d5cf08",
    "committedAt": "2026-10-20T13:37:46+02:00",
    "stable": true,
    "released": "2026-10-20",
    "apiVersion": "0.12.0"
  },
  "docs": {
    "home": "https://docs.harthelm.dev/",
    "llmsTxt": "https://docs.harthelm.dev/llms.txt",
    "llmsFullTxt": "https://docs.harthelm.dev/llms-full.txt",
    "markdown": {
      "urlPattern": "https://docs.harthelm.dev/{page}.md",
      "accept": "text/markdown",
      "example": "https://docs.harthelm.dev/getting-started/quickstart.md"
    },
    "sitemap": "https://docs.harthelm.dev/sitemap.xml",
    "capabilitiesPage": "https://docs.harthelm.dev/reference/machine-readable/"
  },
  "releaseChannel": {
    "registry": {
      "host": "registry.harthelm.dev",
      "images": "registry.harthelm.dev/harthelm/<image>:<tag>",
      "chart": "oci://registry.harthelm.dev/harthelm/charts/harthelm",
      "access": "a login with your licence id and registry token"
    },
    "files": {
      "host": "get.harthelm.dev",
      "release": "https://get.harthelm.dev/releases/1.6.0/",
      "sources": "https://get.harthelm.dev/sources/",
      "access": "public HTTPS, no login"
    },
    "signingKey": "https://docs.harthelm.dev/cosign.pub",
    "guide": "https://docs.harthelm.dev/self-hosting/install/get-harthelm/"
  },
  "features": [
    {
      "id": "workspaces",
      "title": "Workspaces",
      "summary": "A workspace: your code on its own volume, the IDE, terminals, plans and visibility.",
      "kind": "concept",
      "group": null,
      "url": "https://docs.harthelm.dev/concepts/workspaces/",
      "markdown": "https://docs.harthelm.dev/concepts/workspaces.md"
    },
    {
      "id": "start-from-a-repository",
      "title": "Start from a repository",
      "summary": "Connect a Git account and create a workspace from a repository and branch.",
      "kind": "guide",
      "group": "Workspaces",
      "url": "https://docs.harthelm.dev/guides/start-from-a-repository/",
      "markdown": "https://docs.harthelm.dev/guides/start-from-a-repository.md"
    }
  ],
  "cli": {
    "name": "hart",
    "reference": "https://docs.harthelm.dev/reference/hart/",
    "install": "https://docs.harthelm.dev/getting-started/install-hart/",
    "commands": [
      {
        "name": "hart ws",
        "group": "Workspaces",
        "summary": "List, create, open, wake and delete workspaces",
        "url": "https://docs.harthelm.dev/reference/hart/ws/",
        "subcommands": [
          "hart ws create",
          "hart ws delete",
          "hart ws list",
          "hart ws open",
          "hart ws purge",
          "hart ws wake"
        ]
      }
    ]
  },
  "references": {
    "openapi": {
      "document": "https://docs.harthelm.dev/openapi.json",
      "openapi": "3.1.0",
      "apiVersion": "0.12.0",
      "page": "https://docs.harthelm.dev/reference/api/",
      "installationPath": "/api/v1/openapi.yaml"
    },
    "harthelmYml": {
      "schema": "https://docs.harthelm.dev/schemas/harthelm.schema.json",
      "id": "urn:harthelm:schema:harthelm-v1",
      "page": "https://docs.harthelm.dev/reference/harthelm-yml/",
      "installationPath": "/api/v1/schemas/harthelm.json"
    },
    "chartValues": {
      "page": "https://docs.harthelm.dev/reference/chart-values/",
      "chart": "oci://registry.harthelm.dev/harthelm/charts/harthelm"
    },
    "releaseNotes": {
      "index": "https://docs.harthelm.dev/releases/",
      "current": "https://docs.harthelm.dev/releases/v1-6-0/"
    }
  }
}
```