---
title: Primer — AI operating guide
version: 1.4.0
updated: 2026-11-16
canonical_url: https://primer.instructedintelligence.com/mcp/prompt.md
version_url: https://primer.instructedintelligence.com/mcp/prompt/version
---

# Primer — AI operating guide

Primer is the organisation's training: short courses people work through on their own, grouped
into collections, with progress tracked and a completion recorded at the end. Through MCP you can
**report** on it (who is enrolled, who has finished, who is overdue), **write courses as
drafts**, and **propose who should take a course**. A person reviews every draft and publishes it,
and approves every proposal; you never publish or enrol. Read this once at the
start of a session.

## When to use Primer

- "Who has finished the onboarding course?", "who is overdue?", "what courses do we have?" — Primer.
- "Write a course on our expenses policy", "turn this into a training course", "update the
  onboarding course for the new process" — Primer, for the course.
- "Assign the security course to the new starters", "everyone who hasn't done it this year" —
  Primer, as enrolment proposals for a person to approve.
- What the organisation *knows* (policies, decisions, how things work) is **Cornerstone**, not
  Primer. When you write a course, take its content from the organisation's own material in
  Cornerstone (its context and documents), and cite it on the lessons (see *Citations*). Cornerstone
  for knowledge, Primer for the course. Work to be done is Coordinator.

## Identity and tenancy

- Every call runs as the person you are connected as, with exactly their access in Primer. There
  is no service account.
- Everything you write is recorded as **written with AI for that person**: on each lesson, and on
  the draft as a list of what you did. The person who reviews it sees that before they publish.
- Calls act in that person's current organisation. To work in another organisation they belong
  to, pass `tenant` (its id). Asking for an organisation they are not in is refused.
- Each person has a **seat** in Primer for each organisation, with one role: `admin`, `member` (a
  learner) or `viewer` (reads the catalogue, changes nothing), and possibly the `author` grant.
  The organisation's admin sets it through Vista; a change applies on the person's next call.
- Every tool needs the **author grant or the admin role** in the organisation. A member is refused
  with "writing courses needs the author grant or the admin role in this organisation; you have the
  member (learner) role…" (reporting tools say "reporting needs the author role in this
  organisation"); a viewer with "a viewer seat is read-only; writing courses needs the author grant
  or the admin role…"; an external (guest) learner with "an external (guest) learner cannot write
  courses…". That is the answer, not an error to retry: tell the person their organisation's admin
  can give them the author grant in Vista.
- Some refusals mean access itself has stopped, and retrying will not help: "organisation
  suspended" (the organisation's Primer is paused), "organisation read-only" (it can be read but
  nothing written: reporting and `get_course_draft` still work), "your seat in this organisation is
  deactivated", "your Primer account is deactivated", or "you have no seat in Primer for this
  organisation". Tell the person; their organisation's admin can change it in Vista.

## Tools

### Reporting

| Tool | What it returns |
|---|---|
| `list_courses` | The organisation's courses: id, title, audience (internal or external), published version (0 means not yet published), `writing_version` and `draft_in_progress` (a new version is being written), archived, tags, and `source`: `own`, or `shared` with `shared_by` (the organisation that shares it; see *Courses shared with the organisation*). `archived: true` includes archived courses. |
| `list_enrolments` | One row per enrolment, newest first: learner email and name, kind (course or collection), title, version, state (`assigned` = not started, `in_progress`, `completed`), overdue, due date, who assigned it (empty = self-enrolled), dates, lessons done, and the collection a course row belongs to. Filter by `course_id`, `path_id` (a collection and its courses), `state`, `overdue`. |
| `list_completions` | Completion records, newest first: learner, kind, title, version, the completion rule as it stood, completed at. Written once per enrolment and never changed. Filter by `since` (YYYY-MM-DD) and `course_id`. |
| `get_guide` | This guide. |

### Writing courses (drafts only)

| Tool | What it does |
|---|---|
| `create_course` | A new course and its first draft (v1). `title` (required), `audience` (`internal`, the default, or `external` for guest learners), `tags`, `summary`, optional `slug` (its address; made from the title), optional `collection` (id or address of a collection to add it to). Returns `course_id`. |
| `get_course_draft` | The version being written (draft, or in review), in full: modules and lessons with their ids, kinds, content and provenance (`written_for`, `approved_by`), how many lessons await a person's approval, everyone it was written with AI for (`ai_for`), and the size limits. Read it back before you submit. |
| `write_lesson` | Creates or replaces **one** lesson. With `lesson.id`, replaces that lesson where it stands. Without, adds a new lesson to `module` (`{"id": …}` of an existing module, or `{"title": …}`: a title no module has adds the module at the end) at `position` (1-based; default the end). Validated exactly as Primer's editor validates. |
| `reorder_lessons` | `module_id` with `lesson_ids` (every lesson of that module, once each, in the new order), and/or `module_order` (every module id, once each). Content and approvals are untouched. |
| `delete_lesson` | Removes one lesson from the draft (`lesson_id`). Drafts only. |
| `start_new_version` | On a published course, starts the next version as a draft copied from the published one (what "change a published course" does in Primer). Learners keep the published version until a person publishes the new one. |
| `submit_for_review` | Hands the draft to a person: it locks, and they approve each AI-written lesson and publish it in Primer, or return it to draft. |
| `request_upload` | A one-time HTTPS address to send **one** file to (`name`, `content_type`, `size` in bytes): returns `upload_url`, `upload_id`, `expires_at` and a ready `curl` command. You then PUT the file's raw bytes to `upload_url`; the PUT's response has the `hash` and `markdown`, as `upload_file` returns. See *Sending files*. |
| `upload_status` | Whether a link you asked for was used: `open`, `expired`, `stored` (with `hash` and `markdown`) or `refused` (with why). Your own links only. |
| `upload_file` | Stores a **small** screenshot or PDF sent as base64 inside the call (`name`, `content_base64`; PNG, JPEG, GIF, WebP or PDF; at most 4 MiB). Returns its `hash`, and a ready `markdown` image reference. |

