Skip to content

Cursor plugin specification and official plugins

TypeScript

Slim both skills to their behavior-changing core

Cursor Agenta2f9147c01be
diff --git a/origin-apps/README.md b/origin-apps/README.md
index 6e0ba067..c6e4f05f 100644
--- a/origin-apps/README.md
+++ b/origin-apps/README.md
@@ -8,27 +8,23 @@ in Cursor, Claude Code, Codex, and any agent that reads
## What it includes
-- `origin-api`: the general skill. Points the agent at the live docs and
- OpenAPI spec first (the only source for endpoints, scopes, and event slugs),
- then carries the practices that hold across spec versions: app, installation,
- and user credentials and just-in-time token minting; minimal scopes derived
- from `x-origin-scopes`; webhook subscription, `v1ed` signature verification,
- idempotent handling, and delivery behavior; opaque page tokens; TypeIDs; the
- error envelope; rate limits; and the deliberate differences from GitHub (no
- commit statuses, Issues, or GraphQL). Use it for any Origin work.
-- `port-github-app-to-origin`: builds on `origin-api` for one job. Run it
- inside your GitHub App's repository with no other instructions. It discovers
- the app's GitHub surface from the code (manifest, permissions, events
- handled, payload fields read, REST and GraphQL calls, token minting, webhook
- receiver, calls your framework makes for you), maps it onto the live spec,
- and writes a porting brief: a capability table, the webhook fields your
- handlers read and where each comes from on Origin, the scopes to request, a
- hello-world path to your first real event, gaps worth raising with Cursor,
- and the questions your team should settle first. It plans; it does not write
- port code, pick a language or SDK, or estimate in time.
-
-Both skills fetch the spec at run time and refuse to name an endpoint from
-memory, so their output tracks the API as published on the day you run them.
+- `origin-api`: the general skill. Fetch-first sources (the live OpenAPI spec
+ and docs are the only source for endpoints, scopes, and event slugs) plus a
+ checklist of the Origin gotchas GitHub instinct gets wrong: native vs
+ mirrored repositories, opt-in webhook events, `v1ed` signatures, `deliveryId`
+ idempotency, lean payloads, credential kinds and token minting, scopes from
+ `x-origin-scopes`, opaque page tokens, TypeIDs, `404` semantics, rate
+ limits, and the deliberate differences from GitHub. Use it for any Origin
+ work.
+- `port-github-app-to-origin`: builds on `origin-api`. Run it inside your
+ GitHub App's repository. It discovers the app's GitHub surface from the code,
+ maps it onto the live spec, and writes a porting brief: capability table,
+ webhook fields your handlers read and where each comes from on Origin,
+ scopes to request, hello-world path, gaps worth raising with Cursor, and the
+ questions to settle first. It plans; it writes no code and estimates no
+ time.
+
+Both fetch the spec at run time and never name an endpoint from memory.
## When to use
diff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.md
index 21165aa4..d670dc84 100644
--- a/origin-apps/skills/origin-api/SKILL.md
+++ b/origin-apps/skills/origin-api/SKILL.md
@@ -4,9 +4,8 @@ description: >-
Build on the Cursor Origin API: create an Origin App, authenticate as it,
call the REST API, receive webhooks. Use whenever code or a plan touches
Origin endpoints, installation tokens, scopes, webhook subscriptions or
- signatures, page tokens, or an Origin App manifest. Points at the live docs
- and spec first and carries only the practices that do not change between
- spec versions.
+ signatures, page tokens, or an Origin App manifest. Fetch-first sources plus
+ the gotchas GitHub instinct gets wrong.
license: MIT
compatibility: >-
Needs network access to https://cursor.com/docs/api/origin/* at run time.
@@ -14,160 +13,68 @@ compatibility: >-
# Build on the Origin API
-Origin is Cursor's code forge. Its API is GitHub-shaped (repos, pull requests,
-reviews, comments, check runs, labels, branches, commits) and deliberately not
-GitHub-compatible on the wire. This skill tells you where the contract lives
-and what stays true across versions of it. It does not restate endpoints,
-schemas, scope strings, or event slugs; those come from the spec you fetch.
-
-## Fetch the spec; do not trust memory
-
-Before naming any endpoint, scope, event slug, header, or field, fetch:
-
-- `https://cursor.com/docs/api/origin/llms.txt` — index of the docs
-- `https://cursor.com/docs/api/origin/openapi.yaml` — the contract (OpenAPI
- 3.1). Every operation carries `x-origin-scopes` (`scopes`, `tokenTypes`,
- `ambient`); every webhook payload schema carries `x-origin-webhook-events`
- (the slugs that deliver it) and often `x-origin-webhook-resource`;
- `x-cursor-visibility: PREVIEW` marks operations whose shape may still move.
-- `https://cursor.com/docs/api/origin/llms-full.txt` — the prose the spec
- cannot carry: installation flow, authentication, scopes table, mirrored
- repositories, webhook headers and signature verification, delivery
- envelope, retries, pagination, errors, current limitations
-- `https://cursor.com/docs/api/origin/changelog` — what moved recently
-
-Cite `operationId`s and `llms-full.txt` anchors in anything you write. Record
-`info.version` and the fetch time when the output will outlive the session.
-Where this file and the fetched docs disagree, the docs win.
-
-## Practices that hold across spec versions
-
-### Credentials
-
-- Three principals, in order of power: **user** credential (admin actions:
- create the app, add repositories to an installation, mirror transitions),
- **app** JWT (EdDSA over Ed25519; register only the public key; identifies
- the app to app-level operations), **installation** token (`oit_…`,
- short-lived, minted from the app JWT for one installation; the credential
- for repository work). Check an operation's `x-origin-scopes.tokenTypes` to
- see which it accepts.
-- Mint installation tokens just in time and let them expire; never persist
- one as a long-lived secret. Attenuate at mint time to the scopes and
- `repositoryIds` the job needs (IDs, not slugs).
-- The installation **receipt** JWT returned from the install redirect proves
- consent and carries the installation ID. It is never a Bearer token.
-- Git over HTTPS uses Basic auth with username `x-access-token` and an
- installation token as the password; Bearer is for REST only.
-
-### Scopes
-
-- Scopes are `repository:<noun>[:<sub>]:<read|write>`; `write` implies `read`;
- `repository:metadata:read` comes with every installation.
-- Request the union of `x-origin-scopes.scopes` across the operations you
- actually call, nothing more. An installation can only narrow what the admin
- approved, so an over-broad manifest is a review burden, not a convenience.
-- `ambient: true` means the credential already carries the scope; there is
- nothing to request for it.
-
-### Repositories
-
-- Apps act on Origin-native repositories. A repository mirrored *from* GitHub
- is read-only to an installation (writes return `403`) and does not deliver
- `repository.pushed`, because GitHub already notifies apps for it. Confirm
- native-or-mirror before anything else; a mirror produces a successful ping
- and then silence.
-
-### Webhooks
-
-- Only installation lifecycle events are delivered by default. Every other
- event must be selected in app settings. Take the slug list from
- `x-origin-webhook-events`, not from GitHub habit.
-- Verify before parsing. Scheme `v1ed`: Ed25519 over a SHA-256 digest of the
- raw body, keys from Origin's JWKS (cache per `Cache-Control`; keys rotate).
- Reject `webhook-timestamp` more than five minutes off. It follows Standard
- Webhooks except for signing a digest, so off-the-shelf verifiers do not
- validate it unmodified. Routing headers are `webhook-*`, not `x-github-*`;
- after verification the body is authoritative.
-- Handle idempotently. `deliveryId` in the envelope is stable across retries
- and is the dedupe key; `event.id` identifies the domain event. Delivery is
- at-least-once.
-- Acknowledge fast, process later. Retries follow a schedule and persistent
- failure pauses delivery for the app; the recovery window is finite and
- redelivery is through the deliveries operations, so a slow handler costs
- you events. Return `2xx` after verification and enqueue.
-- Payloads are lean snapshots of the one object that changed, plus compact
- references to its containers. No changed-file lists, before-SHAs, web URLs,
- or inlined profiles. The intended pattern is a follow-up `Get…` with the
- identifiers the payload carries; count that fan-out when you design.
-- The action lives in the slug (`pull_request.created`,
- `pull_request.review.submitted`); there is no `action` field and no
- `previous_attributes` delta.
-
-### Pagination
-
-- `pageSize` / `pageToken` / `nextPageToken`. Tokens are opaque and bound to
- the resource and filters: never construct, parse, persist across filter
- changes, or share them between requests with different parameters.
-- Pass `pageSize` on every request, including continuations; do not rely on
- the token to remember it. No `Link` header, no page numbers, no total count.
- Loop until `nextPageToken` is absent or empty.
-
-### Identifiers and wire shape
-
-- IDs are opaque prefixed TypeIDs (`app_…`, `i_…`, `repo_…`, `user_…`,
- `cmt_…`). Never integers, never derived. Cache IDs, not slugs; a repository
- is addressable as `/repos/_/{repoId}`, which survives renames.
-- camelCase JSON; 64-bit integers (PR numbers, versions) are JSON strings;
- RFC 3339 timestamps; defaults are present (`false`, `0`, `""`, `[]`), so a
- present `false` is a value and a missing key is only the default when the
- field is documented optional.
-- Public terminology is "pull request"; do not look for "change" on the wire.
-
-### Errors
-
-- One envelope: `google.rpc.Status` `{code, message, details}` with typed
- `details` (`BadRequest` field violations, `RequestInfo` with the request
- id; more types may appear, so tolerate unknown ones). `X-Request-ID` is on
- every error; quote it when escalating.
-- `404` does not distinguish not-found from no-access. Branch on HTTP status
- and `code`, never on message text.
-
-### Rate limits
-
-- A per-principal point budget: read `X-RateLimit-*` on every response and
- honor `Retry-After` on `429`. Git over HTTPS is metered separately
- (`X-RateLimit-Resource: git`). Cursor raises per-app budgets on request;
- ask rather than spinning.
-
-### Deliberate differences from GitHub
-
-Design decisions, not gaps. Build the Origin idiom instead of emulating the
-GitHub one:
-
-- **No commit statuses.** Check runs are the one status primitive; they upsert
- on a caller-stable `key` and rulesets bind on that key.
-- **No Issues.** Conversation is pull request comments, threads, reviews, and
- labels on pull requests.
-- **No GraphQL.** REST only; decompose queries and accept the fan-out.
-- **No per-repository webhook CRUD.** Subscriptions are app settings.
-- **No user or email directory**, no team pages; actors are TypeIDs (plus a
- handle where the contract exposes it).
-- **Reviews anchor to a pull request version**, not a commit SHA.
-- **No standalone threads API.** A thread materializes from its first
- diff-anchored comment.
-
-## Hello-world path
-
-Create the app (form or user-credential `CreateApp`) → register the Ed25519
-public key → select webhook events → install on an Origin-native repository →
-verify the ping signature → mint an installation token → first `Get…` → first
-real event. Each arrow is a step to observe, not code to write; when a step
-is silent, the answer is almost always native-or-mirror or an unsubscribed
-event.
-
-## Related skill
-
-`port-github-app-to-origin`, in this plugin, applies these fundamentals to
-an existing GitHub App: it discovers the app's GitHub surface from code, maps
-it onto the spec, and writes a porting brief. Use it for a port; use this
-skill for everything else on Origin.
+## Fetch first; never name an endpoint, scope, slug, or header from memory
+
+- `https://cursor.com/docs/api/origin/openapi.yaml` — the contract. Every
+ operation carries `x-origin-scopes` (`scopes`, `tokenTypes`, `ambient`);
+ every webhook payload schema carries `x-origin-webhook-events`, the only
+ authoritative list of subscribable slugs.
+- `https://cursor.com/docs/api/origin/llms-full.txt` — installation flow,
+ authentication, scopes table, mirrored repositories, webhook headers and
+ verification, delivery envelope, retries, pagination, errors, limitations.
+- `https://cursor.com/docs/api/origin/llms.txt` (index) and
+ `https://cursor.com/docs/api/origin/changelog` (what moved).
+
+Cite `operationId`s and `llms-full.txt` anchors. Where this file and the
+fetched docs disagree, the docs win.
+
+## Gotchas
+
+- **Native or mirror, first.** Apps get full scopes only on Origin-native
+ repositories. A repository mirrored from GitHub returns `403` on every write
+ and never delivers `repository.pushed`; the ping succeeds and then nothing
+ else arrives.
+- **Only installation lifecycle events are delivered by default.** Select
+ every other event in app settings; an unselected event is silence, not an
+ error.
+- **Signature `v1ed` is Ed25519 over a SHA-256 digest of the raw body**, keys
+ from Origin's JWKS. It is Standard Webhooks except for the digest, so
+ off-the-shelf verifiers fail unmodified. Verify the raw body before parsing;
+ reject `webhook-timestamp` more than five minutes off. Headers are
+ `webhook-*`, not `x-github-*`; after verification the body is authoritative.
+- **`deliveryId` is the idempotency key** (stable across retries);
+ `event.id` is the domain event. Return `2xx` after verification and process
+ asynchronously: persistent failure pauses delivery for the app.
+- **Payloads are lean snapshots** of the one object that changed plus
+ container references: no changed-file lists, before-SHAs, web URLs, or
+ inlined profiles. Follow up with the `Get…` for the object; count the
+ fan-out. The action is in the slug (`pull_request.review.submitted`); there
+ is no `action` field.
+- **The installation receipt JWT is proof of consent, never a Bearer token.**
+ Its `sub` is the installation ID.
+- **App JWT is EdDSA over Ed25519, not RS256.** Register only the public key.
+- **Installation tokens are short-lived; mint just in time** from the app JWT
+ and attenuate to the scopes and `repositoryIds` the job needs (IDs, not
+ slugs). Git over HTTPS is Basic auth, user `x-access-token`, token as
+ password; Bearer is REST only.
+- **Scopes come from the operations you call**: request the union of their
+ `x-origin-scopes.scopes`. `write` implies `read`; `repository:metadata:read`
+ is automatic; `ambient: true` needs no request. Operations whose
+ `tokenTypes` is user-only (create app, add repositories to an installation,
+ mirror transitions) have no app-side path; there is no `/user` analog.
+- **Page tokens are opaque and bound to the resource and filters.** Never
+ construct, parse, or reuse across filter changes. Send `pageSize` on every
+ request, including continuations. No `Link` header, no total.
+- **IDs are TypeIDs** (`repo_…`, `i_…`, `cmt_…`), never integers. Cache IDs,
+ not slugs; `/repos/_/{repoId}` survives renames. 64-bit integers (PR
+ numbers, versions) are JSON strings. Defaults are present (`false`, `0`,
+ `[]`), so a present `false` is a value.
+- **`404` is not-found *or* no-access.** Branch on status and `code`, never
+ message text. Quote `X-Request-ID` when escalating.
+- **Rate limit is a per-principal point budget**; honor `Retry-After` on
+ `429`. Git HTTPS is metered separately. Per-app raises exist; ask.
+- **Deliberate differences, not gaps:** no commit statuses (check runs upsert
+ on a caller-stable `key`); no Issues (conversation is PR comments, threads,
+ reviews, labels); no GraphQL; no per-repository webhook CRUD; no user or
+ email directory; reviews anchor to a pull request *version*, not a SHA; a
+ thread materializes from its first diff-anchored comment.
diff --git a/origin-apps/skills/port-github-app-to-origin/SKILL.md b/origin-apps/skills/port-github-app-to-origin/SKILL.md
index 08083651..dbccfa72 100644
--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md
+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md
@@ -15,112 +15,62 @@ compatibility: >-
# Port a GitHub App to an Origin App
-Run this inside the codebase of an existing GitHub App, with no other
-instructions needed. The output is a **porting brief**
-(`references/brief-template.md`), not an implementation. "The team" below
-means the people who own this app; if you are running this yourself, that is
-you. The team keeps its language, framework, and client strategy; the brief
-tells them what maps, what changes shape, what is absent on purpose, and what
-is worth raising with Cursor.
+Run inside the GitHub App's codebase. Output is a **porting brief**
+(`references/brief-template.md`), not an implementation: what maps, what
+changes shape, what is absent on purpose, what is worth raising with Cursor.
-Fundamentals come from the `origin-api` skill in this plugin: which docs to
-fetch, credentials and token minting, scopes, webhook verification and
-idempotency, pagination, TypeIDs, errors, rate limits, and the list of
-deliberate departures from GitHub. Follow it first; this skill adds only what
-a port needs on top. Two rules shape the porting work:
+Fundamentals (which docs to fetch, credentials, scopes, webhooks, paging,
+IDs, errors, deliberate differences) are the `origin-api` skill in this
+plugin. Follow it first; nothing here repeats it. Two rules on top:
-1. **Discover, do not ask.** Read the manifest, permission declarations, event
- handlers, token minting, API calls, and webhook receiver out of the code.
- Never ask anyone to paste a manifest or list their endpoints. If something
- is genuinely undiscoverable, record it as an open question in the brief.
-2. **Classify departures as decisions, not omissions.** A GitHub feature that
- Origin deliberately does not reproduce is `by-design-absent` with a pointer
- to the Origin idiom, never a gap card. Nothing in this skill pins a spec
- version or enumerates endpoints; every concrete example in `references/`
- is illustrative until confirmed against today's spec.
+1. **Discover, do not ask.** Read permissions, events, handlers, calls, token
+ minting, and the receiver out of the code. Never ask for a manifest or an
+ endpoint list. What is genuinely undiscoverable becomes an open question.
+2. **Departures are decisions, not omissions.** Anything in
+ `references/origin-isms.md` is `by-design-absent` or `reshaped` with a
+ pointer to the idiom, never a gap card.
## Procedure
-### 1. Load the live Origin surface
-
-Fetch the four URLs from `origin-api` § Fetch the spec and keep them open for
-the run. Record `info.version` and the fetch time in the brief's provenance
-block; that is provenance, not a dependency, and the brief says so.
-`references/spec-mapping.md` explains how to turn the spec's `x-origin-*`
-extensions into the mapping index every later step looks things up in.
-`scripts/index-origin-spec.py <openapi.yaml>` prints that index (operations
-with scopes, parameters, and response fields; webhook slugs with payload
-fields; the scope catalog) so you can grep it instead of paging through 700 KB
-of YAML; it needs python3 with PyYAML and does nothing else.
-
-### 2. Discover the GitHub App's shape
-
-Follow `references/discovery.md`. Produce an inventory with a file and line for
-every fact: declared permissions and events, webhook events handled, payload
-fields the handlers read, REST and GraphQL calls, authentication flow, webhook
-receiver and signature verification, calls made on the app's behalf by its
-framework and helper libraries, and the observed language and client
-libraries (observed, never chosen). Note what you looked for and did not find.
-
-### 3. Map each capability onto Origin
-
-For each inventory row, look up the Origin counterpart in the spec index built
-in step 1 (`references/spec-mapping.md` § Matching rules), then classify it
-with one of the parity labels in `references/brief-template.md`. Before
-labeling anything `gap`, check `references/origin-isms.md`: a GitHub feature
-that Origin deliberately does not reproduce is `by-design-absent` with a
-pointer to the Origin idiom, and the brief must say what to do instead rather
-than raise it. Then apply the bar in `references/gap-bar.md`; only rows that
-clear it become gap cards.
-
-Map webhook payload *fields* the code reads, not just event names. Origin
-payloads are lean row snapshots; a field GitHub inlines is often a follow-up
-REST read on Origin. Say which call, per field.
-
-Two labels are easy to misuse. A GitHub surface with no Origin counterpart
-*and* no mention anywhere in the Origin docs (Marketplace billing, merge
-queues, Actions, Pages) is `unknown` with a question, not a `gap`: Origin has
-not said no, and the team may not need it. A behavior the code depends on
-that the docs neither confirm nor deny (does event X fire in case Y? does
-`updatedAt` move on comments?) is also a question, plus a step on the
-hello-world path to observe it; never guess it into `same`.
-
-### 4. Write the brief
-
-Fill `references/brief-template.md` in full. Every table cell that names an
-Origin operation, event, or field links to its anchor in `llms-full.txt` or
-names its `operationId`. Sizes are S/M/L as defined in the template, never
-time. The hello-world path is the sequence Create App → subscribe events →
-install → verify ping signature → first real event on a native repository;
-it is a checklist of things to verify, not code.
-
-### 5. Ask the up-front questions
-
-Close the brief with the questions in the template's final section, pruned to
-what the discovery left open and extended with anything specific you found.
-The first question is always whether the target repositories are Origin-native
-or mirrored from GitHub, because that decides whether the app will receive
-real events at all.
-
-## What this skill does not do
-
-- Write, scaffold, or vibecode port code, adapters, or SDK wrappers.
-- Choose a language, framework, HTTP client, or codegen strategy.
-- Estimate effort in hours, days, or sprints.
-- Pin the spec version, copy endpoint lists into the brief from memory, or
- claim parity from a name match without reading the operation.
-- Ask for information the codebase already contains.
-- Contact Cursor on the team's behalf; the brief carries the escalation cards
- and the team decides what to send and where.
+1. **Load the spec** (`origin-api` § Fetch first). Record `info.version` and
+ the fetch time for the brief's provenance. Build the mapping index per
+ `references/spec-mapping.md`; `scripts/index-origin-spec.py openapi.yaml`
+ prints it (needs PyYAML).
+2. **Discover** per `references/discovery.md`: a file and line for every fact,
+ including payload fields read only for logging and calls the framework
+ makes on the app's behalf. Note what you looked for and did not find.
+3. **Map** each inventory row (`references/spec-mapping.md` § Matching) and
+ label it with the parity labels in the brief template. Map webhook payload
+ *fields* the code reads, not just event names; a field GitHub inlines is
+ often a follow-up read on Origin, so name the call per field. Then:
+ - `origin-isms.md` before `gap`; `gap-bar.md` before any card.
+ - A GitHub surface the Origin docs never mention (Marketplace billing,
+ merge queues, Actions, Pages) is `unknown` with a question, never `gap`.
+ - A behavior the code depends on that the docs neither confirm nor deny
+ (does event X fire in case Y? does `updatedAt` move on comments?) is a
+ question plus a hello-world step that observes it; never guess it into
+ `same` from GitHub behavior.
+4. **Write the brief** from the template in full. Every Origin cell names an
+ `operationId`, slug, or `llms-full.txt` anchor. Sizes are S/M/L, never
+ time.
+5. **Close with the questions**, pruned to what discovery left open. The
+ first is always native-or-mirror: it decides whether the app receives
+ events at all.
+
+## Not in scope
+
+Writing port code or adapters; choosing a language, framework, or client;
+estimating in time; asking for anything the codebase contains; sending gap
+cards to Cursor (the brief carries them; the team decides).
## Reference files
| File | Read when |
| --- | --- |
-| `../origin-api/SKILL.md` | Always, first: the docs to fetch and the fundamentals every mapping row assumes. |
-| `references/spec-mapping.md` | Building the spec index and matching GitHub calls, events, and payload fields to Origin operations, slugs, and schemas. |
-| `references/discovery.md` | Scanning the codebase for the app's GitHub surface. |
-| `references/origin-isms.md` | Deciding whether a missing GitHub feature is a decision or a gap, and what the Origin idiom is, with the reasoning a team that only knows GitHub needs. |
-| `references/gap-bar.md` | Deciding whether a gap is worth raising with Cursor, and writing the card. |
+| `../origin-api/SKILL.md` | First. Sources and fundamentals. |
+| `references/discovery.md` | Scanning the codebase. |
+| `references/spec-mapping.md` | Building the index; matching calls, events, and fields. |
+| `references/origin-isms.md` | Labeling a missing GitHub feature. |
+| `references/gap-bar.md` | Deciding whether a difference earns a card; writing it. |
| `references/brief-template.md` | Writing the output. |
-| `scripts/index-origin-spec.py` | Turning the fetched `openapi.yaml` into a grep-friendly index (operations, webhook families, scopes, one component). Optional; needs PyYAML. |
+| `scripts/index-origin-spec.py` | Turning `openapi.yaml` into a grep-friendly index. Optional. |
diff --git a/origin-apps/skills/port-github-app-to-origin/references/brief-template.md b/origin-apps/skills/port-github-app-to-origin/references/brief-template.md
index 7642ca1d..f20b5ae3 100644
--- a/origin-apps/skills/port-github-app-to-origin/references/brief-template.md
+++ b/origin-apps/skills/port-github-app-to-origin/references/brief-template.md
@@ -1,40 +1,33 @@
# Porting brief template
-Write the brief as one Markdown file at the repository root
-(`ORIGIN-PORTING-BRIEF.md` unless the team's docs convention says otherwise)
-and print its path. Fill every section; where a section is genuinely empty,
-say so in one line rather than deleting it, so the team can see it was
-considered. Cite spec `operationId`s and `llms-full.txt` anchors; cite the
-team's code by `file:line`.
+One Markdown file at the repository root (`ORIGIN-PORTING-BRIEF.md` unless the
+team's docs convention says otherwise); print its path. Fill every section; an
+empty section says so in one line rather than disappearing. Cite spec
+`operationId`s and `llms-full.txt` anchors; cite the team's code by
+`file:line`. A table row per capability, a line per follow-up field, a card
+per gap; the team will argue over it in one sitting.
-Keep it light. A table row per capability, a line per follow-up field, a card
-per gap. The team will read this in one sitting and then argue about it; give
-them the shape to argue over, not prose.
-
-## Labels used in the tables
+## Labels
**Parity**
| Label | Meaning |
| --- | --- |
| `same` | Same capability, same shape; a path or field rename at most. |
-| `reshaped` | Same capability, different shape: pagination style, identifier form, event granularity, key semantics. The code changes, the behavior does not. |
-| `workaround` | Same outcome reachable with existing surface by a different route (follow-up read, client-side filter, marker). Tradeoff column is mandatory. |
-| `by-design-absent` | GitHub feature Origin deliberately does not reproduce (`origin-isms.md`). Points at the Origin idiom or says "no equivalent; decision needed". |
-| `gap` | No workaround, or a workaround whose tradeoff fails the bar (`gap-bar.md`). Has a card in § Gaps worth raising. |
-| `unknown` | Discovery could not determine the app's use or the spec's answer. Has an up-front question. |
-| `preview` (suffix) | The Origin operation is stamped `x-cursor-visibility: PREVIEW`. Usable; shape may still move. |
+| `reshaped` | Same capability, different shape (pagination, identifier form, event granularity, key semantics). Code changes, behavior does not. |
+| `workaround` | Same outcome by a different route (follow-up read, client-side filter, marker). Tradeoff column mandatory. |
+| `by-design-absent` | Origin deliberately does not reproduce it (`origin-isms.md`). Names the idiom or "no equivalent; decision needed". |
+| `gap` | No workaround, or one that fails `gap-bar.md`. Has a card in § 6. |
+| `unknown` | Discovery or the spec could not answer. Has a question in § 7. |
+| `preview` (suffix) | Origin operation is `x-cursor-visibility: PREVIEW`. Usable; shape may move. |
-**Size** — how much of the team's code changes for this row, by kind of
-change, never by time:
+**Size** (kind of change, never time)
| Size | Meaning |
| --- | --- |
-| S | Contained in the adapter or client layer: a path, header, identifier, or pagination rewrite; a re-keyed lookup. |
-| M | A new code path: a follow-up read where the payload used to suffice, a handshake step, a new event handler, a data-model change for a new identifier or version concept. |
-| L | A product or architecture change: a flow that depended on user OAuth, a customer-visible behavior, a dependency on the customer's repositories being Origin-native, or a capability with an open gap card. |
-
----
+| S | Adapter or client layer: path, header, identifier, or pagination rewrite; re-keyed lookup. |
+| M | New code path: a follow-up read where the payload sufficed, a handshake step, a new handler, a data-model change for a new identifier or version concept. |
+| L | Product or architecture change: a flow that depended on user OAuth, a customer-visible behavior, a dependency on native repositories, an open gap card. |
## Template
@@ -42,144 +35,116 @@ change, never by time:
# Origin porting brief — <app name>
Planning document. Maps this GitHub App's surface onto the Cursor Origin API
-as published on <date>. Contains no implementation decisions about language,
-framework, or client strategy.
+as published on <date>. No decisions about language, framework, or client.
## Provenance
- Origin OpenAPI `info.version`: `<value>`, fetched <timestamp>
-- Docs read: <the four URLs>
-- Codebase: `<repo>` at `<commit>`; scanned <n> files
-- Rows marked `workaround` or `gap` should be re-checked against the changelog before work starts; they are the rows most likely to have moved.
+- Docs read: <the URLs>
+- Codebase: `<repo>` at `<commit>`
+- Re-check `workaround` and `gap` rows against the changelog before work
+ starts; they move most.
## 1. What the app is today
-One paragraph in plain words: what the app does for its users, which GitHub
-events drive it, what it writes back. Then the inventory:
+One paragraph: what it does for its users, which events drive it, what it
+writes back. Then:
| Facet | Finding | Evidence |
| --- | --- | --- |
-| Manifest / declared permissions | … or "none checked in; permissions derived from calls" | `file:line` |
-| Declared / handled events | `pull_request.opened`, … | `file:line` |
-| REST call families | <count>, listed in § 3 | |
+| Manifest / declared permissions | … or "none checked in; derived from calls" | `file:line` |
+| Events handled | … | `file:line` |
+| REST call families | <count>, in § 3 | |
| GraphQL | none / <count> documents, decomposed in § 3 | |
| Auth flow | app JWT (<alg>) → installation token; user OAuth: <yes/no, for what> | `file:line` |
-| Webhook receiver | path, verification scheme, raw-body availability, dedupe | `file:line` |
+| Webhook receiver | path, scheme, raw-body availability, dedupe | `file:line` |
| Git as the app | clone / push / none | `file:line` |
-| Observed language and libraries | … (observed only) | |
+| Observed language and libraries | … | |
| Looked for, not found | … | |
## 2. First decision: which repositories
-<State what the code assumes about the repositories it acts on.> On Origin,
-an installation has full scopes only on Origin-native repositories and
-stable outbound mirrors; repositories mirrored from GitHub are read-only to
-apps and do not deliver push events. **Question 1 below must be answered
-before the hello-world path is attempted.**
+<What the code assumes about the repositories it acts on.> Apps have full
+scopes only on Origin-native repositories and stable outbound mirrors;
+repositories mirrored from GitHub are read-only to apps and deliver no push
+events. **Question 1 must be answered before § 5 is attempted.**
## 3. Capability table
-One row per GitHub capability the code uses. Group rows by facet
-(authentication, installation & discovery, repositories & contents, pull
-requests, reviews & comments, checks, webhooks, git). Follow-up fields go in
-§ 4, not here.
+One row per GitHub capability the code uses, grouped by facet with a bold
+header row (Authentication · Installation & discovery · Configuration ·
+Repositories & contents · Pull requests · Reviews & comments · Checks ·
+Webhooks: events · Webhooks: receiver · Git). Include rows for calls a
+dependency makes on the app's behalf, marked as such.
| GitHub thing (evidence) | Origin equivalent | Parity | Size | Tradeoff | Open question |
| --- | --- | --- | --- | --- | --- |
-| `GET /repos/{o}/{r}/pulls/{n}` (`src/x.ts:12`) | `OriginService_GetPullRequest` | same | S | — | — |
-| … | … | … | … | … | … |
-
-Rules for the table: the Origin column names an `operationId`, an event
-slug, a `llms-full.txt` anchor, or `none`; `workaround` rows always fill
-Tradeoff; `gap` rows link their card; `by-design-absent` rows name the idiom
-in the Tradeoff column; `unknown` rows name their question. Group rows by
-facet with a bold header row (Authentication · Installation & discovery ·
-Configuration · Repositories & contents · Pull requests · Reviews & comments
-· Checks · Webhooks: events · Webhooks: receiver · Git), and include rows
-for calls a dependency makes on the app's behalf, marked as such.
-
-**Scopes to request** (one line under the table): the union of
-`x-origin-scopes.scopes` across every Origin operation named above that an
-installation token can call, minus scopes that are ambient or implied
-(`write` implies `read`; `repository:metadata:read` is automatic). This is
-what the install URL's `scope` parameter carries, so the team can read it
-straight off the brief.
+| `GET /repos/{o}/{r}/pulls/{n}` (`src/x.ts:12`) | `<operationId>` | same | S | — | — |
-## 4. Webhook payload fields the code reads
+The Origin column names an `operationId`, a slug, a `llms-full.txt` anchor,
+or `none`. `workaround` rows fill Tradeoff; `gap` rows link their card;
+`by-design-absent` rows name the idiom; `unknown` rows name their question.
+
+**Scopes to request:** the union of `x-origin-scopes.scopes` across every
+Origin operation above that an installation token can call, minus ambient
+and implied scopes (`write` implies `read`; `repository:metadata:read` is
+automatic). This is what the install URL's `scope` parameter carries.
-For each mapped event, the fields the handlers dereference.
+## 4. Webhook payload fields the code reads
| Event (GitHub → Origin) | GitHub field | Origin | How |
| --- | --- | --- | --- |
-| `pull_request.synchronize` → `pull_request.head_ref.pushed` | `pull_request.head.sha` | present | `payload.pullRequest.head.sha` |
-| `push` → `repository.pushed` | `commits[].added` | follow-up read | `OriginService_ListComparisonFiles` on `refUpdates[].before..after` — one call per ref update |
-| … | `repository.html_url` | derivable / absent | … |
+| `pull_request.synchronize` → `<slug>` | `pull_request.head.sha` | present | `payload.pullRequest.head.sha` |
+| `push` → `<slug>` | `commits[].added` | follow-up read | `<operationId>`, one call per ref update |
"How" is one of: present at `<path>`; present in envelope (`event.type` for
-GitHub's `action`); follow-up read via `<operationId>` (state the call count
-per event); derivable (say from what, and whether the format is documented);
-absent (→ § 3's label for that row: `by-design-absent`, `unknown`, or a § 6
-card). Include fields the code reads only for logging; they are the ones
-teams forget until a dashboard breaks.
+GitHub's `action`); follow-up read via `<operationId>` with the call count
+per event; derivable (from what; is the format documented); absent (→ § 3's
+label). Include fields read only for logging.
## 5. Hello-world path
-The shortest route to one real event from one native repository. Each step
-is something to verify, not code to write. Link each to `llms-full.txt`.
-Append one step per spec-silent behavior the brief depends on (see the
-questions), stated as the observation to make.
-
-1. **Create the app** in the target namespace's app settings; register the
- Ed25519 public key only; set the webhook URL and the callback URI.
-2. **Subscribe to events.** Installation lifecycle events arrive regardless;
- select every repository event from § 3 explicitly. An unselected event is
- silence, not an error.
-3. **Install** on an Origin-native repository (or a stable outbound mirror).
- Verify the installation receipt (`kid` → JWKS, `alg`, `typ`, `iss`, `aud`,
- `exp`, `state`); read the installation ID from `sub`. Never send the
- receipt as a Bearer token.
-4. **Mint** an app JWT (EdDSA, ~5 min) and exchange it for an installation
- token; call `/installation/repos` and confirm the repository is listed
- and its `mirror` state is what § 2 expects.
-5. **Ping** the receiver and verify `v1ed` over the raw body against the
- JWKS; check timestamp skew handling and `webhook-id` dedupe.
-6. **First real event**: perform the smallest action in § 3 on the native
- repository (open a PR, push a branch) and confirm the delivery arrives
- with the expected slug and the payload fields from § 4. If the ping
- arrived and this did not, re-check steps 2 and 3 before anything else.
-7. **First write back** (if the app writes): the smallest write from § 3
- (a check run with a stable `key`, a PR comment), confirming the scope
- from `x-origin-scopes` is in the installation grant.
+Shortest route to one real event from one native repository. Each step is a
+verification, linked to `llms-full.txt`; append one step per spec-silent
+behavior the brief depends on, stated as the observation to make.
+
+1. Create the app; register the Ed25519 public key; set webhook URL and
+ callback.
+2. Select every repository event from § 3 in app settings.
+3. Install on an Origin-native repository; verify the receipt JWT and read
+ the installation ID from `sub`.
+4. Mint an app JWT, exchange for an installation token, confirm the
+ repository is listed and its mirror state matches § 2.
+5. Verify the ping (`v1ed` over the raw body, timestamp skew, `deliveryId`
+ dedupe).
+6. Perform the smallest action in § 3 and confirm the slug and the § 4
+ fields arrive. Ping but no event: re-check steps 2 and 3 first.
+7. Smallest write from § 3 (check run with a stable `key`, PR comment),
+ confirming its scope is in the grant.
## 6. Gaps worth raising
-Zero or more cards in the `gap-bar.md` shape. If zero, say: "No row failed
-the gap bar; the workarounds in § 3 carry their tradeoffs." Do not pad.
+Zero or more cards in the `gap-bar.md` shape. If zero: "No row failed the gap
+bar; the workarounds in § 3 carry their tradeoffs." Do not pad.
## 7. Questions for the team
-Pruned to what discovery left open, plus anything specific found. Always
-starts with the first three.
-
-1. Will the app run against Origin-native repositories (or stable outbound
- mirrors), or against repositories mirrored from GitHub? (Decides whether
- the app receives events and can write at all.)
-2. Which of the follow-up reads in § 4 are acceptable at your event volume,
- and which payload fields are hard requirements?
-3. Which flows depend on a user credential today (user OAuth, install-by-user
- pickers, acting on behalf of a user), and what should they do on Origin?
-4. Does anything key approvals or reviews by commit SHA rather than by pull
- request version?
-5. Do you generate clients from OpenAPI? (Then read the changelog for schema
- renames and check reserved names in your language.)
-6. How do you identify your own check runs / comments / reviews today, and
- can a key or marker you control replace actor matching?
-7. What is your first success metric: ping received, first real event, or
- first write back on a native repository?
-8. Anything marked `unknown` in § 1 or § 3.
-
-## 8. Out of scope for this brief
-
-No implementation, no SDK or language choice, no effort estimates in time.
-The brief is a map; the route is the team's.
+Always the first three; then what discovery left open.
+
+1. Native repositories (or stable outbound mirrors), or repositories mirrored
+ from GitHub? Decides whether the app receives events and can write.
+2. Which follow-up reads in § 4 are acceptable at your event volume, and
+ which payload fields are hard requirements?
+3. Which flows depend on a user credential today, and what should they do on
+ Origin?
+4. Does anything key approvals or reviews by commit SHA rather than PR
+ version?
+5. How do you identify your own check runs / comments / reviews today; can a
+ key or marker you control replace actor matching?
+6. Do you generate clients from OpenAPI? (Read the changelog for renames.)
+
+## 8. Out of scope
+
+No implementation, no SDK or language choice, no time estimates. The brief is
+a map; the route is the team's.
```
diff --git a/origin-apps/skills/port-github-app-to-origin/references/discovery.md b/origin-apps/skills/port-github-app-to-origin/references/discovery.md
index fb353213..a6258c3b 100644
--- a/origin-apps/skills/port-github-app-to-origin/references/discovery.md
+++ b/origin-apps/skills/port-github-app-to-origin/references/discovery.md
@@ -1,147 +1,56 @@
# Discovering the GitHub App's shape from the codebase
-Everything the brief needs about the existing app is in the repository. Search
-for it; do not ask for it. Record a file and line for every fact so the team
-can check your reading, and record every place you looked that turned up
-nothing so they can point you at the right place if you missed it.
-
-Work through the seven facets below. The searches are starting points across
-the common ecosystems (Node Octokit and Probot, Go `go-github`, Python
-`PyGithub`/`ghapi`/`githubkit`, Java `hub4j`, Ruby `octokit.rb`, .NET
-`Octokit.net`, raw HTTP in any language); extend them when the code uses
-something else. Note the language and libraries you observe as a fact in the
-inventory — they inform sizes in the brief and nothing else.
-
-## 1. Declared permissions and events
-
-The app's manifest or registration snapshot, if it is checked in.
-
-- Files: `app.yml`, `app.yaml`, `.github/app.yml`, `github-app-manifest.json`,
- `manifest.json`, `app-manifest.*`, Terraform or Pulumi resources for the
- app, and infrastructure-as-code that seeds a GitHub App.
-- Keys: `default_permissions`, `default_events`, `hook_attributes`,
- `redirect_url`, `callback_urls`, `setup_url`, `public`,
- `request_oauth_on_install`, `setup_on_update`.
-- Probot: `app.yml` at the repo root carries `default_events` and
- `default_permissions`.
-
-When there is no manifest, derive the effective permissions from the calls in
-facet 4 and say the manifest was absent. The union of what the code calls is
-what the port needs anyway.
-
-## 2. Webhook events handled
-
-- Probot / `@octokit/webhooks`: `app.on("<event>.<action>", …)`,
- `app.on([...])`, `webhooks.on(`, `webhooks.onAny(`, `EmitterWebhookEvent`.
-- Hand-rolled receivers: a `switch` or dispatch on the `x-github-event` header
- (any casing), on `payload.action`, or on a combined `"<event>.<action>"`
- string; Go `github.WebHookType(r)` / `github.ParseWebHook`; Python
- `request.headers["X-GitHub-Event"]`.
-- Framework routes registered for webhook paths: `/webhook`, `/webhooks`,
- `/github/webhooks`, `/api/github/events`, `createNodeMiddleware`,
- `createProbot`, smee/ngrok tunnel config in development scripts.
-
-For each handled event record the GitHub event, the action(s) handled, the
-handler location, and — from facet 3 — which payload fields it reads.
-
-## 3. Payload fields read
-
-Inside each handler from facet 2, list every property path dereferenced from
-the payload object: `payload.pull_request.head.sha`, `payload.repository.name`,
-`payload.installation.id`, `payload.sender.login`, `payload.commits[].added`,
-`payload.check_suite.pull_requests`, `payload.before`, `payload.after`, and so
-on. Typed languages make this easy (struct fields accessed); in dynamic
-languages grep the handler body and any helper it passes the payload to.
-Include fields used only for logging or metrics — those are the ones teams
-forget until the port breaks a dashboard.
-
-## 4. REST and GraphQL calls
-
-- Octokit REST: `octokit.rest.<namespace>.<method>(`, `octokit.<namespace>.<method>(`,
- `octokit.request("<METHOD> /…")`, `octokit.paginate(`, `octokit.graphql(`,
- `@octokit/graphql`, `.graphql(`.
-- Other SDKs: Go `client.PullRequests.`, `client.Checks.`, `client.Repositories.`,
- `client.Issues.`, `client.Apps.`; Python `repo.get_pull(`, `gh.rest.`,
- `githubkit`; Java `GHRepository`, `GHPullRequest`; Ruby `client.pull_request(`.
-- Raw HTTP: `api.github.com`, `/repos/`, `Accept: application/vnd.github`,
- `X-GitHub-Api-Version`, `uploads.github.com`, `raw.githubusercontent.com`.
-- GraphQL documents: `.graphql` / `.gql` files, template strings starting with
- `query` or `mutation`, generated client code.
-
-Record each distinct call family once (method + path, or SDK method), with
-the parameters and filters the code passes (state, base, head, per_page,
-sort, since, check_name, app_id, filter…), the response fields it reads, and
-whether it is called in a loop or per webhook (this decides the fan-out
-tradeoff on the brief row). Note pagination style in use (`Link` header,
-`page`/`per_page`, `octokit.paginate`, GraphQL cursors) — it always changes.
-
-## 5. Authentication and token minting
-
-- App identity: `GITHUB_APP_ID`, `APP_ID`, `GITHUB_PRIVATE_KEY`, `PRIVATE_KEY`,
- `.pem` files, `createAppAuth`, `@octokit/auth-app`, `ghinstallation`
- (Go), `jwt.encode(... "RS256")`, `App.get_installation(`.
-- Installation tokens: `/app/installations/{id}/access_tokens`,
- `installationId`, `installation_id`, `app.auth(`, `getInstallationOctokit(`,
- `ghs_` prefixes in tests or fixtures, token caches keyed by installation.
-- User OAuth: `/login/oauth/authorize`, `/login/oauth/access_token`,
- `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `@octokit/auth-oauth-*`,
- `/user`, `/user/installations`, `/user/repos`, "setup URL" handlers reading
- `installation_id` and `setup_action` from the callback query string.
-- Git over HTTPS as the app: `x-access-token:` in clone URLs, credential
- helpers, `GIT_ASKPASS`.
-
-Record the flows present: app JWT algorithm, how the installation is
-identified after install (callback query, webhook, or DB), token lifetime
-handling, whether user OAuth exists and what it is used for (identity,
-repo discovery, acting on behalf of a user), and whether the app pushes or
-clones git.
-
-## 6. Webhook receiver and verification
-
-- Signature: `x-hub-signature-256`, `x-hub-signature`, `verify(`,
- `verifyAndReceive(`, `WEBHOOK_SECRET`, HMAC-SHA256 helpers,
- `github.ValidatePayload`.
-- Delivery handling: use of `x-github-delivery` for idempotency, queueing
- before or after responding, retry handling, redelivery tooling against
- `/app/hook/deliveries`.
-- Transport: the public URL and how it is configured (manifest
- `hook_attributes.url`, env var, tunnel in dev).
-
-Record the verification scheme, whether the raw body is available at
-verification time (frameworks that parse JSON first cannot verify), and how
-deliveries are deduplicated, if at all.
-
-## 7. Calls the framework makes on the app's behalf
-
-Some of the app's GitHub surface is not in its own source: it is what the
-framework or a helper library does for it, and the port has to do it too.
-When the code uses one of these, list the calls the dependency makes as rows
-in their own right, marked "from `<dependency>` (documented behavior)" so the
-team knows they were inferred, not read. `node_modules` is usually not
-checked in, so read the dependency's README or its source on its own
-repository, not the app.
-
-- **Probot**: the built-in receiver (`POST /`, `@octokit/webhooks` HMAC
- verification, `x-github-event` routing), per-installation token minting
- and caching, `context.repo()` / `context.issue()` helpers,
- `context.isBot` (`payload.sender.type`). Common companions:
- `probot-config` (reads `.github/<file>.yml`, falling back to the owner's
- `.github` repository), `probot-scheduler` (lists installations and their
- repositories with the app credential, then emits `schedule.repository` on
- an interval), `probot-metadata` (stores state in issue bodies).
-- **Octokit `App` / `@octokit/app`**: `app.webhooks.verifyAndReceive`,
- `app.eachInstallation` / `app.eachRepository` (installation + repository
- listing), automatic installation-token minting behind
- `app.getInstallationOctokit`.
-- **Go `ghinstallation`, Python `githubkit`/`gidgethub`, Ruby `octokit`
- app auth**: JWT minting and installation-token exchange.
-- **Frameworks' webhook middleware** in any language: which header names
- they read and whether they verify against the raw body.
-
-## When something is missing
-
-Say so in the inventory: "no manifest found (searched: …)", "no signature
-verification found in the receiver at …", "GraphQL client present but no
-query documents found". Each missing item becomes either a row with an
-`unknown` label or an up-front question in the brief. Do not fill gaps with
-assumptions about what an app of this kind usually does.
+Everything the brief needs about the app is in the repository. Search; do not
+ask. Record `file:line` for every fact and list every place you looked that
+turned up nothing. Note the language and libraries as an observation; they
+inform sizes and nothing else.
+
+Seven facets. For each, what to record:
+
+1. **Declared permissions and events.** The manifest or registration snapshot
+ if checked in (`app.yml`, manifest JSON, IaC that seeds the app; Probot
+ keeps `default_events` / `default_permissions` in `app.yml`). If absent,
+ say so and derive permissions from facet 4; the union of what the code
+ calls is what the port needs anyway.
+2. **Webhook events handled.** Each GitHub event and action pair the code
+ dispatches on (`app.on("pull_request.opened")`, a switch on
+ `x-github-event` + `payload.action`, SDK parsers), with the handler
+ location.
+3. **Payload fields read.** Every property path dereferenced from the payload
+ inside each handler and the helpers it passes the payload to. Include
+ fields used only for logging or metrics; those break dashboards after the
+ port.
+4. **REST and GraphQL calls.** Each distinct call family once (method + path
+ or SDK method) with the parameters and filters passed, the response fields
+ read, whether it runs per webhook or in a loop (decides the fan-out
+ tradeoff), and the pagination style in use (it always changes). GraphQL
+ documents count as calls; they are decomposed during mapping.
+5. **Authentication and token minting.** App JWT algorithm; how the
+ installation is identified after install (callback query, webhook, DB);
+ token lifetime handling; whether user OAuth exists and for what (identity,
+ repository discovery, acting for a user); whether the app clones or pushes
+ git as itself.
+6. **Webhook receiver and verification.** Signature scheme; whether the raw
+ body is available at verification time (frameworks that parse JSON first
+ cannot verify); how deliveries are deduplicated, if at all; where the
+ public URL is configured.
+7. **Calls the framework makes on the app's behalf.** Not in the app's
+ source, but the port has to do them. List them as rows marked "from
+ `<dependency>` (documented behavior)" and read the dependency's docs or
+ source, not the app. Common cases:
+ - **Probot**: built-in receiver and HMAC verification, per-installation
+ token minting and caching, `context.repo()` / `context.issue()`,
+ `context.isBot`; companions `probot-config` (reads `.github/<file>.yml`,
+ falling back to the owner's `.github` repository), `probot-scheduler`
+ (lists installations and repositories with the app credential, emits
+ `schedule.repository`), `probot-metadata` (state in issue bodies).
+ - **Octokit `App`**: `webhooks.verifyAndReceive`, `eachInstallation` /
+ `eachRepository`, automatic token minting behind
+ `getInstallationOctokit`.
+ - **`ghinstallation`, `githubkit`, `gidgethub`, `octokit.rb` app auth**:
+ JWT minting and installation-token exchange.
+
+When something is missing, say so in the inventory ("no manifest found
+(searched: …)", "no signature verification found in the receiver at …").
+Each missing item becomes an `unknown` row or an up-front question. Do not
+fill gaps with what an app of this kind usually does.
diff --git a/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md b/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md
index 1e0d3290..fd732713 100644
--- a/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md
+++ b/origin-apps/skills/port-github-app-to-origin/references/gap-bar.md
@@ -1,143 +1,74 @@
# The gap bar and the escalation card
-Most differences between GitHub and Origin are not gaps. A brief that files
-every difference trains the team to ignore it and buries the two or three
-things Cursor actually needs to hear. Use this bar, and when in doubt, write
-the row as `workaround` with an honest tradeoff and an open question rather
-than as a gap card.
-
-## Definitions
+Most differences are not gaps. A brief that files every difference buries
+the two or three things Cursor needs to hear. When in doubt, write the row as
+`workaround` with an honest tradeoff and an open question, not as a card.
- A **difference** is any row whose parity label is not `same`.
-- A **workaround** is a way to get the same outcome with the surface that
- exists today: a follow-up read, a re-keyed identifier, a path change, a
- client-side filter, a marker the app controls.
-- A **gap** is a difference with **no workaround**, or a workaround whose
- tradeoff is **nontrivial**. Only gaps become escalation cards.
+- A **workaround** reaches the same outcome with today's surface: a follow-up
+ read, a re-keyed identifier, a path change, a client-side filter, a marker
+ the app controls.
+- A **gap** is a difference with no workaround, or a workaround whose tradeoff
+ is nontrivial. Only gaps become cards.
-## What makes a tradeoff nontrivial
+## Nontrivial tradeoff
-A workaround's tradeoff is nontrivial when at least one of these holds. Quote
-the one that applies on the card.
+At least one must hold; quote it on the card.
| Tradeoff | Test |
| --- | --- |
-| **Fan-out at scale** | The workaround multiplies calls per event by a factor that grows with repository or activity size (N commits × M files per push; a full list scan to find one row), and the app's event volume makes that budget-relevant. One extra bounded read per event is trivial. |
-| **Correctness risk** | The workaround can produce a wrong answer, not just a slower one: identifying "my own row" by a heuristic; inferring a pull request from a SHA that several versions share; assembling a URL whose format is not contractual. |
-| **Security posture** | The workaround needs a broader scope, a longer-lived token, or a user credential where an installation token should do. |
-| **Product behavior visible to the team's customers** | The workaround changes what their users see or can do (no team link in a comment, no user-scoped repository picker), not just how the code is organized. |
-| **Load-bearing for the port** | The capability sits on the hello-world path or on the team's stated core flow, so its tradeoff decides whether the port ships. |
-
-If none apply, the row is `workaround`, sized honestly, with the tradeoff in
-the tradeoff column and no card.
-
-## What is never a gap
-
-- Anything on the `origin-isms.md` list. Those rows are `by-design-absent`
- or `reshaped`, and the brief points at the idiom. Filing them wastes the
- team's and Cursor's time; the decisions are recorded.
-- A field or filter the code does not actually use. Map what the code reads,
- not what the SDK exposes.
-- A difference that exists only because the code uses a GitHub convenience
- (`Link` pagination, numeric IDs, `html_url`) in a place where the Origin
- convention is a mechanical substitution.
+| **Fan-out at scale** | Calls per event multiply by a factor that grows with repository or activity size (N commits × M files; a full list scan to find one row) and the app's volume makes that budget-relevant. One bounded extra read per event is trivial. |
+| **Correctness risk** | The workaround can be wrong, not just slower: heuristic "my own row" matching, inferring a PR from a SHA several versions share, assembling a URL whose format is not contractual. |
+| **Security posture** | Needs a broader scope, a longer-lived token, or a user credential where an installation token should do. |
+| **Customer-visible behavior** | Changes what the team's users see or can do, not how the code is organized. |
+| **Load-bearing** | Sits on the hello-world path or the team's stated core flow. |
+
+## Never a gap
+
+- Anything in `origin-isms.md`.
+- A field or filter the code does not actually use.
+- A GitHub convenience (`Link` pagination, numeric IDs, `html_url`) where the
+ Origin convention is a mechanical substitution.
- Something the changelog says shipped or the spec already carries. Re-check
- the live spec before writing any card; the rows most likely to be stale are
- the ones you are about to escalate.
-- A concept the Origin docs never mention at all (Marketplace billing, merge
- queues, Actions, Projects). That is `unknown` plus a question
- (`spec-mapping.md` § Out-of-domain surfaces); a card asks Origin to build
- something the team may not want.
-- A GitHub search query. Origin has no search endpoint by design for the
- surfaces it exposes; a list operation with `sortBy`/`state`/filters plus a
- client-side predicate is the idiom. Count the fan-out honestly (a sorted
- list read that stops at a cutoff is proportional to the matches, not the
- collection), and only if that count fails the bar does it become a card
- about a *filter*, never about search.
+ the live spec before writing any card.
+- A concept the Origin docs never mention (Marketplace billing, merge queues,
+ Actions, Projects): `unknown` plus a question.
+- A GitHub Search query. The idiom is a list operation with its filters plus
+ a client-side predicate; a sorted list read that stops at a cutoff is
+ proportional to the matches, not the collection. Only if that count fails
+ the bar does it become a card about a *filter*, never about search.
## One pattern that does clear the bar
-A state change the app reacts to that has **no event**, when the app's
-purpose is to react to exactly that change and the state is otherwise
-invisible until an unrelated event arrives. Reading the state off the next
-event's snapshot is the workaround; it fails on correctness and
-customer-visible behavior when the app is a gate (a check, a block, a
-notification) and the lag is the whole failure mode. Write the card about the
-event; do not write it when the app merely logs or tidies up on that change.
+A state change the app reacts to that has **no event**, when reacting to
+exactly that change is the app's purpose and the state is invisible until an
+unrelated event arrives. Reading it off the next snapshot fails on
+correctness and customer-visible behavior when the app is a gate (a check, a
+block, a notification). Write the card about the event; not when the app
+merely logs or tidies up on that change.
-## The escalation card
+## The card
-One card per gap, in the brief's "Gaps worth raising" section, in this shape.
-It is written so Cursor can act on it without a call.
+One per gap, in the brief's "Gaps worth raising" section, written so Cursor
+can act without a call:
```markdown
-### Gap: <one line naming the capability, in Origin terms>
+### Gap: <capability, in Origin terms>
-- **GitHub surface the app uses:** `<METHOD /path>` or `<event.action>` or `<permission>`, at `<file:line>`.
-- **What the app needs from it:** <the data or effect, one sentence>.
+- **GitHub surface the app uses:** `<METHOD /path>` / `<event.action>` / `<permission>`, at `<file:line>`.
+- **What the app needs from it:** <data or effect, one sentence>.
- **Why:** <what the app does with it, one sentence>.
-- **Closest Origin surface today:** `<operationId>` / `<event slug>` / none, and what it lacks.
-- **Workaround considered:** <the workaround, or "none found">.
-- **Tradeoff that fails the bar:** <one of the five, quoted, with the number or risk>.
-- **Shape that would close it:** <a field, a filter, an event, an operation — described as a capability, not a design: "list pull requests whose head is this SHA", not a proto sketch>.
-- **Blocking?** yes / no, and for which flow.
+- **Closest Origin surface today:** `<operationId>` / `<slug>` / none, and what it lacks.
+- **Workaround considered:** <it, or "none found">.
+- **Tradeoff that fails the bar:** <one of the five, with the number or risk>.
+- **Shape that would close it:** <a capability, not a design: "list pull requests whose head is this SHA", not a route or field name>.
+- **Blocking?** yes / no, for which flow.
- **Spec version checked:** `<info.version>` on `<date>`.
```
-Keep the card to those lines. Do not propose scope names, field names, or
-route templates; Cursor owns the shape and applies design conventions the
-card cannot see. Do not batch unrelated capabilities into one card.
-
-## Where the card goes
-
-The brief is written for the team. The cards are theirs to send, in their own
-words if they prefer. Two routes exist today:
-
-- **A shared Slack channel with Cursor**, if the team has one from working
- with Cursor on the integration. Post the card there; it reaches the people
- who own the API.
-- **`[email protected]`**, the feedback address the Origin documentation names.
- Put "Origin API" and the app name in the subject and paste the card.
-
-Either way, quote the spec version the card was checked against and any
-`X-Request-ID` values from failed calls (every Origin error response carries
-one; the API reference asks for it when you contact Cursor). A card that
-states the capability and the tradeoff cleanly is the fastest path to an
-answer, including a "this is by design, here is the idiom" answer, which is a
-fine outcome and belongs back in the brief as a `by-design-absent` row.
-
-Do not send cards yourself. Write them, put them in the brief, and let the
-team decide what goes out.
-
-## Calibration examples
-
-Illustrations of where the bar falls. Each is written as a pattern, because
-the specific surface may have moved since this file was written; confirm
-against the live spec before reusing the verdict.
-
-- **A list operation lacks a filter the code relies on to find its own row**
- (for example, finding the app's own check run for a commit by name or key).
- Workaround: page the whole list and match client-side. Trivial when the
- list is small and bounded; **gap** when the list grows with activity and the
- lookup runs per event (fan-out) or when the match is heuristic
- (correctness). State which.
-- **A web URL the app posts in comments is not in the payload or resource.**
- Workaround: assemble it from slug and number. Correctness risk only if the
- URL format is not contractual — check the docs; if the format is documented,
- it is `derivable`, not a gap. If it is not documented, write a card that
- asks for the URL field rather than guessing.
-- **A membership roster the app uses to attribute approvals to a team** has
- no read on Origin and no workaround (identity is a TypeID; there is no
- directory). Correctness plus product behavior: **gap**, with a card that
- names the capability ("who is in group X, for a repository this
- installation can read") and leaves the oracle analysis to Cursor.
-- **Push payload lacks the changed-file list.** Workaround: compare or list
- commit files on receipt. One bounded read per push is `workaround`; if the
- app fans out per commit and per file on high-volume repositories, quote the
- multiplier and let the team decide — and note that the lean payload is the
- documented design (`origin-isms.md` § Webhooks), so the card, if any, is
- about a compare endpoint's shape, not about fattening the payload.
-- **The app uses GitHub Issues.** Never a card. `by-design-absent`; the
- up-front question is what the PR-scoped behavior should be.
-- **The app uses commit statuses.** Never a card. `reshaped` onto check runs
- with a stable key.
+Do not propose scope, field, or route names; Cursor owns the shape. Do not
+batch unrelated capabilities. Do not send cards yourself; the team decides
+what goes out (their shared Slack channel with Cursor, or `[email protected]`
+with "Origin API" and the app name in the subject), quoting the spec version
+and any `X-Request-ID` from failed calls. "This is by design, here is the
+idiom" is a fine answer and goes back into the brief as `by-design-absent`.
diff --git a/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md b/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md
index 112c988c..db4f021a 100644
--- a/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md
+++ b/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md
@@ -1,170 +1,37 @@
-# Origin-isms: where Origin departs from GitHub on purpose
-
-Origin uses GitHub's nouns and general shape and deliberately not its wire
-format. When a GitHub feature has no counterpart in the spec, check this list
-before calling it a gap: a row here is `by-design-absent` (or `reshaped`) in
-the brief, and the brief's job is to point the team at the Origin idiom. Each
-entry gives the departure, the idiom, and the reason in one line, so you can
-explain it to a team that has only ever seen GitHub. Confirm the current
-wording in `llms-full.txt`; this file explains intent, the docs state the
-contract. The `origin-api` skill carries the same conventions as practices
-for building; this file carries them as parity decisions for a port.
-
-## Which repositories an app can act on
-
-- **Apps act on Origin-native repositories (and stable outbound mirrors).** A
- repository mirrored *from* GitHub is read-only to an installation — metadata
- and contents reads, clone/fetch/pull — and rejects pull requests, reviews,
- comments, checks, rulesets, and every write with `403`. Why: a write on a
- mirror would have to act on GitHub as Cursor's GitHub App, with risk Origin
- cannot bound; and GitHub already sends its own webhooks for those repos.
-- **`repository.pushed` is not delivered for GitHub-mirrored repos.** Why:
- GitHub owns those pushes and already notifies the app; Origin would
- duplicate them. Consequence for the port: a ping works on a mirror and then
- nothing else does. The first up-front question in every brief is
- native-or-mirror for exactly this reason.
-- **`mirror.status` does not tell you whether writes are allowed.** Treat the
- `403` as authoritative.
-
-## Identity and authentication
-
-- **No OAuth-app token exchange as the install path.** Install is a consent
- redirect that returns a signed **installation receipt** JWT (`sub` = the
- installation ID, `state` echoed) instead of `installation_id` and
- `setup_action` query parameters. Why: the receipt proves the approval came
- from Origin; a bare query string cannot. The receipt is never a Bearer
- token.
-- **App JWT is EdDSA over Ed25519, not RS256.** Register only the public key;
- up to ten active keys. `kid` and `iss` are the app ID; `aud` is fixed.
-- **Installation tokens are `oit_…`, short-lived, minted just in time**, and
- can be attenuated to fewer scopes or to specific `repositoryIds` (IDs, not
- slugs — resolve the ID first). Git over HTTPS uses Basic auth with username
- `x-access-token` and the token as password; Bearer belongs to REST only.
-- **User-scoped calls (`/user`, `/user/installations`, install-by-user) have
- no app-side counterpart.** Repository discovery is through the
- installation (`/installation/repos`), and app creation, adding
- repositories to an installation, and mirror transitions are admin actions
- carried by a Cursor user credential, not app calls. Read the live
- Authentication section for the current user-credential story before
- labeling anything here; do not assume a GitHub-OAuth analog exists.
-- **Scopes, not permissions.** `repository:<noun>[:<sub>]:<read|write>`;
- `write` implies `read`; `repository:metadata:read` is automatic; the
- installation can only narrow what the admin approved. Look each called
- operation's requirement up in `x-origin-scopes` rather than translating the
- manifest noun-for-noun.
-
-## Wire conventions
-
-- **Opaque TypeIDs, never integers**: `app_…`, `i_…`, `ns_…`, `repo_…`,
- `user_…`, `cmt_…`, `evt_…`. Why: sequential IDs are enumerable; opaque IDs
- are the stable handle to cache. A repository is addressable by ID as
- `/repos/_/{repoId}`, which survives renames; there is no
- `/repositories/{id}` route and no numeric ID anywhere.
-- **camelCase JSON; 64-bit integers (PR numbers, version numbers) are JSON
- strings; RFC 3339 timestamps.**
-- **Defaults are present, not omitted.** `false`, `0`, `""`, `[]` appear in
- bodies; only fields documented as optional are absent when unset. Do not
- treat a missing key as the default and do not treat a present `false` as
- "unset".
-- **Pagination is `pageSize` / `pageToken` / `nextPageToken`.** Tokens are
- opaque, bound to the resource and filters, and there is no `Link` header,
- no `page`, no total count. Why: keyset cursors do not skip or duplicate
- under concurrent writes; offsets do. Restart when filters change.
-- **Errors are one envelope**: `google.rpc.Status` `{code, message, details}`
- with typed `details` (`BadRequest` field violations, `RequestInfo` request
- id on every error; further typed detail types such as machine-readable
- `ErrorInfo` reasons may be added, so read the live Errors section and
- tolerate unknown detail types). `X-Request-ID` is on every error. **`404`
- never distinguishes not-found from no-access.** Why: anti-enumeration.
- Branch on status and `code`; quote the request id when escalating.
-- **No GraphQL.** REST only; decompose queries.
-- **Rate limits are a per-principal point budget**, `X-RateLimit-*` plus
- `Retry-After` on `429`; Git HTTPS meters separately (`X-RateLimit-Resource:
- git`). Cursor can raise per-app budgets on request.
-- **Public terminology is "pull request"** throughout; do not expect
- "change" or "changeset" on the wire.
-
-## Resources GitHub has that Origin does not reproduce
-
-- **No commit statuses.** Check runs are the only status primitive:
- `PostCheckRun` upserts on a caller-stable `key` (with `externalId` /
- `externalUpdatedAt` for retries and ordering), and rulesets bind on check
- keys. Why: one status model, idempotent by construction. A `statuses`
- permission or `POST /statuses/{sha}` maps to checks, not to a gap.
-- **No Issues.** Origin's conversation surfaces are pull requests, pull
- request comments and threads, reviews, and labels on pull requests. An
- `issues`-only GitHub App has no Origin equivalent for that part; say so
- and ask what the team wants the PR-scoped behavior to be. GitHub's
- `/issues/{n}/comments` used *on a PR* is just a path change.
-- **No repository-level webhook CRUD** (`/repos/…/hooks`). Subscriptions are
- an app-settings concern; there are no per-repo hook objects.
-- **No app-manifest conversion endpoint and no OAuth-app token mints.**
- Legacy GitHub mechanisms Origin does not reproduce. App creation is a
- form (which accepts prefill query parameters) or the user-credential
- `CreateApp` operation.
-- **No REST git-object writes beyond the documented ones.** Commits are
- pushed over Git HTTPS with an installation token (or created through the
- documented commit-from-files and ref operations); do not expect a GitHub
- Git Data API for arbitrary tree/blob writes.
-- **No standalone threads API.** Comments are the only content write
- surface; a thread materializes from its first diff-anchored comment and is
- addressable for resolve/reopen. Why: one write surface, no dual bookkeeping.
-- **No user/email directory.** Actors carry a TypeID (and a handle where the
- contract exposes it); there is no lookup from email to user and no team
- or member pages to link to. Why: an email or membership oracle.
-
-## Webhooks
-
-- **One message serves REST and webhooks.** A payload snapshots the one
- object that changed exactly as its `Get…` returns it, plus compact
- references (`repository`, `pullRequest`) for its containers. Why: consumers
- reuse their REST decoders and never see a partially hydrated shape.
-- **Webhooks notify; the API answers.** Payloads are lean by design: no
- changed-file lists on pushes, no before-SHA on PR events, no web URLs, no
- inlined user profiles. Follow-up reads (`GetCommit`, `CompareCommits`,
- `ListComparisonFiles`, `GetRepo`, `GetPullRequest`) are the intended
- pattern. Why: no emit-time joins, no size blowups, no staleness races.
- Map fields the code reads to specific follow-up calls and count the
- fan-out honestly; that count is the tradeoff, not a defect.
-- **Slugs are `<resource>[.<sub>].<past-tense-action>`** and the action lives
- in the slug (`pull_request.created`, `pull_request.review.submitted`,
- `repository.check_run.completed`), never in a payload `action` field, and
- there is no `previous_attributes` delta. Why: granular event types over
- payload flags; one shape per event. GitHub's `pull_request` +
- `action: synchronize` becomes `pull_request.head_ref.pushed`, and so on —
- confirm each in `x-origin-webhook-events`.
-- **Envelope**: `{deliveryId, appId, installationId, event: {id, type,
- eventTime, payload}}`. `deliveryId` is stable across retries and is the
- idempotency key; `event.id` identifies the domain event. Routing headers
- are `webhook-id`, `webhook-timestamp`, `webhook-signature`,
- `webhook-event-type`, `webhook-app-id`, `webhook-installation-id` (not
- `x-github-*`); after verification the body is authoritative.
-- **Signature is Ed25519 over a SHA-256 digest, scheme `v1ed`**, keys from
- Origin's JWKS (rotated weekly, cache per `Cache-Control`), not an HMAC
- shared secret. It tracks the Standard Webhooks spec except that it signs a
- digest instead of the raw string, so off-the-shelf Standard Webhooks
- verifiers do not validate it as-is. Verify the raw body before parsing;
- reject timestamps more than five minutes off.
-- **Installation lifecycle events are always delivered; every other event
- must be selected in app settings.** Creating the app subscribes to nothing
- else. Why: opt-in exposure. This is the second most common first-week
- stall after mirror-vs-native.
-- **Delivery is at-least-once with retries and a seven-day recovery window**
- (`ListWebhookDeliveries`, `BatchRedeliverWebhookDeliveries`); persistent
- failure pauses the app's delivery.
-
-## Checks, reviews, comments
-
-- **Check runs upsert on `key`**, live under a check suite keyed the same
- way, and can be flagged re-requestable; a re-request arrives as an event
- to the owning app. Annotations are appended, not replaced.
-- **Reviews anchor to a pull request *version*, not a commit SHA.** Why: a
- SHA can match several versions after a rebase or retarget. Code that keys
- approvals by `commit_id` re-keys by version number.
-- **Requested reviewers are addressed by identifier** (users, groups), and
- Origin is deliberately careful about existence oracles on that surface. Do
- not expect `created_via` or team pages on the read side.
-- **Find your own writes by a key you control.** Check runs are found by
- their `key`; for reviews and comments, carry a marker the app owns (a body
- prefix, a stable key) rather than relying on actor identity alone, and
- confirm in the spec which author filters the list operations offer.
+# Origin-isms: GitHub surfaces Origin departs from on purpose
+
+Check here before labeling anything `gap`. A row below is `by-design-absent`
+or `reshaped`; the brief points at the idiom and never files a card. The
+reasoning behind each lives in the `origin-api` skill; this table carries only
+what the classifier needs. Confirm current wording in `llms-full.txt`.
+
+| GitHub surface the app uses | Label | Origin idiom |
+| --- | --- | --- |
+| Acting on a repository mirrored *from* GitHub (writes, `push` events) | `by-design-absent` | Install on Origin-native repositories or stable outbound mirrors. Mirrors are read-only to apps and deliver no `repository.pushed`. First question of every brief. |
+| Install callback with `installation_id` + `setup_action` query params | `reshaped` | Signed installation receipt JWT; `sub` is the installation ID. Not a Bearer. |
+| RS256 app JWT | `reshaped` | EdDSA over Ed25519; register the public key. |
+| `ghs_` installation tokens, long cache | `reshaped` | `oit_…`, short-lived, minted just in time, attenuable to scopes and `repositoryIds`. |
+| User OAuth: `/user`, `/user/installations`, `/user/repos`, install-by-user picker | `by-design-absent` | Repository discovery is `/installation/repos`. App creation and installation-repository changes are admin actions with a user credential, not app calls. Ask what the flow should do. |
+| Permissions `<noun>: read\|write` | `reshaped` | Scopes `repository:<noun>[:<sub>]:<read\|write>` taken from `x-origin-scopes` of the called operations. |
+| Numeric IDs, `/repositories/{id}` | `reshaped` | TypeIDs; `/repos/_/{repoId}`. |
+| `Link` / `page` / `per_page` pagination, total counts | `reshaped` | `pageSize` / `pageToken` / `nextPageToken`; opaque; no total. |
+| GraphQL | `by-design-absent` | REST; decompose and count the fan-out. |
+| Commit statuses (`statuses` permission, `POST /statuses/{sha}`) | `reshaped` | Check runs upserting on a caller-stable `key`; rulesets bind on the key. |
+| Issues (`issues` permission, `issues.*` events, `/issues/{n}` not on a PR) | `by-design-absent` | PR comments, threads, reviews, labels on pull requests. Ask what the PR-scoped behavior should be. |
+| `/issues/{n}/comments`, `/issues/{n}/labels` used on a pull request | `reshaped` | Same calls under `/pulls/{n}/…`. |
+| Repository webhook CRUD (`/repos/…/hooks`) | `by-design-absent` | Subscriptions are app settings. |
+| App-manifest conversion, OAuth-app token mints | `by-design-absent` | App creation form (accepts prefill params) or user-credential `CreateApp`. |
+| Git Data API tree/blob writes | `by-design-absent` | Push over Git HTTPS with an installation token, or the documented commit-from-files and ref operations. |
+| Standalone review-thread objects | `reshaped` | A thread materializes from its first diff-anchored comment and is addressable for resolve/reopen. |
+| User, email, team, and member lookups | `by-design-absent` | Actors are TypeIDs (plus a handle where exposed). No directory. |
+| Single `pull_request` event with `action` field, `previous_attributes` | `reshaped` | One slug per action (`pull_request.head_ref.pushed`); no `action` field, no delta. Confirm each slug in `x-origin-webhook-events`. |
+| `x-github-*` headers, HMAC `x-hub-signature-256` | `reshaped` | `webhook-*` headers; `v1ed` Ed25519 over a SHA-256 digest, JWKS keys. |
+| Payload inlines: changed files on push, before-SHA, `html_url`, `sender` profile | `reshaped` | Follow-up `Get…` / `CompareCommits` / `ListComparisonFiles` with identifiers the payload carries. Name the call per field; count the fan-out. |
+| Default delivery of all events after app creation | `reshaped` | Only installation lifecycle is default; select the rest. |
+| Reviews keyed by `commit_id` | `reshaped` | Reviews anchor to a pull request version. |
+| Finding own check runs / comments by actor | `reshaped` | Check runs by `key`; comments and reviews by a marker the app controls. |
+| Requested-reviewer team pages, `created_via` | `by-design-absent` | Reviewers addressed by identifier only. |
+
+Not on this list, and not mentioned anywhere in the Origin docs (Marketplace
+billing, merge queues, Actions, Pages, Projects): `unknown` with a question,
+never `by-design-absent`.
diff --git a/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md b/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md
index d0dcf83f..0a788ba5 100644
--- a/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md
+++ b/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md
@@ -1,185 +1,94 @@
# Reading the Origin spec and matching GitHub surface to it
-The mapping in the brief is derived from the live `openapi.yaml`, not from a
-table in this skill. This file explains what the spec carries and how to match
-against it. Build the index once at the start of the run; every later step
-looks things up in it.
+Every mapping in the brief is derived from the fetched `openapi.yaml`, not
+from a table here. Build the index once; every later step looks things up in
+it.
-## What the spec carries
-
-`https://cursor.com/docs/api/origin/openapi.yaml` is OpenAPI 3.1 generated from
-Origin's protobuf contract. Beyond the standard fields, four extensions matter
-for porting:
+## Extensions the spec carries
| Extension | Where | Meaning |
| --- | --- | --- |
-| `x-origin-scopes` | every operation | `scopes`: the scope strings the operation requires. `tokenTypes`: which credentials it accepts (`app` JWT, `installation` token, `user`). `ambient: true`: the scopes come with the credential itself, so an app has nothing to request for it. |
-| `x-origin-webhook-events` | payload schemas under `components.schemas` | The event slugs that deliver this payload shape. A schema carrying it is a webhook payload family; the slugs are the only authoritative list of subscribable events. |
-| `x-origin-webhook-resource` | payload schemas, when present | Points at the REST component the payload embeds (the object a `Get…` operation returns). When absent, infer the embedded resource from the payload's `$ref` properties. Do not assume every payload has a REST twin; pushes, deletions, and reviewer requests are event-native. |
-| `x-cursor-visibility: PREVIEW` | some operations | Published but badged preview. Carry the badge into the brief; a preview operation is usable, but tell the team the shape may still move. |
-
-Everything else you need is standard: `paths` with `operationId`,
-`description`, `parameters`, request and response schemas, and `example`
-blocks; `components.schemas` with field descriptions that are the contract
-text itself.
-
-`llms-full.txt` adds what the spec cannot: the installation flow, the receipt
-and app JWT, installation tokens and Git HTTPS, the scopes table, the mirrored
-repositories rule, webhook headers, signature verification, the delivery
-envelope, retries and recovery, pagination and error conventions, and the
-current limitations list. Read those sections before mapping; several rows in
-the brief (auth, receiver, pagination) map onto them rather than onto an
-operation.
+| `x-origin-scopes` | every operation | `scopes` required; `tokenTypes` accepted (`app`, `installation`, `user`); `ambient: true` means nothing to request. |
+| `x-origin-webhook-events` | payload schemas | The slugs that deliver this payload shape. A schema carrying it is a webhook family; these slugs are the only authoritative event list. |
+| `x-origin-webhook-resource` | some payload schemas | The REST component the payload embeds. When absent, infer from `$ref`s; pushes, deletions, and reviewer requests are event-native with no REST twin. |
+| `x-cursor-visibility: PREVIEW` | some operations | Usable, shape may move. Carry the badge into the brief as a `preview` suffix. |
## Build the index
-Parse the YAML and produce four lookups. Keep them in a scratch file; the
-brief cites from them.
-
-1. **Operations**: for each path and method, record `operationId`, method,
- path template, first sentence of `description`, `x-origin-scopes`
- (`scopes`, `tokenTypes`, `ambient`), `x-cursor-visibility` if any, path and
- query parameter names, request body top-level fields, and the response
- component name.
-2. **Webhook events**: for each schema with `x-origin-webhook-events`, record
- each slug → schema name → the properties and their `$ref`s (or the
- `x-origin-webhook-resource` target). Also read the Events table in
- `llms-full.txt` § Webhooks reference for each slug's trigger sentence and
- for which events are app-lifecycle (always delivered) versus repository
- subscriptions (must be selected in app settings).
-3. **Scopes**: the union of every `scopes` value seen in `x-origin-scopes`,
- annotated with which operations require it, plus the Scopes table in
- `llms-full.txt` for the human description and the `write` ⊃ `read` rule.
- Separate the scopes an installation can request from those that are
- ambient or user-credential-only; the latter tell you which GitHub flows
- have no app-side equivalent by construction (for example, app creation and
- installation-repository changes are admin actions on Origin, not app
- calls).
-4. **Resources**: component schemas returned by `Get…`/`List…` operations,
- with their field names. Used to answer "which fields does the Origin object
- carry" when mapping payload fields and response fields the code reads.
-
-## Matching rules
-
-Match in this order and stop at the first rule that yields a confirmed
-counterpart. "Confirmed" means you read the Origin operation's description and
-parameters and they answer the same question the GitHub call answers. A name
-match is a candidate, never a result.
-
-### REST calls
-
-1. **Normalize the GitHub path** and look for the same shape under
- `/v1/origin`: `/repos/{owner}/{repo}` → `/v1/origin/repos/{ownerSlug}/{repoName}`;
- `{pull_number}` → `{pullNumber}`; `{ref}`/`{sha}` stay; GitHub's
- `check-runs`, `check-suites`, `compare/{basehead}`, `contents`, `git/…`,
- `pulls/{n}/{files,commits,reviews,comments,requested_reviewers,merge}`,
- `labels`, `branches`, `commits` all have direct or near-direct shapes.
- Custom-verb operations on Origin use a `:verb` suffix
- (`…/contents:batchGet`, `…/check-runs:batchUpsert`, `…:grep`).
-2. **Re-home GitHub's issue-flavored PR calls.** GitHub puts PR conversation
- comments under `/issues/{n}/comments` and labels under `/issues/{n}/labels`;
- on Origin those live under `/pulls/{n}/…`. This is a path change, not a
- gap, when the code only ever uses them on pull requests. When the code
- uses them on real issues, see `origin-isms.md` (issues are not an Origin
- surface).
-3. **Re-home app and installation calls.** GitHub's `/app`,
- `/app/installations`, `/app/installations/{id}/access_tokens`,
- `/installation/repositories` have Origin counterparts under `/v1/origin/app…`
- and `/v1/origin/installation/repos`; check `tokenTypes` to confirm which
- credential each takes. GitHub's `/user`, `/user/installations`,
- `/orgs/{org}/…`, `/search/…`, and `/repositories/{id}` have no path
- counterpart; consult `origin-isms.md` and the Authentication section
- before deciding whether they are absent by design, covered by a different
- idiom, or a gap.
-4. **Compare parameters, not just paths.** A matching path with a missing
- filter the code depends on (for example a list the code narrows by a field
- Origin does not accept) is `workaround` or `gap`, not `same`. Read the
- `parameters` block.
-5. **Compare response fields the code reads.** Trace which response
- properties the handlers dereference and check them against the Origin
- component. Missing fields are common where GitHub inlines convenience data
- (web URLs, nested user profiles, aggregate counts). Each missing field gets
- its own line under the row: follow-up call, derivable, or absent.
-
-### GraphQL
-
-There is no GraphQL endpoint. Decompose each query or mutation into the REST
-reads and writes it stands for, then map those individually. Note the fan-out
-(one query → N calls) as the tradeoff on the row. If the query exists to
-avoid REST pagination or to fetch a cross-repository view, say so; that is
-the tradeoff the team weighs.
-
-### Permissions → scopes
-
-GitHub permissions are `<noun>: read|write`; Origin scopes are
-`repository:<noun>[:<subnoun>]:<read|write>` with `write` implying `read`
-and `repository:metadata:read` granted automatically. Match the noun, then
-verify by finding the operations the code actually calls in the Operations
-lookup and reading *their* `x-origin-scopes` — the scope set in the brief is
-the union of what the called operations require, not a translation of the
-manifest. GitHub permissions with no Origin noun (`statuses`, `issues`,
-`members`, `organization_*`, `pages`, `actions`, `workflows`, `secrets`,
-`deployments`, `environments`) go through `origin-isms.md` before they can be
-called gaps.
-
-### Webhook events → slugs
-
-Origin slugs are `<resource>[.<sub-resource>].<past-tense-action>` with the
-action in the slug, never in the payload: GitHub's single `pull_request` event
-with an `action` field is several Origin events. Translate each
-`event.action` pair the code handles into a candidate slug, then confirm the
-slug appears in the Webhook events lookup. Candidates that do not appear are
-not events on Origin; check whether the state change is observable another
-way (an event on a related resource, or a REST read on receipt of one) before
-classifying. Installation lifecycle events are always delivered to the app;
-everything else must be subscribed explicitly, which the brief's hello-world
-path calls out.
-
-### Payload fields → schema properties
-
-For each field path a handler reads off a GitHub payload
-(`payload.pull_request.head.sha`, `payload.repository.full_name`,
-`payload.sender.login`, `payload.commits[].added`), find the Origin payload
-schema for the mapped slug and walk its properties. Record one of:
-
-- **present** at `<origin.path>`;
-- **follow-up read**: not in the payload, available from `<operationId>` using
- identifiers the payload does carry;
-- **derivable**: assembled from present fields (say how, and note whether the
- format is contractual);
-- **absent**: no payload field and no read that yields it (this row goes to
- the gap bar).
-
-The payload carries references (`repository`, `pullRequest`) around the
-snapshot of the one object that changed. Expect a lean shape and plan the
-follow-up reads; that is the Origin design, not a defect
-(`origin-isms.md` § Webhooks). Compare the webhook snapshot's schema with
-the REST resource it mirrors: a field on the REST component that the webhook
-twin lacks (for example a list the resource carries but the snapshot omits)
-is a follow-up read via the matching `Get…`, and the code that reads it off
-the GitHub payload today needs that read on every event.
-
-### Out-of-domain surfaces and spec-silent behavior
-
-Some of what a GitHub App touches is not source control at all: Marketplace
-billing and plan lookups, merge queues, Actions, Pages, Projects,
-Milestones, Discussions, `github.com` HTML probes. When neither the spec nor
-`llms-full.txt` mentions the concept, the row is `unknown` with an up-front
-question about what the team wants on Origin, never `gap` (Origin has not
-declined it; the team may not need it) and never `by-design-absent` (only
-`origin-isms.md` rows earn that).
-
-When the code depends on a behavior the docs do not state (does an event
-fire for a pull request opened as a draft? does `updatedAt` move on a
-comment? what does a remove return when nothing was there?), do not resolve
-it from GitHub's behavior. Record the dependency in the row's Open question
-column and add a step to the hello-world path that observes it on a native
-repository.
-
-## Provenance in the brief
-
-Write the spec's `info.version`, the fetch timestamp, and the four URLs into
-the brief's provenance block. State plainly that the brief reflects the
-surface on that date and that the team should re-read the changelog before
-acting on any row marked `workaround` or `gap`, because those are the rows
-most likely to have moved.
+1. **Operations**: `operationId`, method, path, `x-origin-scopes`,
+ visibility, parameter names, request top-level fields, response component.
+2. **Webhook events**: slug → schema → properties and `$ref`s (or the
+ `x-origin-webhook-resource` target). From `llms-full.txt` § Webhooks,
+ which slugs are app-lifecycle (always delivered) versus repository events
+ (must be selected).
+3. **Scopes**: union of every `scopes` value, annotated with the operations
+ that need it; separate installation-requestable scopes from ambient and
+ user-only ones (the latter tell you which GitHub flows have no app-side
+ equivalent by construction).
+4. **Resources**: component schemas returned by `Get…`/`List…`, with field
+ names, for "does the Origin object carry this field".
+
+`scripts/index-origin-spec.py openapi.yaml [ops|events|scopes|schema <Name>]`
+prints all four.
+
+## Matching
+
+Match in this order; stop at the first rule that yields a *confirmed*
+counterpart. Confirmed means you read the Origin operation's description and
+parameters and it answers the same question. A name match is a candidate,
+never a result.
+
+**REST calls**
+
+1. Normalize the GitHub path to the same shape under `/v1/origin`
+ (`{owner}/{repo}` → `{ownerSlug}/{repoName}`, `{pull_number}` →
+ `{pullNumber}`; custom verbs are `:verb` suffixes such as
+ `…/contents:batchGet`).
+2. Re-home GitHub's issue-flavored PR calls: `/issues/{n}/comments` and
+ `/issues/{n}/labels` used *on a pull request* live under `/pulls/{n}/…`.
+ Path change, not a gap. Used on real issues: `origin-isms.md`.
+3. Re-home `/app`, `/app/installations`, access-token minting, and
+ `/installation/repositories` under `/v1/origin/app…` and
+ `/v1/origin/installation/repos`; confirm `tokenTypes`. `/user`,
+ `/user/installations`, `/orgs/…`, `/search/…`, `/repositories/{id}` have
+ no path counterpart: consult `origin-isms.md` before labeling.
+4. Compare parameters, not just paths. A matching path missing a filter the
+ code depends on is `workaround` or `gap`, not `same`.
+5. Compare response fields the code reads. Each missing field gets its own
+ line: follow-up call, derivable, or absent. GitHub inlines convenience
+ data (web URLs, nested profiles, counts) that Origin does not.
+
+**GraphQL.** No endpoint. Decompose each document into the REST reads and
+writes it stands for, map those, and record the fan-out as the row's
+tradeoff.
+
+**Permissions → scopes.** Do not translate the manifest noun-for-noun. Find
+the operations the code calls and take the union of *their*
+`x-origin-scopes.scopes`. GitHub permissions with no Origin noun
+(`statuses`, `issues`, `members`, `organization_*`, `pages`, `actions`,
+`workflows`, `deployments`) go through `origin-isms.md` first.
+
+**Events → slugs.** Each GitHub `event` + `action` pair becomes a candidate
+slug (`pull_request` + `synchronize` → `pull_request.head_ref.pushed`);
+confirm it exists in the webhook index. A candidate that does not exist is
+not an event on Origin; check whether the state change is observable another
+way before classifying.
+
+**Payload fields → schema properties.** For each field path a handler reads,
+walk the mapped slug's payload schema and record one of: **present** at
+`<path>`; **follow-up read** via `<operationId>` with identifiers the payload
+carries; **derivable** from present fields (say how, and whether the format
+is contractual); **absent** (goes to the gap bar). A field on the REST
+component that the webhook twin lacks is a follow-up `Get…` on every event.
+
+## Out of domain and spec-silent
+
+- A concept neither the spec nor `llms-full.txt` mentions (Marketplace
+ billing, merge queues, Actions, Pages, Projects, Discussions, HTML probes)
+ is `unknown` with an up-front question. Never `gap` (Origin has not
+ declined it) and never `by-design-absent` (only `origin-isms.md` rows earn
+ that).
+- A behavior the code depends on that the docs do not state (does an event
+ fire for a draft PR? does `updatedAt` move on a comment?) is an open
+ question plus a hello-world step that observes it on a native repository.
+ Do not resolve it from GitHub's behavior.