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.
- People say: Agent
- Read more: Concepts: Agents
- In plain words: Agent
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.
- People say: Agent credential
- In the editor: API keys
- Read more: Agent credentials
- In plain words: Agent credential
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_*).
- People say: Agents app
- In the editor: Agents
- Read more: Conversations: how the runner relays them
- In plain words: Agents app
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.
- People say: Assistant
- In the editor: Assistant
- Read more: Privacy: the assistant
- In plain words: Assistant
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.
- People say: Activity log
- In the editor: Activity
- Read more: Export the audit trail
- In plain words: Activity log
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.
- Read more: Concepts: Documents
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.
- People say: Follow
- In the editor: Follow in your coding agent…
- Read more: How following works
- In plain words: Follow
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.
- People say: Agents card
- In the editor: Agents
- Read more: Concepts: Followers
- In plain words: Agents card
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.
- People say: Checkpoint
- In the editor: Checkpoint
- Read more: Concepts: Drafts
- In plain words: Checkpoint
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.
- People say: Coding agent
- Read more: Other coding agents
- In plain words: Coding agent
comment thread
A thread on words of the draft (instructions_comments_*). Kept with the draft, never delivered.
- People say: Comment
- In the editor: Comment
- Read more: Concepts: Suggestions, comments, proposals and forks
- In plain words: Comment
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.
- People say: Follower
- In the editor: Agents
- Read more: Concepts: Followers
- In plain words: Follower
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.
- People say: Live
- In the editor: Live
- Read more: Concepts: Refs
- In plain words: Live
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.
- Read more: What an agent receives
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.
- People say: Deployment rule
- In the editor: Run every instruction here on…
- Read more: Rules over MCP
- In plain words: Deployment rule
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.
- People say: Deployment
- In the editor: Deploy to…, Run every instruction here on…
- Read more: The runner (instruction agents run)
- In plain words: Deployment
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.
- People say: Developer mode
- In the editor: Developer mode
- Read more: Policy and roles
- In plain words: Developer mode
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.
- People say: Draft
- In the editor: Draft
- Read more: Concepts: Drafts
- In plain words: Draft
E
edition (instruction/1)
The version of the language a document is read with. spec: "1" in the front matter names the first edition.
- Read more: Editions
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.
- People say: Explore
- In the editor: Explore
- Read more: Concepts: Visibility and access
- In plain words: Explore
F
folder (fld_…)
Groups instructions inside a project, and can hold folders (folders_*). Folders don't change access. A deployment rule can select one.
- People say: Folder
- In the editor: Folder
- Read more: Concepts: Organizations and workspaces
- In plain words: Folder
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.
- People say: Fork
- In the editor: Fork — a copy of your own
- Read more: Concepts: Suggestions, comments, proposals and forks
- In plain words: Fork
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.
- People say: Details
- In the editor: Details
- Read more: Front matter and backmatter
- In plain words: Details
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.
- People say: Guest
- In the editor: Guest
- Read more: Concepts: Organizations and workspaces
- In plain words: Guest
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.
- Read more: Holds
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.
- People say: AI app
- In the editor: Connected apps
- Read more: Connect an MCP client
- In plain words: AI app
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.
- Read more: Idempotency keys
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.
- People say: Instruction
- In the editor: Instruction
- Read more: Concepts: Documents
- In plain words: Instruction
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.
- People say: Runner
- Read more: The runner (instruction agents run)
- In plain words: Runner
.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.
- Read more: Keep the last good version
.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.
- People say: Follow file
- Read more: follow.json
- In plain words: Follow file
instructions_archive
Makes an instruction read-only without deleting it. Its versions are still served, so its followers keep working.
- People say: Archive
- In the editor: Archive
- Read more: Tool reference
- In plain words: Archive
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.
- People say: Revoke
- In the editor: Revoke…
- Read more: Revoke a version
- In plain words: Revoke
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.
- People say: Integration
- In the editor: Integrations
- Read more: Integrations
- In plain words: Integration
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.
- Read more: Run the company proxy
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.
- People say: Admin
- In the editor: Admin
- Read more: Concepts: Visibility and access
- In plain words: 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.
- Read more: Concepts: Architecture
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.
- People say: Member
- In the editor: Member
- Read more: Organization roles
- In plain words: Member
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.
- Read more: Needs confirmation
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.
- Read more: org:admin
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.
- People say: Organization
- In the editor: Organization
- Read more: Concepts: Organizations and workspaces
- In plain words: Organization
owner (organization role)
The organization role with every right an admin has, plus making other owners (orgs_members_update) and deleting the organization.
- People say: Owner
- In the editor: Owner
- Read more: Organization roles
- In plain words: Owner
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.
- People say: Parameter
- In the editor: $
- Read more: Parameters
- In plain words: Parameter
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.
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.
- People say: Pin
- In the editor: Only v4
- Read more: Refs and versions
- In plain words: Pin
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.
- People say: Plan
- In the editor: Your plan
- Read more: Rate and size limits
- In plain words: Plan
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.
- People say: Machine
- In the editor: Where they run
- Read more: The runner (instruction agents run)
- In plain words: Machine
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.
- Read more: Concepts: Visibility and access
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.
- People say: Visibility
- In the editor: Only you, Your organization, Everyone
- Read more: Concepts: Visibility and access
- In plain words: Visibility
project (prj_…)
A group of instructions in a workspace, which can hold folders (projects_*). A deployment rule can select one.
- People say: Project
- In the editor: Project
- Read more: Concepts: Organizations and workspaces
- In plain words: Project
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.
- People say: Offered changes
- In the editor: Offer changes
- Read more: Concepts: Suggestions, comments, proposals and forks
- In plain words: Offered changes
publish
The role whose permission is publish: edit the draft, accept suggestions, release and move refs. Agents hold publish at most.
- People say: Maintainer
- In the editor: Maintainer
- Read more: Concepts: Visibility and access
- In plain words: Maintainer
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.
- Read more: Publisher keys
R
read
The role whose permission is read: it reads and changes nothing.
- People say: Reader
- In the editor: Reader
- Read more: Concepts: Visibility and access
- In plain words: Reader
read link (instructions_links_create)
A signed link that reads one version or a ref without an account, until it expires or is revoked with instructions_links_revoke.
- People say: Read link
- In the editor: Read links
- Read more: Tool reference
- In plain words: Read link
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.
- People say: Recovery code
- In the editor: Recovery codes
- Read more: Recovery codes
- In plain words: Recovery code
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.
- People say: Version name
- In the editor: latest, stable
- Read more: Concepts: Refs
- In plain words: Version name
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.
- People say: Publish gates
- In the editor: Publish gates…
- Read more: Concepts: Refs
- In plain words: Publish gates
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.
- People say: Quiet version
- In the editor: Make it live — agents switch to it
- Read more: Concepts: Versions
- In plain words: Quiet version
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.
- People say: Publish
- In the editor: Publish
- Read more: Concepts: Versions
- In plain words: Publish
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.
- Read more: Expected revisions
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.
- People say: Rule
- In the editor: Rule
- Read more: Rule keywords
- In plain words: Rule
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.
- Read more: What a person lets a host do
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.
- People say: Sealed
- In the editor: Sealed
- Read more: Sealed instructions for developers
- In plain words: Sealed
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.
- People say: Signed
- Read more: Signing and verification
- In plain words: Signed
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.
- People say: Stable
- In the editor: stable
- Read more: Concepts: Refs
- In plain words: Stable
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.
- People say: Live updates
- Read more: Live updates, events and webhooks
- In plain words: Live updates
suggest
The role whose permission is suggest: read versions, suggest changes and comment.
- People say: Contributor
- In the editor: Contributor
- Read more: Concepts: Visibility and access
- In plain words: Contributor
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.
- People say: Suggestion
- In the editor: Suggestion
- Read more: Concepts: Drafts
- In plain words: Suggestion
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.
- People say: Template
- Read more: Tool reference
- In plain words: Template
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.
- Read more: 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.
- People say: Mention
- In the editor: @, &, #, $
- Read more: References and links
- In plain words: Mention
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.
- People say: Version label
- Read more: The version label and published versions
- In plain words: Version label
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.
- People say: Version
- In the editor: v1, v2…
- Read more: The version label and published versions
- In plain words: Version
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.
- People say: History
- In the editor: History
- Read more: Concepts: Versions
- In plain words: History
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.
- People say: Workflow
- In the editor: Workflow
- Read more: Workflow node reference
- In plain words: Workflow
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.
- People say: Workspace
- In the editor: Workspace
- Read more: Concepts: Organizations and workspaces
- In plain words: Workspace
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. |