---
title: Orrery — AI operating guide
version: 1.2.0
updated: 2026-11-14
canonical_url: https://orrery.instructedintelligence.com/mcp/prompt.md
version_url: https://orrery.instructedintelligence.com/mcp/prompt/version
---

# Orrery — AI operating guide

## What Orrery is for

Orrery is a map of how a business actually runs: every step from a person's request through the
AI sessions, services and code that handle it, modelled as **journeys** inside an **estate** (one
organisation's model). It answers three questions: how does this work, what is missing, and what
would automating it be worth.

Two ideas carry the model:

- **Every edge has a trigger kind**: `event`, `invocation` or `schedule` (runs on its own), or
  `convention` or `initiative` (runs when somebody remembers). A `convention`/`initiative` edge
  between two automated ones is a manual relay inside an automated chain.
- **Every step names a witness**: the concrete query that would prove it ran (a tracker transition,
  a knowledge episode, a commit, an audit event), or an explicit `unobservable: true` with a reason.

Reach for Orrery when the question is about **process shape**: who or what does each step, what
triggers the next one, and where the gaps are. Use a neighbouring tool instead when:

- you want the work items themselves (tickets, status, who is on what) — **Coordinator**;
- you want what the organisation knows or decided — **Cornerstone**;
- you want what is deployed and running (hosts, services) — **Cartograph**.

Orrery reads those tools to build its models; it never writes to them.

## Identity and tenancy

- Every call runs as **the connected identity**: an II Sign-In token (through Junction, or directly)
  or an Orrery key (`orr_…`). There is no anonymous MCP access.
- **The estate is the isolation boundary.** Every tool call names one `estate` (for `put_journey`
  it is the `estate` field inside the journey document). There is no call that spans estates, and
  findings never cross them.
- Reading an estate needs **viewer** access to it; writing needs **member** (or owner). Access comes
  from a seat in the organisation that owns the estate (admin = owner, member, viewer; set by
  Vista), or from an explicit grant an owner made. Being in the organisation is not enough without
  a seat. A call on an estate you do not hold is refused before anything is read.
- A deactivated account, or an organisation that is suspended, is refused on the next call: the
  HTTP request itself answers `403` with `account deactivated` or `organisation suspended`, or the
  tool result says `refused: organisation suspended`. Do not retry; tell the person.
- An organisation can instead be **read-only** (a lapsed subscription): reads work as normal, and
  every write is refused with `organisation read-only` (HTTP `403`, or the tool result
  `refused: organisation read-only`). Do not retry the write; tell the person that their
  organisation's admin can restore it.
- There is no MCP tool that lists estates. If you do not know the estate id, ask the person you are
  working with (or, with a browser session, the canvas shows only the estates you hold).

## Tools

| Tool | Kind | What it does |
|---|---|---|
| `list_journeys` | read | The journeys in one estate, with step and edge counts. |
| `get_journey` | read | One journey in full (steps, edges, divergences) as YAML. |
| `get_guide` | read | Returns this guide. Takes no arguments and needs no estate. |
| `put_journey` | write | Create or replace a whole journey. |
| `upsert_step` | write | Add or replace one step in an existing journey (matched by step id). |
| `link` | write | Add or replace one edge between two existing steps (matched by from + to). |
| `set_witness` | write | Set how one step's running would be proven. |

**Write tools exist only on a writable deployment.** The production endpoint
(`orrery.instructedintelligence.com/mcp`, and Junction's `orrery__` tools) is **read-only**: the
model is YAML in git, and the rule is "never edit on the server". Models are composed on a local
Orrery started with `-repo`, committed, pushed and deployed. If `tools/list` shows only the read
tools, you are on a read-only server; do not look for another way to write.

Through Junction the tools are namespaced: `orrery__list_journeys`, `orrery__get_journey`,
`orrery__get_guide`.

## Main workflows

**Understand how something works**

1. `list_journeys {estate}` — find the journey by id and title.
2. `get_journey {estate, journey}` — read the steps (actor kind, mode, witness), the edges (trigger,
   `because`) and any divergences between what the documents say and what happens.

**Add or extend a model (writable deployment only)** — check before you file:

1. `list_journeys {estate}` — make sure the journey does not already exist under another id.
2. `get_journey {estate, journey}` if it exists — build on what is there.
3. A new journey: `put_journey {reason, agent, journey}` with the complete document
   (`schema_version`, `estate`, `id`, `title`, `intent`, `starts`, `ends`, `steps[]`, `edges[]`,
   `divergences[]`).
4. A change to an existing one: `upsert_step`, `link` or `set_witness`, each with a `reason`.

Every write is validated and then committed to git with your `reason` and `agent` (default
`orrery-agent`), so it is reviewable as a diff. A step needs a witness or an explicit
`{unobservable: true, why: …}`; an edge needs a `trigger` and the specific carrier in `because`.

## Paging, limits and errors

- No paging: `list_journeys` returns every journey in the estate; a journey is returned whole.
- Request bodies are capped at 4 MB.
- **A refusal comes back as a tool result with `isError: true`**, not a transport error, and its
  text says why:
  - `refused: no viewer access to estate "x"` / `no member access…` — you do not hold the access.
    Do not retry with another estate id; ask the person who owns the estate.
  - `refused: could not determine which estate this call targets` — pass `estate` (or, for
    `put_journey`, `journey.estate`).
  - a validation message — the change would not make a valid model (missing witness, edge without a
    trigger, unknown step). Fix the named field and send it again.
  - `no journey "x" in estate "y"` — call `list_journeys`.
- An HTTP 401 means the token or key was missing or not accepted.

## Hard lines

- Orrery never proposes reducing human steps. A `human` + `decision` step is the goal state, not a
  cost; impact is understanding, substrate completeness and reclaimed judgement time, never headcount.
- No write without a commit: there is no way to change the model that skips validation and git.
- Nothing crosses estates. Do not copy a journey, finding or name from one estate into another.
- Orrery reads Coordinator, Cornerstone and Cartograph; it never writes to them.
- Do not invent a witness to get a step accepted. If you cannot say how a step would be proven,
  mark it unobservable and say why: that is a finding, and a true one.

## Staying current

This guide is versioned separately from Orrery's release. Check
`GET https://orrery.instructedintelligence.com/mcp/prompt/version` (or the version in the
`initialize` instructions) and re-read this guide when the version increases. If you cannot open
URLs, call `get_guide`.
