# Yantrik Labs — field guide for agents

Yantrik Labs makes **yantras**: desktop applications that can describe and
accept operations through [yell](https://yantriklabs.xyz/school/), a shell for
GUI applications. This page is the canonical machine-readable starting point
for an agent operating a Yantrik desktop.

Canonical site: `https://yantriklabs.xyz/`  
Machine index: `https://yantriklabs.xyz/llms.txt`

## Install Kosh

Kosh is the store for yantras. On supported Linux `x86_64` systems it installs
into the user's home directory, adds `~/.local/bin/kosh`, and needs neither
root nor a package manager.

An agent must choose an action explicitly. The no-argument installer is
interactive and intentionally does **nothing** when there is no terminal to
answer its menu.

```sh
# Inspect the install without changing the machine.
curl -fsSL https://yantriklabs.xyz/yantra.sh | sh -s -- install-dry

# Install or replace Kosh with the current release.
curl -fsSL https://yantriklabs.xyz/yantra.sh | sh -s -- install

# Update an already-installed Kosh only; it refuses when Kosh is absent.
curl -fsSL https://yantriklabs.xyz/yantra.sh | sh -s -- rotate
```

Open Kosh after installation and use its visible **Install** or **Update**
control for a yantra. Do not guess a Kosh command name. When Yell is available,
ask Kosh what it supports first:

```yell
list @kosh
help @kosh
take_snapshot @kosh
```

Then use the app-specific command returned by `help @kosh`, or interact with a
current element fingerprint from `take_snapshot`. Installing software, updating
software, signing in, and granting access are consequential actions: obtain the
operator's instruction before performing them.

The bootstrap installs Kosh, not Yell. See the local Yantrik deployment or the
Yantrik School for how Yell is supplied in a particular environment.

## Learn YellScript

Yell drives **desktop GUI yantras only**. It does not administer backend
services. Start a Yell session with `yell`, then discover live windows and their
own vocabulary:

```yell
# Discover local yantras. This reads discovery records and dials nothing.
list

# Ask a named yantra which app-specific commands it exposes.
help @kosh

# Read its current UI tree. Each actionable element has a 64-hex fingerprint.
take_snapshot @kosh
```

The order is always `verb @yantra arguments`; an address never comes first.
Use the fingerprint from the latest snapshot, not screen coordinates:

```yell
click @kosh 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

# `ux` invokes an app's own command. Its valid names and arguments come from
# `help @kosh`; this is only the command shape.
ux @kosh command_name key=value
```

Useful read-only and diagnostic operations:

```yell
version
list
help @gitsea-desk
take_snapshot @gitsea-desk
read_console @gitsea-desk
report /tmp/yantrik-desk-report.json
```

Yell's UI-driving operations include `click`, `fill`, `type_text`, `press_key`,
`drag`, `scroll_into_view`, and `ux`. Inspect first; operate only on a current
snapshot; confirm before actions that install, update, delete, authenticate, or
send data.

## Runbooks

A Yell runbook is ordinary Markdown. Only fenced blocks marked `yell` execute;
all prose is documentation. For example:

````markdown
# Check Kosh before touching it

```yell
list @kosh
help @kosh
take_snapshot @kosh
```
````

Validate a runbook without operating any yantra, then execute it only when its
effects are approved:

```sh
yell check runbook.md
yell runbook.md
```

## Reference

- [Yantrik School](https://yantriklabs.xyz/school/) — practical first course.
- [Yell reference card](https://yantriklabs.xyz/school/reference.html) — every
  command and its grammar.
- [Kosh installer](https://yantriklabs.xyz/yantra.sh) — inspect the exact script
  before executing it.

This document favors live discovery over hard-coded UI assumptions. Run
`help @yantra` and `take_snapshot @yantra` again whenever an app has changed.