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

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

FamilyWhat happenedTypes
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 organizationinstruction.archived, instruction.created, instruction.deleted, instruction.purged, instruction.restored, instruction.transferred, instruction.updated, instruction.visibility_changed
draft.*The draft changeddraft.changed
checkpoint.*A checkpoint of the draft keptcheckpoint.created
suggestion.*A suggestion madesuggestion.created
comment.*A comment writtencomment.created
proposal.*A proposal opened, updated or closedproposal.closed, proposal.opened, proposal.updated
version.*A version released or revokedversion.published, version.revoked
ref.*A ref moved, its gates changed, or deletedref.changed, ref.deleted
schedule.*A scheduled release set or cancelledschedule.cancelled, schedule.created
access.*A grant or the workspace baseline changed, access asked for, or an access request answeredaccess.changed, access.requested, access.resolved
link.*A read link made or revokedlink.created, link.revoked
binding.*A follower declared, changed, reported the version it applied, paused, resumed or removedbinding.created, binding.deleted, binding.paused, binding.reported, binding.resumed, binding.updated
consumer.*A reader taken over as a declared followerconsumer.adopted
folder.*A folder or project made, renamed, moved or deletedfolder.changed
org.*The organization made, renamed, its plan, policy, sign-in, domains, apps or spending limit changed, or deletedorg.created, org.deleted, org.renamed, org.updated
workspace.*A workspace made, changed or deletedworkspace.created, workspace.deleted, workspace.updated
member.*A member added, their role changed, or removedmember.added, member.removed, member.updated
invitation.*An invitation sent, accepted or revokedinvitation.accepted, invitation.created, invitation.revoked
user.*A person's profile changed, or their account deleteduser.deleted, user.updated
agent.*An agent credential made, rotated or revokedagent.created, agent.revoked, agent.rotated
key.*A signing key added, rotated, retired or revokedkey.changed
integration.*An integration added, pulled again (an API), its tools' policy changed, or removedintegration.added, integration.removed, integration.updated
seal.*A sealed workspace's key set up, rotated or given to someoneseal.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 deleteddeployment.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):

transportThe read
exportAn export that holds the version
forkA fork made from the version
mcpAn instruction:// resource read over MCP
pageThe instruction's page on the site, or its Markdown
toolA 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

An event, with detail full
{
  "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:admin scope. The audit tools are in the insights toolset, 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".

Every MCP read this month
{
  "name": "instructions_audit_query",
  "arguments": {
    "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
    "types": ["read"],
    "transport": "mcp",
    "from": "2026-11-01T00:00:00Z",
    "limit": 100
  }
}
Answer
{
  "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

ArgumentTypeWhat it keeps
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
orgIdstringThe organization (org_…).
typesstring[]Only these.
exceptstring[]All but these (the same forms as types).
qstringOnly records whose sentence, actor's name or type has these words, whatever their case.
workspaceIdstringOnly what happened in this workspace of the organization (ws_…).
principalstringOnly this principal.
fromstringFrom (ISO 8601).
tostringUntil (ISO 8601).
transportstringOnly reads over this.
outcomestringOnly this outcome.

How the filters behave:

  • types and except each take event types in three forms: an exact type (ref.changed), a family (version.*) or *. read is the reads. except leaves out what it names, so "except": ["read"] is every event.
  • q is up to 200 characters, matched in a record's sentence, its actor's name or its type, whatever their case.
  • workspaceId must be one of the organization's workspaces; any other is not_found. It keeps the events recorded in that workspace, and the reads of instructions that are in it now.
  • principal is a person's or an agent's id (usr_…, agt_…).
  • from keeps records at or after that time, to records before it. Both are ISO 8601; anything else is validation, "from is a date or an ISO 8601 time".
  • transport keeps only reads, made over that transport. outcome other than ok matches nothing.
Every argument of instructions_audit_query
ArgumentTypeWhat it is
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
orgIdstringThe organization (org_…).
typesstring[]Only these.
exceptstring[]All but these (the same forms as types).
qstringOnly records whose sentence, actor's name or type has these words, whatever their case.
workspaceIdstringOnly what happened in this workspace of the organization (ws_…).
principalstringOnly this principal.
fromstringFrom (ISO 8601).
tostringUntil (ISO 8601).
transportstringOnly reads over this.
outcomestringOnly this outcome.
limitintegerAt most this many (default 25, max 500).
cursorstringThe 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.

tools/call params
{
  "name": "instructions_activity_list",
  "arguments": { "instructionId": "acme/support-agent", "limit": 25 }
}
Answer
{
  "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:

Shell
instruction audit --org acme --types 'version.*,ref.changed' --from 2026-11-01T00:00:00Z
Output
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.

What you did on one instruction
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:

Every change in one workspace, as CSV
{
  "name": "instructions_audit_export",
  "arguments": {
    "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
    "except": ["read"],
    "workspaceId": "ws_01JX7Q2M4N8R5T6V9W0Y3Z1A2D",
    "format": "csv",
    "idempotencyKey": "audit-2026-11"
  }
}
Answer
{
  "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 in me://inbox: "Your audit export is ready". Its name is audit-<scope>-<YYYY-MM-DD>.ndjson or .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, via and subject included.
  • 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.
CSV header
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:

Shell
instruction audit export --org acme --format csv --out audit.csv
Output
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.

Last checked against the product:

Was this page helpful? Report a problem