> For the complete documentation index, see [llms.txt](https://docs.khotan.com/llms.txt). A markdown version of any page is available at its `index.md` URL.

# Agents

Use these docs as the teaching surface. Use `khotan help` as the source of
truth.

## Read docs this way

1. Fetch `https://docs.khotan.com/llms.txt`.
2. For a command domain, fetch `https://docs.khotan.com/cli/commands/<domain>/index.md`. The domains are `apps`, `pipelines`, `files`, `context`, `integrations`, `databases`, `redis`, `buckets`, `folders`, `projects`, `organization`, `feedback`.
3. Do not scrape HTML. Every page has a Markdown twin at `index.md`.
4. `https://docs.khotan.com/llms-full.txt` is the whole documentation set in one request.
5. `https://docs.khotan.com/docs.json` is the structured manifest with per-page headings, for jumping to an anchor without fetching the page.

## Look something up

`https://docs.khotan.com/search.json?q=<query>` returns ranked pages with matching heading anchors and a snippet each. Use it instead of fetching `llms-full.txt` and scanning, unless you genuinely want the whole corpus. Omit `q` to get the full page index.

Scoped indexes, when you only care about one surface:

- `https://docs.khotan.com/cli/llms.txt` — CLI pages only.
- `https://docs.khotan.com/api/llms.txt` — HTTP API pages only.

## Calling the API directly

The CLI wraps `/api/v1` and adds no capability the API lacks, so prefer the CLI unless you need raw HTTP. If you do:

1. Read [HTTP API](/api/) for authentication, the error envelope, and rate limits.
2. Fetch `https://docs.khotan.com/api/<resource>/index.md` for a resource group's operations.
3. Generate clients from `/api/v1/openapi.json` on your workspace origin. That document is the contract; the docs pages summarize it and omit nested response schemas.

## Send feedback to Khotan

When Khotan lacks something you needed, or you see a better way Khotan, its templates, skills, or design docs could work, tell the Khotan team with `khotan feedback submit`. Send it even when a workaround got the job done, then carry on with your task.

```sh
khotan feedback submit --kind feature_request --origin agent \
  --title "Append a section to DESIGN.md" \
  --proposal "An action that appends a section to a repository's DESIGN.md" \
  --situation "A user asked me to document empty states. I found no append action." \
  --reason "I rewrote the whole file, which risks losing their edits."
```

- `--kind` is `feature_request`, `direction`, `docs_gap`, `bug`, or `other`.
- `--origin` is `user` when a person asked you to send it, and `agent` when you decided to.
- `--situation` is your task, its goal, and what you tried. `--reason` is what you did instead, and what the change would let you or your user do.
- `--thread-id` records your own chat or session id. `--impact`, `--area`, `--capability-ids`, `--model`, and `--client` are optional.
- Cover one topic in each. Use placeholders such as `<customer>` for names, emails, and customer data, and never include a credential.

Any API key can send feedback, including a read-only one. Over HTTP it is `POST /api/v1/feedback`; see [Feedback](/api/feedback/). Nothing reads feedback back over the API.

## Before you trust output

Authenticate and assert the organization. See [auth](/cli/auth/). If `apps list` returns unfamiliar data, stop and read [errors](/cli/errors/).

Never invent flags. Never commit an API key. Destructive commands need `--yes` when there is no TTY.