Glossary

This page is for developers who meet a word of instruction.md in a tool, a resource, a file or a conversation with the people who use the editor. Each term is listed by the name the API, the CLI and the files use, with what it is, the word people and the editor use for the same thing, and the page that owns it.

It holds 79 terms. 64 of them are the same terms as the glossary in plain words, read from the same list when this page is built, and each has the same anchor on both pages. The others are terms only developers meet.

A

agent (agt_…)

A caller that isn't a person, signing in with an agent credential. It holds publish at most, never manage, and its edits land as suggestions. The word also names coding agents, deployments and the @instruction.md/agents package.

agent credential (agt_…, client credentials)

An agent's client id (agt_…) and secret, for the client-credentials grant at the agents' token URL. Its tokens last five minutes, carry its scopes and never org:admin. Made in Developer ▸ API keys or with instruction agents create.

Agents app (/agents/)

The web app where people see the organization's deployed agents, answer what they ask (deployments_asks_*) and write to them (deployments_messages_*).

assistant

instruction.md's own AI helper in the editor, an OpenAI model that processes requests in the United States. Its changes land as suggestions. The organization policy key assistant turns it off.

audit log

The organization's record of events and reads: who changed, released, shared or read what, and when. It never holds an instruction's text. instructions_audit_query and instructions_audit_export read it; instructions_activity_list gives one instruction's activity.

authored digest, delivered digest

Two sha256:… digests of a document: of the file's bytes, which a signature covers, and of the delivered text, which a follower reports.

B

backmatter

The block at the end of a document that keeps its record: notes, sources, authors and review dates. Never delivered.

  • People say: Notes
  • In the editor: Notes
  • Read more: Backmatter
  • In plain words: Notes

binding (what is followed), consumer (who follows)

A follower reads the version a ref points to and applies it, or pins one version. It declares a binding with instructions_bindings_create (mode follow or pin) and reports what it applied with instructions_bindings_report.

bindings and consumers

The editor's list of who follows an instruction: instructions_consumers_list (readers known from their reads, as live, recent or declared) and the declared bindings, with the version and delivered digest each reported.

C

checkpoint

A copy of the draft the server keeps after 60 seconds without a change, after 5 minutes of continuous editing, and before a replace, a discard, a restore or accepting several suggestions. instructions_checkpoints_create makes one and instructions_restore brings one back. Never delivered.

coding agent (host)

Claude Code, Codex, Cursor and similar tools. A project makes them follow its instruction through hooks (instruction agents hook <host>), a file instruction watch keeps current, or a plugin.

comment thread

A thread on words of the draft (instructions_comments_*). Kept with the draft, never delivered.

consumer, binding

Anything that reads an instruction and applies it. It declares what it follows with instructions_bindings_create (a ref or a pinned version) and reports what it applied with instructions_bindings_report; instructions_consumers_list lists them.

D

default ref (latest)

The version the default ref points to: what instruction://{id} reads when no ref is named, and what a new binding follows. The default ref is latest unless instructions_refs_set with makeDefault made another one.

delivered text (instruction-text/1)

The text a model receives: the body, with parameters, includes and bases resolved, and without the front matter, the backmatter and comments.

deployment rule (dpr_…)

A rule (deployments_rules_create) that selects instructions by project, folder, tags or a list and makes one deployment for each, now and for every instruction that later matches. The runner (instruction agents run --rule) starts their agents.

deployment, deployment rule (dpr_…)

A deployment is one agent for one instruction on a platform. A deployment rule (deployments_rules_create) selects instructions by project, folder, tags or a list and makes a deployment for each; the runner starts them.

developerMode

A person's own preference that shows technical details and the Developer pages in the editor. The organization policy key developerMode is the default for a member who hasn't set it.

draft

An instruction's one shared, editable text, with an integer revision. Tools change it with instructions_draft_edit or instructions_draft_replace, passing expectedRevision; the editor holds it as a Yjs document. Never delivered.

E

edition (instruction/1)

The version of the language a document is read with. spec: "1" in the front matter names the first edition.

Explore (public instructions and templates)

Where public instructions and templates are listed. An instruction whose visibility is public is listed there; templates_list lists the templates.

F

folder (fld_…)

Groups instructions inside a project, and can hold folders (folders_*). Folders don't change access. A deployment rule can select one.

fork (instructions_fork)

Your own copy of an instruction you can read. It keeps its origin, starts with a draft and no versions, and offers changes back as a proposal.

front matter

The YAML block at the top of a document: spec, title, description, parameters and the other keys. Never delivered; its parameters only give values to the body.

G

guest

An organization role that sees only what is shared with it, one instruction at a time, and takes no seat. An open workspace doesn't give guests its default role.

H

hold

A follower's refusal of a version it read, such as an unsigned one when signatures are required. It applies nothing and keeps its last good version.

host, MCP client

