Audit trail
For developers, administrators and auditors who need to know who changed what on instruction.md, and who read what isn't public. This page lists what the audit trail records, the tools and the command that read it, the export, and how long each part is kept.
What is recorded
The audit trail is two lists read as one, newest first:
- Events. Every change made through the service: 70 event types, below. Each says who did it, when, from which client, and what it was about, in ids and one sentence.
- Reads. Every read of a released version of an instruction that isn't public (Only you or Your organization), by anyone. Reads of public instructions are counted per day, never logged one by one.
Neither ever holds an instruction's content: no draft text, no version text, no comment or suggestion text. A record's summary is a sentence made of names and titles, such as "Maria Lopez released v8 of Support agent".
Events
| Family | What happened | Types |
|---|---|---|
instruction.* | An instruction made, changed (title, description, tags, address), archived or restored, moved to the trash, deleted for good, its visibility changed, or moved to another organization | instruction.archived, instruction.created, instruction.deleted, instruction.purged, instruction.restored, instruction.transferred, instruction.updated, instruction.visibility_changed |
draft.* | The draft changed | draft.changed |
checkpoint.* | A checkpoint of the draft kept | checkpoint.created |
suggestion.* | A suggestion made | suggestion.created |
comment.* | A comment written | comment.created |
proposal.* | A proposal opened, updated or closed | proposal.closed, proposal.opened, proposal.updated |
version.* | A version released or revoked | version.published, version.revoked |
ref.* | A ref moved, its gates changed, or deleted | ref.changed, ref.deleted |
schedule.* | A scheduled release set or cancelled | schedule.cancelled, schedule.created |
access.* | A grant or the workspace baseline changed, access asked for, or an access request answered | access.changed, access.requested, access.resolved |
link.* | A read link made or revoked | link.created, link.revoked |
binding.* | A follower declared, changed, reported the version it applied, paused, resumed or removed | binding.created, binding.deleted, binding.paused, binding.reported, binding.resumed, binding.updated |
consumer.* | A reader taken over as a declared follower | consumer.adopted |
folder.* | A folder or project made, renamed, moved or deleted | folder.changed |
org.* | The organization made, renamed, its plan, policy, sign-in, domains, apps or spending limit changed, or deleted | org.created, org.deleted, org.renamed, org.updated |
workspace.* | A workspace made, changed or deleted | workspace.created, workspace.deleted, workspace.updated |
member.* | A member added, their role changed, or removed | member.added, member.removed, member.updated |
invitation.* | An invitation sent, accepted or revoked | invitation.accepted, invitation.created, invitation.revoked |
user.* | A person's profile changed, or their account deleted | user.deleted, user.updated |
agent.* | An agent credential made, rotated or revoked | agent.created, agent.revoked, agent.rotated |
key.* | A signing key added, rotated, retired or revoked | key.changed |
integration.* | An integration added, pulled again (an API), its tools' policy changed, or removed | integration.added, integration.removed, integration.updated |
seal.* | A sealed workspace's key set up, rotated or given to someone | seal.key |
deployment.* | A deployment made, waiting for approval, approved, given a release, refused, asking a person or answered, needing sign-in, retired, or a deployment rule made, changed or deleted | deployment.answered, deployment.approval_needed, deployment.approved, deployment.asked, deployment.created, deployment.needs_sign_in, deployment.refused, deployment.release_pending, deployment.released, deployment.retired, deployment.rule_created, deployment.rule_deleted, deployment.rule_updated |
An organization's audit holds every event recorded in it: about its instructions, its workspaces, its people, its settings and its deployments. An instruction's audit holds the events about that instruction.
The live-updates stream lists comment.resolved, export.ready, job.finished, proposal.merged, schedule.fired, suggestion.settled too. Nothing records those types, so no audit record has them. Filtering for them finds nothing.
Reads
A read record has the type read, the reader, the version read and how it was read (transport):
transport | The read |
|---|---|
export | An export that holds the version |
fork | A fork made from the version |
mcp | An instruction:// resource read over MCP |
page | The instruction's page on the site, or its Markdown |
tool | A tool that returns a version's text, such as instructions_versions_read or instructions_export |
Every read record has the outcome ok: refused reads aren't logged.
A record
{
"id": "evt_01JX9B2C5F7H9K1M3P5R7T9V1X",
"source": "event",
"type": "integration.updated",
"at": "2026-11-22T09:31:44.019Z",
"actor": { "kind": "user", "id": "usr_01JX7P9Q1R3S5T7U9V1W3X5Y7Z", "name": "Maria Lopez" },
"via": { "client": "instruction.md studio" },
"subject": { "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B", "integrationId": "itg_01JX8A3B5C7D9E1F3G5H7J9K1M", "kind": "mcp", "url": "https://calendar.example.com/mcp", "tools": 1, "newTools": "allow" },
"summary": "Maria Lopez changed which tools of Calendar may be used",
"outcome": "ok"
} | Field | What it is |
|---|---|
id |
evt_… for an event, read_… for a read |
source |
event or read |
type |
The event type, or read |
at |
When, in UTC |
actor |
Who: kind (user, agent or service), id, name, and for when an agent acted for a person |
via |
The client the call came from, as the gateway named it. Only with detail: "full" |
instructionId, versionId, workspaceId |
What it was about. A read's workspace is the instruction's workspace now |
subject |
The ids and values of the change. Only with detail: "full", and never content |
summary |
One sentence. Events only |
transport |
How a read was made. Reads only |
outcome |
ok |
Who can read it
- An organization's audit (
orgId): its owners and admins. - One instruction's audit (
instructionId): anyone with Admin (manage) on that instruction, which an organization's owners and admins have on all of them. - Always as a person, with a token that has the
org:adminscope. The audit tools are in theinsightstoolset, which a token without that scope doesn't list, and no agent or service credential can have it. See org:admin.
The server doesn't check the plan for the audit trail: an organization's owners and admins can query and export it on every plan.
In the editor, owners and admins read it as Settings ▸ Activity. That page shows events only, never reads. Show narrows it to All, Changes, Published, Access or Agents, and Search activity finds words. Its Export offers CSV and NDJSON, which export the whole log, reads included.
Query it
instructions_audit_query reads a page of records, newest first: 25 by default, at most 500. Give either orgId or instructionId (an id, owner/name or an instruction:// address); without one, it is refused with validation, "say whose audit: instructionId or orgId".
{
"name": "instructions_audit_query",
"arguments": {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"types": ["read"],
"transport": "mcp",
"from": "2026-11-01T00:00:00Z",
"limit": 100
}
} {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"filters": { "types": ["read"], "transport": "mcp", "from": "2026-11-01T00:00:00+00:00" },
"records": [
{
"id": "read_48213",
"source": "read",
"type": "read",
"at": "2026-11-21T16:05:12.408Z",
"actor": { "kind": "agent", "id": "agt_01JX7Q4B8C2D6E0F3G7H1J5K9M", "name": "support-bot" },
"instructionId": "ins_01JD3Q8Z5X7R2M4K6N8P0S2T4V",
"versionId": "ver_01JX9B2C4D6E8F0G2H4J6K8M0N",
"transport": "mcp",
"outcome": "ok",
"workspaceId": "ws_01JX7Q2M4N8R5T6V9W0Y3Z1A2D"
}
],
"nextCursor": "eyJhdCI6IjIwMjYtMTEtMjFUMTY6MDU6MTIuNDA4WiIsImsiOiJyMDAwMDAwMDAwMDAwMDA0ODIxMyJ9"
} filters repeats the filters as the server understood them. nextCursor reads the next page; a record made meanwhile doesn't shift it.
Scope and filters
| Argument | Type | What it keeps |
|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. |
orgId | string | The organization (org_…). |
types | string[] | Only these. |
except | string[] | All but these (the same forms as types). |
q | string | Only records whose sentence, actor's name or type has these words, whatever their case. |
workspaceId | string | Only what happened in this workspace of the organization (ws_…). |
principal | string | Only this principal. |
from | string | From (ISO 8601). |
to | string | Until (ISO 8601). |
transport | string | Only reads over this. |
outcome | string | Only this outcome. |
How the filters behave:
typesandexcepteach take event types in three forms: an exact type (ref.changed), a family (version.*) or*.readis the reads.exceptleaves out what it names, so"except": ["read"]is every event.qis up to 200 characters, matched in a record's sentence, its actor's name or its type, whatever their case.workspaceIdmust be one of the organization's workspaces; any other isnot_found. It keeps the events recorded in that workspace, and the reads of instructions that are in it now.principalis a person's or an agent's id (usr_…,agt_…).fromkeeps records at or after that time,torecords before it. Both are ISO 8601; anything else isvalidation, "from is a date or an ISO 8601 time".transportkeeps only reads, made over that transport.outcomeother thanokmatches nothing.
Every argument of instructions_audit_query
| Argument | Type | What it is |
|---|---|---|
instructionId | string | The instruction: its id (ins_…), owner/name, or instruction:// address. |
orgId | string | The organization (org_…). |
types | string[] | Only these. |
except | string[] | All but these (the same forms as types). |
q | string | Only records whose sentence, actor's name or type has these words, whatever their case. |
workspaceId | string | Only what happened in this workspace of the organization (ws_…). |
principal | string | Only this principal. |
from | string | From (ISO 8601). |
to | string | Until (ISO 8601). |
transport | string | Only reads over this. |
outcome | string | Only this outcome. |
limit | integer | At most this many (default 25, max 500). |
cursor | string | The nextCursor of the previous page. |
detail | "summary" | "full" | How much of each item: summary (default) — each record without via or subject; full — all it has. |
One instruction's recent activity
instructions_activity_list lists one instruction's events, newest first, each with a sentence: 25 by default, at most 100. It has no filters and no reads. detail: "full" adds each event's subject and client. It needs Admin on the instruction, and org:admin, like the audit.
{
"name": "instructions_activity_list",
"arguments": { "instructionId": "acme/support-agent", "limit": 25 }
} {
"instructionId": "ins_01JD3Q8Z5X7R2M4K6N8P0S2T4V",
"events": [
{ "id": "evt_01JX9B…", "type": "ref.changed", "at": "2026-11-21T16:02:51.230Z", "actor": { "kind": "user", "id": "usr_01JX7P…", "name": "Maria Lopez" }, "versionId": "ver_01JX9B…", "summary": "Maria Lopez moved latest of Support agent to v8" },
…
],
"nextCursor": "…",
"links": ["instruction://ins_01JD3Q8Z5X7R2M4K6N8P0S2T4V/events"]
} The same events, as they happen, are the resource instruction://{id}/events. See Resources and addresses.
From the command line
instruction audit prints the last 100 records of an instruction or an organization:
instruction audit --org acme --types 'version.*,ref.changed' --from 2026-11-01T00:00:00Z 2026-11-21 16:02 ref.changed Maria Lopez ver_01JX9B2C4D6E8F0G2H4J6K8M0N Maria Lopez moved latest of Support agent to v8
2026-11-21 16:02 version.published Maria Lopez ver_01JX9B2C4D6E8F0G2H4J6K8M0N Maria Lopez released v8 of Support agent
2026-11-18 10:47 version.published ci ver_01JX7S1T3U5V7W9X1Y3Z5A7B9C ci released v7 of Support agent Each line is the time (UTC, to the minute), the type, the actor, via <transport> for a read, the version and the sentence.
instruction audit acme/support-agent --self | Flag | What it does |
|---|---|
<id|uri> |
One instruction's audit |
--org ORG |
An organization's audit, by its slug or id |
--types a,b |
Only these types, in the forms above |
--from ISO, --to ISO |
A time range |
--self |
Only what you did. Not with export |
--format ndjson|csv, --out FILE |
With export only: the file's format, and where to write it |
--json |
The records as JSON |
The command needs the org:admin permission. On a terminal, a sign-in without it asks once to sign in again with it. Without a terminal it stops with exit code 3 and says to run instruction login --admin first. Every command is on instruction commands.
Export it
instructions_audit_export takes the same scope and filters and writes them to a file, as NDJSON (the default) or CSV. It runs as a background job, so it answers at once:
{
"name": "instructions_audit_export",
"arguments": {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"except": ["read"],
"workspaceId": "ws_01JX7Q2M4N8R5T6V9W0Y3Z1A2D",
"format": "csv",
"idempotencyKey": "audit-2026-11"
}
} {
"jobId": "job_01JX9C7D9F1H3K5M7P9R1T3V5X",
"kind": "audit.export",
"state": "queued",
"format": "csv",
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"filters": { "except": ["read"], "workspaceId": "ws_01JX7Q2M4N8R5T6V9W0Y3Z1A2D" },
"links": ["me://exports"]
} - The file appears in
me://exports, readable only by whoever asked for it, and is kept 7 days. You are told inme://inbox: "Your audit export is ready". Its name isaudit-<scope>-<YYYY-MM-DD>.ndjsonor.csv. - Asking again for the same scope, filters and format while that export is on its way answers the same job. With an
idempotencyKey, the same call sent again later answers what it did. - NDJSON has one record per line, whole,
viaandsubjectincluded. - CSV has these columns. A cell that starts with
=,+,-,@, a tab or a carriage return gets a'in front, so a spreadsheet doesn't run it as a formula.
at,type,source,actor_kind,actor_id,actor_name,client,instruction_id,version_id,transport,outcome,summary From the command line, instruction audit export makes the export, waits for it (up to 3 minutes) and writes it:
instruction audit export --org acme --format csv --out audit.csv audit-org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B-2026-11-22.csv → audit.csv Without --out, the file goes to standard output. The other exports are on Export and back up.
How long it is kept
| What | Kept |
|---|---|
| Events | As long as the organization. When an organization is deleted for good, its events go, except org.deleted and user.deleted |
| Reads | 90 days, unless instruction.md has agreed another period with the organization. No tool changes it |
| Exports | 7 days in me://exports |
| A deleted account | Its reads go with it. In the events that stay, its name becomes "A deleted account" |
While the organization is under legal hold, the retention removes none of its reads, whatever their age. What a hold blocks is on Organization policy.
Deleting an instruction for good (instructions_purge) keeps its events, with an instruction.purged event last. Its reads stay for the read log's retention.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
| The audit tools aren't listed | The token lacks org:admin, or it is an agent's |
Sign in as a person with org:admin: instruction login --admin, or add the scope to your host's connector. |
forbidden: "this needs an organization admin" |
You are a member, not an owner or admin | Ask an owner or admin, or read one instruction's audit with Admin on it. |
not_found for an instruction |
You can't read it, or lack Admin on it | Use an instruction you administer. |
not_found for a workspace |
workspaceId isn't one of the organization's |
Use an id from orgs_workspaces_list. |
validation: "from is a date or an ISO 8601 time" |
from or to isn't a time |
Use a form such as 2026-11-01T00:00:00Z. |
validation: "invalid cursor" |
A cursor from another query, or edited | Start again without cursor. |
| "the export (job_…) is taking a while; your notifications will say when it's ready (me://exports)" | The export took more than 3 minutes | Wait for the notice, then read it from me://exports. |
--self filters the query; an export takes --types, --from and --to |
--self with export |
Export with principal over MCP, or leave --self out. |
| No reads appear | The instruction is public, or the reads are older than 90 days | Reads are logged for instructions that aren't public, for that long. |
| Still stuck | Ask on Support. |
Questions
Who changed this rule and when?
Query the instruction's audit for draft.changed, suggestion.created and version.published, or read instructions_activity_list. Each event says who and when; compare versions with instructions_diff to see what changed. See Query it.
Can I export the audit trail for an auditor?
Yes. instructions_audit_export or instruction audit export --org <org> --format csv --out audit.csv writes every record that matches, reads included. See Export it.
Does the audit trail hold the text of my instructions?
No. It holds ids and one-sentence summaries, never a draft's, a version's or a comment's text. See What is recorded.
Are reads of public instructions logged?
No. They are counted per day, without who read them. Reads of instructions that aren't public are logged, with the reader. See Reads.
Can an agent read the audit trail?
No. The audit tools need a person with org:admin, and no agent credential can have it. See Who can read it.
Generated from the code
The event types are read from every call that records an event in db/functions/*.sql. The transports, the read log's retention and the export's lifetime come from the same files, and the arguments from packages/registry/registry.json. A new event family, or a filter that leaves one of the two tools, stops the docs build until this page describes it.