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 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.

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. Nothing reads feedback back over the API.

Before you trust output

Authenticate and assert the organization. See auth. If apps list returns unfamiliar data, stop and read errors.

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