# The Card on the Desk

## A name that means a promise

Under api-spec.md is something simple: a written promise about how one thing may speak to another. The first part names a shared way of asking. The second part is the careful description of that way. Even the short ending of the name suggests the promise should stay close to ordinary language, so a person can read it without a special key.

## The library card

Think of the small card at a library desk. It lists the hours, what you may borrow, and how to ask. You do not need the map of every shelf. You need a clear request and a clear reply. A specification works the same way between programs and, if we are honest, between people. It lets cooperation happen without forcing anyone to show their whole inner room.

## What we choose to write down

A good agreement is short enough to keep and specific enough to trust. It does not try to explain the entire world. It names the doors, the questions welcome at each one, and the answers you can expect.

- Name only what you can stand behind.
- Use words a newcomer could follow.
- Leave the other side free to be built differently from you.

On 27 October 2026, that ideal still feels quiet and necessary. We add more connections every year. The humane response is not more noise. It is a page someone can return to when they are unsure, and find that the important names have not changed overnight.

*A clear promise is a kindness you can reread.*