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.mdindex 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 usediff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.mdindex 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 touchesOrigin 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: MITcompatibility: >-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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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.