لم تُترجم هذه الصفحة بعد.

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.

The objects the API names, from organization to follower.

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 with version_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_restore puts 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, whatever refs says.
  • Schedules. instructions_schedules_create releases 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_cancel cancels it.
  • Revocation. instructions_versions_revoke revokes 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 refs says otherwise.
  • The default ref is what instruction://{id} reads when no ref is named, and what a new binding follows. instructions_refs_set with makeDefault: true makes 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 as beta.
  • Moving the default ref asks for confirmation, because its followers switch. Moving another ref doesn't ask. latest and the default ref can't be deleted. Deleting another ref leaves its followers on their last version.
How refs move on a release and on a promotion.

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.
instructions_refs_set arguments
{
  "instructionId": "acme/support-agent",
  "ref": "stable",
  "versionId": "v3",
  "policy": {
    "requireChecks": true,
    "requireSignature": true,
    "promote": { "from": "latest", "afterMinutes": 1440 }
  }
}
The same, with the CLI
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:// addresses
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 where aiAutoPublish allows, and merge where agentPublish or aiAutoPublish does.
  • 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 (follow mode, the default ref unless it names one) or one version (pin mode), 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_report with 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_list lists every reader from what it did (its last read is the version it has), and the declared bindings, as live, recent or declared.
  • Pause. An Admin of the instruction (the manage permission) 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.activity and md.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 following stable, 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 agentPublish allows.
  • "Deleting a ref rolls back." It removes the name. To roll back, move the ref to an older version.

Last checked against the product:

Was this page helpful? Report a problem