An MCP client a person connects as themselves, such as Claude or ChatGPT. Its token carries the scopes the person chose. It acts with the person's role, and a call that needs confirmation asks the person first.

I

idempotencyKey

A string you choose on a create. Sent again with the same key and arguments within 24 hours, the call answers what the first one made.

instruction (ins_…)

A UTF-8 Markdown document read by the first edition of the language (instruction/1), with one shared draft and immutable versions. Its id never changes; its owner/name address can.

instruction agents run

The process that runs an agent for each active deployment of a rule or a platform, each in a folder of its own with its follow file, and reports each with deployments_report.

.instruction/current.md

The text of the last version a hook applied. It is used offline and while a newer version is held, and kept out of git.

.instruction/follow.json

The project file that names what the project's agents follow (follow), with optional requireSignature, keys, url, refreshSeconds, maxInjectChars and apply. Commit it.

instructions_archive

Makes an instruction read-only without deleting it. Its versions are still served, so its followers keep working.

instructions_versions_revoke

Revokes a version no ref points at. It stays readable and marked revoked, no ref can move back to it, and followers pinned to it keep their last good version.

integration (itg_…)

An MCP server, an MCP registry, a GitHub repository of skills, an A2A agent or an API from its OpenAPI document, added to an organization (orgs_integrations_*). Its definitions are pulled in the background and offered while writing, and its tools can be allowed or blocked.

K

key service

An organization's sealing key held by a company proxy (instruction-mcp --http), which opens sealed text for the people it serves. In beta, not yet independently reviewed.

M

manage (instruction, workspace); admin (organization)

On an instruction or a workspace, the Admin role holds the permission manage: share, change visibility, rename, archive, delete and set the default ref. In an organization, admin is a role beside owner, billing, member and guest. Administering an organization over MCP also needs the scope org:admin.

MCP gateway (MCPG)

The MCP server at https://instruction.md/mcp. It speaks MCP 2026-07-28 only, with no sessions, checks tokens and scopes, and serves the tools, resources, prompts and skills.

member (organization role)

The organization role of people who work on its instructions with their workspace roles. A member takes a seat; the other organization roles are owner, admin, billing and guest.

N

needs_confirmation, confirmToken

The first answer of a call that changes what others receive or can't be undone: a summary, its consequences and a token. The call is made only when sent again with the token, within 10 minutes, once.

O

org:admin

The scope that administering an organization takes. Without it, a token doesn't list the organization, billing and insights tools that administer. No agent or service credential can have it.

organization (org_…)

Owns the plan, billing, seats, people, policy, apps, domains, signing keys, integrations and the assistant switch. Its roles are owner, admin, billing, member and guest. Every account has a personal one.

owner (organization role)

The organization role with every right an admin has, plus making other owners (orgs_members_update) and deleting the organization.

P

parameter

A typed value declared in the front matter's parameters, with a default, and inserted where the body names it. Values are given when the text is delivered.

passkey (WebAuthn)

How people sign in, at instruction.md's Keycloak (/auth). There are no passwords. Agents and services sign in with a credential instead.

  • People say: Passkey
  • In the editor: Passkey
  • Read more: Passkeys
  • In plain words: Passkey

pinned version (@ver_…, @vN)

Following one exact version: a binding in pin mode, or an address ending @ver_… or @vN. A pinned follower whose version is revoked keeps its last good one.

plan (billing/plans.json)

What an organization may do and how much: Community, Pro, Team or Enterprise, each with the limits and features of one catalogue. A call past a limit answers limit_reached.

platform

The label of where an organization's agents run, such as agents-box. A deployment rule names a platform, and instruction agents run --platform starts its deployments.

principal

Who a call acts as: a person (usr_…), an agent (agt_…) or a service. Access is granted to principals of type user, agent or org.

private, internal, public

Who reads an instruction's versions: private (Only you), internal (Your organization) or public (Everyone, on the web, and listed in Explore). Over MCP every caller signs in, whatever the visibility.

project (prj_…)

A group of instructions in a workspace, which can hold folders (projects_*). A deployment rule can select one.

proposal

A whole text offered to an instruction (instructions_proposals_*), with a title, a rationale, a diff against the version it was based on, and reviews. A Maintainer merges it as a new version; an author never approves their own.

publish

The role whose permission is publish: edit the draft, accept suggestions, release and move refs. Agents hold publish at most.

publisher key (org_…-N)

An organization's Ed25519 signing key, derived by the server. Rotated, retired and revoked with orgs_keys_*, and listed in the organization's keys.json.

R

read

The role whose permission is read: it reads and changes nothing.

A signed link that reads one version or a ref without an account, until it expires or is revoked with instructions_links_revoke.

recovery code

One of a set of single-use codes a person gets with their first passkey. Signing in with one makes them set a new passkey and get new codes.

ref

