# Gramit for AI assistants

Gramit (https://gramit.io) is a free browser diagram editor whose boards are also a small
YAML language, **Gramit Code**. You write the YAML, the user opens a link, the diagram is
there. No account, nothing to install.

This page is the index. It carries enough to write a working diagram, and points at the
four resources that answer everything else. Fetch what the task needs; there is no reason
to read all of it.

---

## The smallest valid document

```yaml
template:
  name: Deploy pipeline    # optional
  theme: dark              # light | dark
  style: clean             # clean (precise) | handmade (sketchy)

root:                      # required: the main diagram
  nodes:
    - name: build          # the id, unique across the whole document
      text: Build          # the visible label
    - name: test
      text: Test
    - name: gate
      type: decision       # diamond
      text: Green?
      stroke: '#f59e0b'
    - name: ship
      text: Ship
      color: '#14342b'
      stroke: '#16a34a'
  edges:
    - from: build
      to: test
    - from: test
      to: gate
    - from: gate
      to: ship
      text: "Yes"
```

That is the whole shape of the language: a `template`, a required `root` flow of `nodes`
and `edges`, and any other top-level key is a **subflow**, a nested diagram that opens as
its own level when a node names it with `subflow:`.

Six rules cover most of what goes wrong:

1. `name` is the node id and must be unique across the whole document, subflows included.
   `text` is what the reader sees.
2. Edges reference nodes by `name`. Both ends must exist.
3. Node types: `simple` (default), `circle`, `decision`, `text`, `person`, `icon`,
   `image`, `code`, `frame`, `table`. Each type allows a different set of properties, and anything
   outside that set is rejected.
4. Quote hex colors (`'#3b82f6'`). Unquoted, `#` starts a YAML comment and the value is
   gone.
5. Positions are computed for you. Say `direction: LR` or `TB` in the template if you
   care which way the diagram runs.
6. Nothing renders until the whole document is valid.

---

## The four resources

| Resource | Fetch it when |
|----------|---------------|
| https://www.gramit.io/docs/ai/language | You need the full reference: every type, every property, frames, subflows, style defaults. |
| https://www.gramit.io/docs/ai/schema.json | You want to check the document you just wrote. JSON Schema, generated from the editor's own validator. |
| https://www.gramit.io/docs/ai/icons?q=lambda | A node is `type: icon` and needs an id. Searchable, a few thousand of them, and guessing does not work. |
| https://www.gramit.io/docs/ai/examples | You would rather adapt a complete working document than assemble one. |

Human documentation, with live previews: https://www.gramit.io/docs

---

## Delivering the diagram

Hand the user a link that opens the board, not a block of YAML and instructions on where
to paste it. Base64 the document (UTF-8, standard base64) and put it in the fragment:

```
https://gramit.io/new#code=<base64 of the YAML>
```

```python
import base64
url = "https://gramit.io/new#code=" + base64.b64encode(yaml_text.encode()).decode()
```

Opening it renders the diagram and saves it as a new board in that browser's gallery.
Base64 is what keeps the link intact: raw YAML is full of newlines, `#`, `:` and `|`, and
chat clients cut a link at the first character they dislike. The fragment never reaches a
server, so the board stays between you and the person you sent it to.

Show the YAML alongside the link for anyone who wants to read it. If a link is not usable
where you are, the manual route still works: open https://gramit.io, then
**Menu -> Code to Diagram**, and paste the YAML in.