The model
An instruction is a Markdown document with a shared draft and a list of immutable versions. Named refs point at those versions, and agents follow a ref. This page defines each object as the MCP server's tools and resources name it, so you can read the tool reference without guessing.
Documents
A document is UTF-8 Markdown read by the first edition of the language (instruction/1). Front matter is optional. When it is there, spec: "1" names the edition, and keys such as title and parameters describe the document. A line that starts with a rule keyword (MUST:, SHOULD:, NEVER: and the others) is a rule. A block fenced with a kind (:::context, ::person{…}) is guidance, a declaration or data. Comments, the front matter and the back matter are never delivered to a model.
Each document has two digests, both sha256:…:
- The authored digest is the SHA-256 of the file's bytes.
instruction digest <file>prints it, and an author signature covers it. - The delivered digest is that of the text a model receives (instruction-text/1), after parameters, includes and bases are resolved. A follower reports it.
The language itself is in the Language reference and, normatively, in the specification.
Drafts
Every instruction has one draft, shared by everyone who may edit it. The editor holds it as a Yjs document (instructions_draft_sync), so several people type into it at once. Tools change it with instructions_draft_edit (precise operations) or instructions_draft_replace (a whole new text).
- Revision. The draft has an integer revision that goes up with each change. An edit says which revision it was made on (
expectedRevision). If the draft moved since, the edit is refused withversion_conflict: read it again and redo the change. - Suggestions. An edit by a Contributor or an agent, or one sent with
asSuggestion, lands as a suggestion: marked text a Maintainer accepts or rejects. Only the accepted text is released. - Checkpoints. The server keeps a checkpoint of the draft after 60 seconds without a change, or after 5 minutes of continuous editing. It also keeps one before a replace, a discard, a restore, a release, or accepting or rejecting several suggestions at once.
instructions_restoreputs a checkpoint's or a version's text back.
Versions
instructions_publish releases the draft's accepted text as the next version: v1, v2 and so on. A version never changes. It has an id (ver_…), a number, a message, its author, its authored digest and, when the server signs (it does on instruction.md), an author signature. Releasing a text that has errors is refused. Releasing a text equal to the latest version is refused with conflict.
"Release" on these pages and "publish" in the editor are the same act.
Plans Community 200 · Pro 1,000 · Team 10,000 · Enterprise unlimited
- Quiet version. A release with
refs: [](instruction publish --quiet) moves no ref, so nobody following a ref gets it until you move one there. The first release always moves the default ref, whateverrefssays. - Schedules.
instructions_schedules_createreleases the draft, or moves a ref, at a set time from one minute to 90 days ahead. It asks for confirmation when you create it, because nobody is asked when it runs.instructions_schedules_cancelcancels it. - Revocation.
instructions_versions_revokerevokes a version no ref points at. It stays readable and marked revoked. No ref can be moved back to it, and followers pinned to it hold their last good version.
Refs
A ref is a name that points at one version. Agents follow refs, so you change what they run by moving a ref, and roll back by moving it to an older version.
- latest exists from the first release and is the default ref. A release moves the default ref unless
refssays otherwise. - The default ref is what
instruction://{id}reads when no ref is named, and what a new binding follows.instructions_refs_setwithmakeDefault: truemakes another ref the default. That needs manage and asks for confirmation. - stable is never created for you. Create it with
instruction refs <id> set stable v1(instructions_refs_set), and move it the same way. Any other name that fits the slug grammar works the same, such asbeta. - Moving the default ref asks for confirmation, because its followers switch. Moving another ref doesn't ask.
latestand the default ref can't be deleted. Deleting another ref leaves its followers on their last version.
Ref gates
A ref can carry a policy that every move must pass. instructions_refs_set with policy replaces the whole policy; instruction refs <id> gate REF … sets it from flags, at the version the ref points at. Moving a ref needs publish; changing its gates without moving it needs manage.
| Key | Type | Effect |
|---|---|---|
requireSignature |
boolean | The ref takes only signed versions. |
requireChecks |
boolean | The ref takes only versions whose server checks passed (instructions_checks_run). |
allowedPublishers |
list of ids (usr_…, agt_…), at most 100 |
Only these principals may move the ref. |
promote |
{ from, afterMinutes } |
The ref follows another ref: once a version there has stood for afterMinutes (default 60, at most 43,200) and passes the other gates, the server moves this ref to it. Only a person can set a promotion; it then runs as that person. |
{
"instructionId": "acme/support-agent",
"ref": "stable",
"versionId": "v3",
"policy": {
"requireChecks": true,
"requireSignature": true,
"promote": { "from": "latest", "afterMinutes": 1440 }
}
} instruction refs acme/support-agent set stable v3
instruction refs acme/support-agent gate stable --require-checks --require-signature --promote-from latest --after 1440 Two organization policy keys decide what agents may do with versions. agentPublish lets agents release versions and merge proposals. aiAutoPublish lets agents approve and merge proposals. It takes true, false or a list of ref names (globs with *), but agents approve and merge only when it is true. Both are false by default. Every key is in Policy and roles.
Addresses
An instruction is read as an MCP resource. Its address takes the owner and name, or the id. The id never changes; renaming or moving an instruction changes its owner/name address, and the old one redirects.
instruction://acme/support-agent the default ref's version, by owner and name
instruction://ins_01JX0000000000000000000000 the same, by id (stays the same through renames and moves)
instruction://acme/support-agent@stable the version a ref points at
instruction://ins_01JX0000000000000000000000@v3
one version, by number
instruction://ins_01JX0000000000000000000000@ver_01JX0000000000000000000000
one version, by its id
instruction://ins_01JX0000000000000000000000/draft
the working text, for those who may read the draft Other views of an instruction (/versions, /refs, /meta, /consumers and more), and the me://, org:// and skill:// schemes, are in Resources and addresses.
Visibility and access
Visibility says who may read an instruction's versions:
| Visibility | Editor label | Who reads its versions |
|---|---|---|
private |
Only you | You, and the people and agents it is shared with |
internal |
Your organization | Its organization's owners, admins, billing and members; not its guests |
public |
Everyone | Anyone, signed in or not, on the web; it is listed in Explore |
Over MCP every caller signs in, whatever the visibility. The draft, its suggestions and its comments stay with the people who work on it, even when the versions are public. The first release must say the visibility (visibility on instructions_publish). Making an instruction public asks for confirmation.
Access is a permission on the ladder none < read < suggest < edit < publish < manage. A caller gets the highest of what the visibility gives, what its workspace role gives and what the instruction's grants give. The organization's owners and admins manage every instruction in it. instructions_access_set grants a permission to a principal of type user, agent or org; with workspaceBaseline: false, the workspace's roles stop applying to that instruction.
| Permission | Role | Allows |
|---|---|---|
read |
Reader | Read versions |
suggest |
Contributor | Suggest changes and comment |
edit |
(agents) | Edit the draft; an agent's edits land as suggestions |
publish |
Maintainer | Edit, accept suggestions, release, move refs |
manage |
Admin | Share, change visibility, delete, set the default ref |
An agent or service holds publish at most: it never manages. A caller with no access gets not_found, not forbidden, so a private instruction's existence doesn't leak. The full matrix, with organization roles, is in Policy and roles.
Suggestions, comments, proposals and forks
- Suggestions are marked changes inside the draft (
instructions_suggestions_*). A Maintainer accepts or rejects them. - Comments are threads on words of the draft (
instructions_comments_*). They are kept with the draft and never delivered. - Proposals offer a whole text to an instruction (
instructions_proposals_*): a title, a rationale, a diff against the version it was based on, and reviews. A Maintainer merges one as a new version. An author never approves their own. Agents approve only whereaiAutoPublishallows, and merge whereagentPublishoraiAutoPublishdoes. - Forks are your own copy of an instruction you can read (
instructions_fork). The copy keeps its origin, starts with a draft and no versions, and offers changes back as a proposal.
Followers
A follower is anything that reads an instruction and applies it: an agent, a hook, instruction watch.
- Binding. A follower declares what it follows with
instructions_bindings_create: a ref (followmode, the default ref unless it names one) or one version (pinmode), and who it is (consumer). In the editor and on people pages this is "following". - Report. After applying a version, the follower calls
instructions_bindings_reportwith the version and the delivered digest, and the app it runs in (host). The instruction's Admins then see who holds what and who is behind. - Consumers.
instructions_consumers_listlists every reader from what it did (its last read is the version it has), and the declared bindings, aslive,recentordeclared. - Pause. An Admin of the instruction (the
managepermission) can pause one binding (instructions_bindings_pause): it keeps its last version and gets nothing new until resumed. A follower that only wants to stop deletes its own binding. - Live updates. A follower subscribes to the instruction's resource and hears of a new version at once, through the events
md.instruction.activityandmd.instruction.releases. Reading is never limited; live updates are.
Plans Community 1 · Pro unlimited · Team unlimited · Enterprise unlimited
How the follow file, hooks and offline behaviour work is on How following works. The live-update limit and its error are on Live updates.
Organizations and workspaces
An organization owns the plan, billing, seats, people, policy, apps, domains, signing keys, integrations and the assistant switch. Everyone has a personal organization; a team has its own. Organization roles are owner, admin, billing, member and guest.
A workspace holds instructions, projects and folders. It is open (the organization's members, not its guests, get their default-workspace role there, at most Maintainer), restricted (only the people added to it) or sealed (beta, not yet independently reviewed). Workspace roles are Reader, Contributor, Maintainer and Admin.
Plans Community 1 · Pro 1 · Team unlimited · Enterprise unlimited
Projects and folders organize a workspace's instructions. A deployment rule selects instructions by project, folder, tags or a list.
Policy is a set of keys on the organization (orgs_policy_get, orgs_policy_set), such as defaultVisibility, memberRole, agentPublish, requireSignedVersions and assistant. Every key is in Policy and roles.
Agents
"Agent" means several things on instruction.md. Each has its own page.
| Word | What it is | Where |
|---|---|---|
| agent (principal) | A caller that isn't a person, signing in with an agent credential (API key). It holds publish at most, and its edits land as suggestions. |
Agent credentials |
instruction agents list, create, rotate, revoke |
The instruction CLI's own commands for an organization's agent credentials. |
instruction commands |
@instruction.md/agents |
The package behind instruction-agents, and behind every other instruction agents <command> (follow, install, run, apply, check, hook and more), which instruction hands over to it. |
instruction agents commands |
| coding agent | Claude Code, Codex, Cursor and similar, following an instruction through hooks. | Claude Code, Other coding agents |
| managed agents | An organization's settings that make every Claude Code and Codex its people use follow one instruction. | Managed agents |
| deployment, deployment rule, runner | An agent per instruction of a project or folder, on a machine of yours, started by instruction agents run. |
The runner |
| the Agents card | In the editor: who follows an instruction and which version each holds. | See your agents |
| the Agents app | At /agents/: talk with the agents that run for you. | The Agents app |
Plans On Pro, Team, and Enterprise
Agent credentials are on the plans above. Deployments have their own badge on The runner.
Signed and sealed
Signed says who released a version. The server signs every version that isn't sealed with the organization's publisher key (Ed25519, a JWS over the authored digest), and publishes the keys at instruction://pub/{owner}/keys.json. A follower with --require-signature refuses an unsigned or unverifiable version and keeps its last good one. You can't sign with your own key on instruction.md: --sign-with is refused. See Signing and verification.
Sealed says who can read the text. In a sealed workspace the text is encrypted on your devices, or in a proxy your company runs, and the server stores only ciphertext.
Plans On Team and Enterprise
A sealed text is signed inside its envelope by the key of the person who sealed it, and its visibility is private or internal, never public. Signing never hides a text. See Sealed instructions.
Architecture
The hosted service is a set of parts in one Kubernetes cluster. Self-hosting runs the same parts.
| Part | What it does |
|---|---|
| The MCP gateway (MCPG) | The MCP server at https://instruction.md/mcp. It speaks MCP 2026-07-28 only, with no sessions, runs as two replicas, checks tokens and scopes, and serves the tools, resources, prompts and skills. |
| Postgres | Holds everything. Most tools are SQL functions the gateway calls directly, in one transaction each. |
| imd-svc | The tools that need more than SQL: the Yjs draft, the language service, releases and signing, Keycloak administration, and a background worker (checkpoints, promotions, exports). |
| NATS (JetStream) | The gateway replicas' shared state: subscriptions and the events log behind live updates. |
| Keycloak | Sign-in at https://instruction.md/auth: passkeys, agent credentials and the tokens every caller presents. |
| Embeddings | A self-hosted model (Text Embeddings Inference) behind instructions_search; no instruction text leaves the cluster for it. |
| The web | The site, the editor, Learn and these docs, served as static files. |
Common misunderstandings
- "Publishing updates my agents." It moves
latest(the default ref). Agents followingstable, or pinned, don't change until you move that ref. - "stable exists." Not until you create it.
- "Public means agents can read it without signing in." Public versions are readable on the web by anyone. Over MCP, every caller signs in.
- "An agent with edit can change the draft." Its edits land as suggestions, and it releases only where
agentPublishallows. - "Deleting a ref rolls back." It removes the name. To roll back, move the ref to an older version.