A name that points at one version and can move: latest, stable or any other slug. Agents follow refs, so moving one changes what they get.

ref policy

A ref's policy, which every move must pass: requireSignature, requireChecks, allowedPublishers and promote. instruction refs <id> gate REF sets it from flags.

refs: [] (a quiet release)

instructions_publish with refs: [], or instruction publish --quiet. It moves no ref, so nobody following a ref gets it until a ref is moved there.

release (instructions_publish)

Makes the next version from the draft's accepted text, and moves the default ref unless refs says otherwise. It is refused when the text has errors or equals the latest version.

revision, expectedRevision

The draft's integer revision, which goes up with each change. An edit names the revision it was made on, and is refused with version_conflict when the draft moved since.

rule (keyword line)

A line that starts with a rule keyword: MUST, MUST NOT, NEVER, SHOULD, SHOULD NOT, AVOID, MAY, ALWAYS or GUARDRAIL. BECAUSE gives the reason.

S

scope

What a token may list and call: instructions:read, instructions:write, instructions:publish, instructions:admin, instructions:follow, and org:admin. A scope never widens what the caller's role allows.

sealed (end-to-end encrypted)

A sealed workspace's text is encrypted on its people's devices, or in a company proxy, and the server stores only ciphertext, as imd-seal/1 envelopes. In beta, not yet independently reviewed.

seat

A paid place for one person in an organization. Guests and agents take none.

  • People say: Seat
  • In the editor: Seats
  • Read more: Plan limits
  • In plain words: Seat

signed release

Every version that isn't sealed is signed with the organization's publisher key: Ed25519, a JWS over the authored digest. The keys are published at instruction://pub/{owner}/keys.json.

stable ref

A ref you create with instruction refs <id> set stable <version>. It is never made for you, and it moves only when you or its gates move it.

subscriptions, events

Being told of a change: subscriptions/listen on an instruction:// address, or the events md.instruction.activity and md.instruction.releases by stream, poll or webhook. Some plans limit how many consumers hold them at a time; reading is never limited.

suggest

The role whose permission is suggest: read versions, suggest changes and comment.

suggestion

A marked change in the draft (instructions_suggestions_*). A Contributor's or an agent's edits, and an edit sent with asSuggestion, land as suggestions. Only accepted text is released.

T

template

An instruction of kind template, listed by templates_list. instructions_create with templateId copies its text, and the copy doesn't change when the template does.

toolset

A group of the server's tools, such as core, author, review, versions, share, consume and org, named on each tool in the tool reference.

typed reference

A reference in the text to exactly one person, tool, skill, rule or parameter. The editor writes one when you type @, &, # or $ and pick from the list.

V

version (front-matter key)

A string the author writes in the front matter, such as "2.3". A release doesn't read, change or require it; published versions are numbered v1, v2 by the service.

version (ver_…)

An immutable release of the draft: its id, its number (v1, v2…), a message, its author, its authored digest and its signature. It is not the front matter's version, which is the author's label.

versions and checkpoints

An instruction's published versions (instructions_versions_list, instructions_versions_read) and its draft's checkpoints, compared with instructions_diff and brought back with instructions_restore.

W

workflow (instruction/workflow)

A :::workflow block in the instruction/workflow dialect: named, typed steps with triggers, data flow, human decisions and waits. instruction.md checks and draws it, and never runs it.

workspace (ws_…)

Holds instructions, projects and folders inside an organization. It is open, restricted or sealed, and its roles are Reader, Contributor, Maintainer and Admin.

Terms that are easy to mix up

These terms The difference
draft, checkpoint, version The draft is the one editable text. A checkpoint is a copy of the draft the server keeps for the people who edit it. A version is an immutable release, and the only one of the three a follower reads.
ref, default ref, pinned version A ref is a name that moves. The default ref (latest unless changed) is what an address with no ref reads. A pinned version never moves.
release, publish The same act, instructions_publish. These pages say release; the editor says Publish.
signed, sealed Signed says who released a version. Sealed says who can read its text. A sealed version has no platform signature.
binding, consumer A binding is what a follower declares it follows (instructions_bindings_create). A consumer is who reads, known from its reads (instructions_consumers_list).
role, permission, scope A role (Reader, Contributor, Maintainer, Admin) maps to a permission (read, suggest, publish, manage). A scope limits what a token may call, and never widens the role.
organization, workspace The organization owns the plan, people, policy and keys. A workspace holds the instructions.
suggestion, comment, proposal A suggestion is a marked change in the draft. A comment is a thread, never delivered. A proposal is a whole text offered from a fork, merged as a new version.
agent, coding agent, deployment An agent is a principal with an agent credential. A coding agent is a tool such as Claude Code. A deployment is one agent the runner starts for one instruction.
front matter version, version The front matter's version is the author's label. A version (ver_…, v1, v2…) is what the server releases.

Last checked against the product:

Was this page helpful? Report a problem