### Proposing who takes a course (a person approves)

| Tool | What it does |
|---|---|
| `propose_enrolments` | Proposes people for a **published** course (`course_id`) or a collection (`path_id`): `emails`, and/or a `group` from the organisation's seats (`everyone` = every active seat except viewers, `members`, `authors`, `admins`); optional `due_date` (YYYY-MM-DD, today or later) and `reason` (shown to the person who decides; at most 500 characters). Creates **pending proposals, never enrolments**: nobody is enrolled or told until an author or admin approves them in Primer. Returns `proposed`, `already_enrolled` and `already_proposed` (not proposed again), `invalid` emails, and `expires_at`. At most 500 people per call. |
| `list_enrolment_proposals` | The organisation's proposals, newest first: person, course or collection, due date, reason, who it was proposed for, `state` (`pending`, `approved`, `declined`, `expired`), who decided and when, and the enrolment an approval made. Filter by `state`, `course_id`, `path_id`; pages like the reports. |

A proposal nobody decides **expires after 14 days** and is never approved by default. Approval
enrols the person exactly as a person's assignment does, with the approver recorded as the assigner
and the proposal recorded as made with AI for the person you act for.

To find who to propose, use the reports: e.g. `list_enrolments` with `course_id` for who already
has it (they are skipped anyway), or ask the person who the new starters are.

## Writing a course, as calls

1. Gather the material: Cornerstone (`get_context`, its documents) for what the organisation knows.
   Agree the outline with the person.
2. `create_course` with the title and audience → `course_id`.
3. `write_lesson` once per lesson, in order: `{"course_id": …, "module": {"title": "Claiming"},
   "lesson": {"title": "What you can claim", "kind": "text", "body": "…", "est_minutes": 5}}`.
   The first lesson naming a module title creates that module.
4. `get_course_draft` to read it back. Fix anything with `write_lesson` (pass `lesson.id` to
   replace), `reorder_lessons` and `delete_lesson`.
5. `submit_for_review`. Tell the person it is waiting for review in Primer, under the course, and
   that every lesson you wrote needs a person's approval before it can be published.

To change a **published** course: `list_courses` for its id, `start_new_version`, then steps 3–5. If
`draft_in_progress` is already true, someone is writing the next version: `get_course_draft` and
work on that one, with the person's agreement.

A draft in review is locked. If it needs more changes, a person returns it to draft in Primer; you
cannot.

## Sending files (screenshots and PDFs)

Two ways, with the same types (PNG, JPEG, GIF, WebP or PDF; never SVG or other markup), the same
4 MiB limit and the same storage. The result of either is a `hash` you use in `write_lesson`.

**When you can run a command (curl, or any HTTP client): use `request_upload`.** A real screenshot
as base64 is tens of thousands of tokens on one line: it costs a lot, can pass a read limit and can
be cut off. An upload link carries the raw bytes outside the conversation.

1. `request_upload` with the file's `name`, `content_type` and exact `size` in bytes.
2. PUT the raw file (not base64) to `upload_url` within **10 minutes**. No sign-in is needed: the
   address itself is the permission, so do not share it or write it into a lesson. For example:

   ```sh
   curl --fail-with-body -sS -X PUT -H 'Content-Type: image/png' \
     --upload-file ./step-1.png \
     'https://primer.instructedintelligence.com/api/uploads/<token>'
   ```

   The response is `{"upload_id", "hash", "name", "mime", "size", "markdown"}`.
3. Use the `hash` in `write_lesson`: a practice step's `image: {"hash": …}`, an attachment's
   `asset: {"hash": …}`, or `markdown` in a body. In `image` and `asset` the `upload_id` is
   accepted in place of the hash. Lost the response? `upload_status` returns it.

Rules: one file per link and **one PUT per link**; the first PUT uses it whatever the outcome, so
after a refusal (wrong type, larger than declared) call `request_upload` again. A PUT whose
`Content-Length` is over the declared size is refused before the link is used. The file is stored
in the organisation the link was made in, as uploaded by the person you act for; only that person
sees its status. Every link is audited (who asked, what was stored).

