# gloss: make a nanoapp for someone

**If you're an LLM and someone asked you to build them a small shared app
(a football pool, a potluck sign-up, a chore chart), this page tells you how.**
We call these **nanoapps**.

gloss is where you write the nanoapp. You don't write code: you write an
**aide**, a short YAML spec of the nanoapp's data, what people can do, and the rules. gloss
checks it, keeps every version, and publishes it. Once published, the nanoapp has a
page, and each person gets their own link. They use it by typing plain messages
("eagles and commanders", "I'll bring salad"), which are matched to the nanoapp's
commands, checked against its rules, and confirmed by the person.

## What you'll do

1. **Interview the person you're building for.** They're usually the
   nanoapp's **organizer**, who runs it once it's live; you're its **author**,
   and the people who use it are **participants**. What is it for, who uses
   it, and what do people need to do? Get dates with their time zone. Keep their request word for word:
   it goes into the aide.
2. **Read the authoring kit:** [https://gloss.bantay.co/kit](https://gloss.bantay.co/kit). It has the aide
   format, the design rules, how to write checks, and a complete worked example.
   Read all of it before writing anything.
3. **Write the aide**, starting from the kit's example.
4. **Validate until it's clean.** Errors block publishing; warnings are design
   problems. Fix both, and make every check pass. Don't publish with a warning
   you haven't fixed unless you tell them exactly which one and why. A
   warning that a time "is already in the past" means the nanoapp would open
   closed: ask for new dates.
5. **Save it to gloss.** Every save is a version; drafts with errors are kept.
6. **Publish.** The first publish creates the nanoapp and returns its
   **invite link**, the organizer's link, and a read-only guest link. Later publishes update it in
   place, keeping people's data. Only the author, through gloss, changes the
   aide; the organizer runs the nanoapp but can't edit it.
7. **Hand over the invite link.** Tell the person to post it in their group
   chat: each person taps it, types their name, and gets their own link. (Use
   `add_participant` only for someone who isn't in the chat.) Give them the
   organizer link too, for themselves.
8. **Try it as them.** `try_message` sends a message as a person ("eagles and
   bears" as Lola) and shows what the nanoapp would do and what the rules say,
   without applying anything. Try the main thing people will do, a change of
   mind, something the rules should refuse, and a deadline. If it doesn't
   behave, fix the aide, save, and publish again.
9. **Tell them** what you built, in plain words: what people can do, what
   you couldn't express (`unmet`), and anywhere you interpreted their words.

## No gloss tools? (ChatGPT, Gemini, a plain chat)

You can still build it; the person publishes it on one page. Do steps 1–3
above, then:

- **The format is exact.** Open [https://gloss.bantay.co/kit](https://gloss.bantay.co/kit) and read all of
  it before writing anything, then start from its worked example. Rules are
  `{ level: MUST, when: "<condition>", else: "<message>" }` and checks are
  steps that run (`{ do: pick, with: { team: Eagles }, expect: ok }`), never
  sentences. gloss rejects an aide written any other way.

- **Dates:** for each one, open
  `https://gloss.bantay.co/time?local=2026-11-10 23:59&zone=America/Chicago` (or compute it
  with code). Never work out epoch milliseconds in your head.
- **End your answer with** the complete aide in one YAML code block, and then these words, filled in: *"Copy the aide above, open
  **https://glossier.bantay.co/new**, paste it, enter **‹name›** as the name and **‹Ana, Ben…›**
  as the people, and press Publish."*
- **If you can run code**, also give a link that fills all of that in:
  `https://glossier.bantay.co/new#aide=‹aide›&name=‹name›&people=‹Ana,Ben›`, each value
  URI-encoded (`encodeURIComponent`, or `urllib.parse.quote(value, safe="")`).
  Build it with code; never encode by hand.
- The page checks the aide before it can publish. If it shows errors or
  warnings, the person pastes them back to you: fix the aide and give the
  whole thing again.
- Once it's live, the page lets them try it as someone. Tell them what to
  try: the main thing people will do, a change of mind, something the rules
  should refuse, and something after a deadline.

## Be honest about what you built

The validator checks that your aide is consistent. It can't check that it's
what they asked for. So:

- Put their request in the aide **verbatim**, under `request:`.
- Every requirement **quotes** it, and every sentence of it is quoted by some
  requirement. Prove each one with a check, or mark it `unmet:` with the reason,
  or `info:` if it's context rather than behavior.
- Never drop a requirement because it's hard. Never paraphrase one.
- When you're done, **try the nanoapp the way people will** with `try_message`, and
  read the live state with `get_live_nanoapp`. Look at the page as a person would:
  if they asked to *see* something (vote counts, who's bringing what), make
  sure it's actually in the state, not just derivable from it. Checks written against a wrong date,
  or a wrong assumption, pass anyway; a closed or broken nanoapp is not done, even
  if every check passes. Say so instead of reporting success.

## Connect over MCP (preferred)

gloss is an MCP server (Streamable HTTP):

- **Endpoint:** `https://glossier.bantay.co/mcp`
- **Auth:** OAuth. Your MCP client discovers it from the endpoint and opens a
  sign-in page, where the person you're building for signs in with their email
  (gloss sends a code) and approves the connection, once. Their aides are
  theirs: the client sees and changes only those.

| Tool and arguments | What it does |
|---|---|
| `get_authoring_kit()` | The kit: same as [/kit](https://gloss.bantay.co/kit). |
| `validate_aide(aide)` | Check an aide without saving: errors, warnings, checks, requirements. |
| `time(local, zone)` | `"2026-11-10 23:59"` in `"America/Chicago"` → epoch ms, daylight saving handled, read back in words. Use it for every date. |
| `create_aide(name, aide, note?)` | Start a new aide (version 1). Returns its `id`. |
| `save_aide(id, aide, note?)` | Save a new version. |
| `get_aide(id, version?)`, `list_aides()`, `list_versions(id)` | Read what's there. |
| `publish(id, version?)` | Publish a version. Refused if it has errors. |
| `add_participant(id, name)` | One participant's link, by name — for someone not in the group chat. Everyone else joins through the invite link. |
| `try_message(id, as, text, role?)` | Send `text` as the person named `as` (a participant, or `role: "organizer"` for organizer-only commands), and see what it would do. Nothing is applied. |
| `get_live_nanoapp(id)` | The published nanoapp's state, version, participants, and invite link, right now. |

Arguments are by name, exactly as above (`?` means optional); a wrong or
missing one is refused with the right signature. `tools/list` returns the full
schemas.

You never see the nanoapp's credentials; gloss keeps them and publishes for
you.

**Without an MCP client**, you can still read the kit and validate:
`POST https://gloss.bantay.co/validate` with `{"aide": "<the YAML>"}`. When the aide is clean,
send the person to `https://glossier.bantay.co/new` to publish it (see above).

## For people: connect your LLM to gloss

- **Claude (claude.ai or the desktop app):** Settings → Connectors → Add custom
  connector, with the URL `https://glossier.bantay.co/mcp`. Connect, and sign in with your email
  on the page that opens.
- **Claude Code:** `claude mcp add --transport http gloss https://glossier.bantay.co/mcp`, then
  run `/mcp`, choose gloss, and authenticate in the browser.
- **Any MCP client** with remote servers: add `https://glossier.bantay.co/mcp`; it signs in the
  same way.
- **Any chat, nothing to set up (ChatGPT, Gemini…):** say *"Read https://gloss.bantay.co/guide and
  make me a nanoapp: ‹what you want›"*. It ends with an aide; paste it into
  [https://glossier.bantay.co/new](https://glossier.bantay.co/new), sign in with your email, and press Publish.

Then ask it something like: *"Make a family football pool for this week's
games. Everyone picks a winner for each game; picks lock at kickoff."*

## Links

- This page as plain text for LLMs: [https://gloss.bantay.co/llms.txt](https://gloss.bantay.co/llms.txt)
- The authoring kit: [https://gloss.bantay.co/kit](https://gloss.bantay.co/kit)
- Validate an aide: `POST https://gloss.bantay.co/validate`
- Publish an aide without MCP: [https://glossier.bantay.co/new](https://glossier.bantay.co/new)
- Convert a local time: `GET https://gloss.bantay.co/time?local=2026-11-10 23:59&zone=America/Chicago`
- MCP: `https://glossier.bantay.co/mcp`