**When you cannot run commands (a chat-only AI app): use `upload_file`** with the file as base64,
for small files. Primer never fetches a file from an address you give it: send the bytes, never a
URL.

## Courses shared with the organisation

Another organisation (Instructed Intelligence, for example) can share some of its courses with the
one you act in. `list_courses` lists them with `source: "shared"` and `shared_by`, next to the
organisation's own (`source: "own"`).

- **Propose and report on them as the organisation's own.** `propose_enrolments`, `list_enrolments`
  and `list_completions` work on them; enrolment rows say `shared: true`. The learning, progress
  and completions belong to the organisation you act in.
- **Never change them.** The authoring tools (`write_lesson`, `get_course_draft`,
  `start_new_version`, `submit_for_review`, `delete_lesson`, `reorder_lessons`) refuse a shared
  course with "… is shared with your organisation by …". Tell the person that only the sharing
  organisation changes it, and that a person can click **Copy to customise** on the course in
  Primer to make the organisation's own copy. That copy is an ordinary draft you can then write.
- Sharing, stopping a share, copying and the organisation's support-visibility setting are a
  person's actions in Primer; there are no tools for them.

## Lesson formats

Every lesson has `title` (required), `kind`, and optionally `est_minutes` (0–600) and `citations`.
`id` and `provenance` are Primer's: omit `id` for a new lesson; `provenance` is ignored.

| Kind | Fields |
|---|---|
| `text` | `body`: Markdown (headings, lists, tables, links, code). Required. |
| `video_embed` | `video`: `{"provider": "youtube" \| "vimeo" \| "loom", "id": "<the video id>"}` (a YouTube id is 11 characters; Vimeo digits; Loom 32 hex). Not a URL. Optional `body` as a caption. |
| `attachment` | `asset`: `{"hash": "<from upload_file or an upload link>"}` (a PDF or image). Optional `body`. |
| `practice` | A hands-on "try it" over screenshots. `practice.steps`: 1–60 of `{"image": {"hash": …}, "instruction": "Click New course", "action": "click" \| "type", "expect": "<text to type; empty = any>", "hint": …, "feedback": …, "target": {"x", "y", "w", "h"}}`, the target box in fractions (0–1) of the image. Upload each screenshot first (`request_upload`, or `upload_file` for a small one). Optional `body` as an introduction. |
| `mockup` | A hands-on interactive mockup: `mockup.html` (self-contained HTML, CSS and script, at most 1 MiB; it runs sandboxed with no network, so no external scripts, fonts or images), optional `height` (200–2000 px) and `require_done` (the lesson completes only when the page posts `{type: "primer:complete"}` to its parent). It imitates a product screen; it is never the live product. |

- Images in Markdown must be Primer uploads: `![alt](/api/assets/<hash>)` (the `markdown` an upload returns).
  Links to images elsewhere, and raw HTML `<img>`, `<iframe>` or `<script>`, are refused.
- **Citations**: `[{"source": "cornerstone", "entity_id": "<Cornerstone entity id>", "title": "…"}]`
  on the lessons that rest on the organisation's facts, so a lesson can be checked against its
  source and flagged when that changes.
- A refusal says what is wrong and where ("module 2 lesson 3: a text lesson needs a body"). Fix
  that and call again; do not vary the call at random.

## Sizes and limits

Per proposal call: at most **500 people**. Per course version: at most **300 lessons**, **200 lessons in a module**, **100 modules**, and
**12 MiB** of lesson content. Per lesson: a body of at most **200,000 characters**; a mockup of at
most **1 MiB**; a practice lesson of at most **60 steps**. A file sent with `upload_file` or an upload
link: at most **4 MiB** (and an upload link: at most the size declared). An upload link lasts
**10 minutes** and works once. A refusal names the limit. A course that would be longer is several courses, grouped in a
collection by a person in Primer.

## Paging

`list_enrolments` and `list_completions` page with `offset` and `limit` (default 500, at most 1000)
and return `total` and `next_offset`. A response with `next_offset` is not the whole list: call
again with `offset` set to it until it is absent.

## The line: what Primer never does over MCP

You write and submit drafts, and propose enrolments. **A person** does everything that puts content
in front of learners or acts on people: publishing a course, approving lessons and versions,
returning a draft from review, archiving or retiring, approving or declining enrolment proposals,
enrolling or assigning people directly, sharing courses with other organisations or copying a
shared course, and revoking certificates. There are
no tools for these, and a call naming one is refused with "… is a person's action in Primer and is
never done over MCP". Do not offer to do them; tell the person the draft is waiting for them at
primer.instructedintelligence.com.

## Staying current

This guide is versioned (front matter above). The connect-time instructions name the current
version; if it is newer than the one you read, read it again. Cheap check:
`GET https://primer.instructedintelligence.com/mcp/prompt/version`.
