Cursor plugin specification and official plugins
TypeScript
Unslop pass over skills, references, README, and manifests
Cursor Agente97c83e73109
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 505ac1ad..8d18083d 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -8,7 +8,7 @@{"name": "origin-apps","source": "./origin-apps",- "description": "Build on the Cursor Origin API: fetch the live spec first, then apply durable practices for credentials, scopes, webhooks, paging, and errors; includes a skill that plans the port of an existing GitHub App."+ "description": "Skills for building on the Cursor Origin API. Fetch the live spec first, then follow the Origin rules for credentials, scopes, webhooks, paging, and errors. Includes a skill that plans the port of an existing GitHub App."}]}diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.jsonindex 484fedf2..bf0d0b7a 100644--- a/.cursor-plugin/marketplace.json+++ b/.cursor-plugin/marketplace.json@@ -66,7 +66,7 @@{"name": "origin-apps","source": "origin-apps",- "description": "Build on the Cursor Origin API: fetch the live spec first, then apply durable practices for credentials, scopes, webhooks, paging, and errors; includes a skill that plans the port of an existing GitHub App."+ "description": "Skills for building on the Cursor Origin API. Fetch the live spec first, then follow the Origin rules for credentials, scopes, webhooks, paging, and errors. Includes a skill that plans the port of an existing GitHub App."},{"name": "orchestrate",diff --git a/README.md b/README.mdindex a6418fb7..59acad9d 100644--- a/README.md+++ b/README.md@@ -17,7 +17,7 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc| `pr-review-canvas` | [PR Review Canvas](pr-review-canvas/) | Cursor | Developer Tools | Render PR diffs as review canvases grouped by importance. || `docs-canvas` | [Docs Canvas](docs-canvas/) | Cursor | Developer Tools | Render documentation as a navigable canvas. || `cursor-sdk` | [Cursor SDK](cursor-sdk/) | Cursor | Developer Tools | Build apps, scripts, and automations with the TypeScript SDK. |-| `origin-apps` | [Origin Apps](origin-apps/) | Cursor | Developer Tools | Build on the Cursor Origin API: fetch the live spec first, then apply durable practices for credentials, scopes, webhooks, paging, and errors; includes a skill that plans the port of an existing GitHub App. |+| `origin-apps` | [Origin Apps](origin-apps/) | Cursor | Developer Tools | Skills for building on the Cursor Origin API. Fetch the live spec first, then follow the Origin rules for credentials, scopes, webhooks, paging, and errors. Includes a skill that plans the port of an existing GitHub App. || `orchestrate` | [Orchestrate](orchestrate/) | Cursor | Developer Tools | Fan large tasks out across parallel cloud agents with planners, workers, verifiers, and structured handoffs. || `pstack` | [pstack](pstack/) | Lauren Tan | Developer Tools | if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence. || `advisor` | [Advisor](advisor/) | Cursor | Developer Tools | Consult a stronger model before major decisions, when stuck, and before declaring done. |diff --git a/origin-apps/.claude-plugin/plugin.json b/origin-apps/.claude-plugin/plugin.jsonindex b09982da..dde7dcf6 100644--- a/origin-apps/.claude-plugin/plugin.json+++ b/origin-apps/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "origin-apps",- "description": "Build on the Cursor Origin API: fetch the live spec first, then apply durable practices for credentials, scopes, webhooks, paging, and errors; includes a skill that plans the port of an existing GitHub App.",+ "description": "Skills for building on the Cursor Origin API. Fetch the live spec first, then follow the Origin rules for credentials, scopes, webhooks, paging, and errors. Includes a skill that plans the port of an existing GitHub App.","version": "0.1.0","author": {"name": "Cursor",diff --git a/origin-apps/.cursor-plugin/plugin.json b/origin-apps/.cursor-plugin/plugin.jsonindex edd88eed..cefa3aa4 100644--- a/origin-apps/.cursor-plugin/plugin.json+++ b/origin-apps/.cursor-plugin/plugin.json@@ -2,7 +2,7 @@"name": "origin-apps","displayName": "Origin Apps","version": "0.1.0",- "description": "Build on the Cursor Origin API: fetch the live spec first, then apply durable practices for credentials, scopes, webhooks, paging, and errors; includes a skill that plans the port of an existing GitHub App.",+ "description": "Skills for building on the Cursor Origin API. Fetch the live spec first, then follow the Origin rules for credentials, scopes, webhooks, paging, and errors. Includes a skill that plans the port of an existing GitHub App.","author": {"name": "Cursor","email": "[email protected]"diff --git a/origin-apps/CHANGELOG.md b/origin-apps/CHANGELOG.mdindex f7285b41..38ba40c9 100644--- a/origin-apps/CHANGELOG.md+++ b/origin-apps/CHANGELOG.md@@ -2,14 +2,14 @@All notable changes to this plugin will be documented here.-## 0.1.0 — initial release+## 0.1.0, initial release-- Added the `origin-api` skill: fetch the live Origin docs and OpenAPI spec- first, then apply the practices that hold across spec versions (credentials- and token minting, minimal scopes, webhook verification and idempotency,- opaque page tokens, TypeIDs, the error envelope, rate limits, and the- deliberate differences from GitHub).-- Added the `port-github-app-to-origin` skill, built on `origin-api`: discover- a GitHub App's surface from its codebase, map it onto the live Origin API- spec, and write a porting brief with a capability table, webhook field map,- hello-world path, gap cards, and up-front questions.+- Added the `origin-api` skill. It lists the live Origin docs and OpenAPI spec+ to fetch first, then the Origin rules that GitHub habits get wrong:+ credentials and token minting, minimal scopes, webhook verification and+ idempotency, opaque page tokens, TypeIDs, the error envelope, rate limits,+ and the differences from GitHub that are decisions rather than gaps.+- Added the `port-github-app-to-origin` skill, built on `origin-api`. It reads+ what a GitHub App uses from GitHub out of its codebase, maps that onto the+ live Origin spec, and writes a porting brief with a capability table, a+ webhook field map, a hello-world path, gap cards, and up-front questions.diff --git a/origin-apps/README.md b/origin-apps/README.mdindex c6e4f05f..785328a9 100644--- a/origin-apps/README.md+++ b/origin-apps/README.md@@ -1,70 +1,70 @@# Origin Apps-Plugin for building on [Cursor Origin](https://cursor.com/docs/api/origin),-Cursor's code forge: creating an Origin App, calling the API, receiving-webhooks, or bringing an existing GitHub App across. Skills only, so it runs-in Cursor, Claude Code, Codex, and any agent that reads-[Agent Skills](https://agentskills.io).+Two skills for building on [Cursor Origin](https://cursor.com/docs/api/origin),+Cursor's code forge. They cover creating an Origin App, calling the API,+receiving webhooks, and bringing an existing GitHub App across. The plugin is+skills only, so it runs in Cursor, Claude Code, Codex, and any agent that+reads [Agent Skills](https://agentskills.io).## What it includes-- `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.+`origin-api` is the general skill. It lists the sources to fetch first (the+live OpenAPI spec and docs are the only source for endpoints, scopes, and+event slugs) and then the Origin rules that GitHub habits get wrong. Native+versus 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. The differences from GitHub that are decisions, not gaps. Use it+for any Origin work.++`port-github-app-to-origin` builds on `origin-api`. Run it inside your GitHub+App's repository. It reads what the app uses from GitHub out of the code, maps+that onto the live spec, and writes a porting brief with a capability table,+the webhook fields your handlers read and where each comes from on Origin,+the scopes to request, a hello-world path, the gaps worth raising with Cursor,+and the questions to settle first. It plans. It writes no code and estimates+no time.++Both skills fetch the spec at run time and never name an endpoint from memory.## When to use-- You are writing or reviewing code that calls Origin, mints installation- tokens, or receives Origin webhooks: `origin-api`.-- You are creating an Origin App and want the hello-world path and the- first-week traps up front: `origin-api`.-- You have a GitHub App (Probot, Octokit, go-github, hand-rolled) and want to- know what an Origin App version looks like before you start:+- Writing or reviewing code that calls Origin, mints installation tokens, or+ receives Origin webhooks: `origin-api`.+- Creating an Origin App and wanting the first-week traps up front:+ `origin-api`.+- Holding a GitHub App (Probot, Octokit, go-github, hand-rolled) and wanting+ to know what an Origin App version looks like before starting:`port-github-app-to-origin`.-- You want to check which GitHub features Origin deliberately does not- reproduce, and what the Origin idiom is instead: either.+- Checking which GitHub features Origin deliberately does not reproduce, and+ what to do instead: either skill.-In Cursor, ask about the Origin API or ask to port the app; or run+In Cursor, ask about the Origin API or ask to port the app, or run`/origin-api` or `/port-github-app-to-origin`.## Install in Cursor-Search for **Origin Apps** in the Cursor Marketplace+Search for Origin Apps in the Cursor Marketplace([cursor.com/marketplace/origin-apps](https://cursor.com/marketplace/origin-apps)),-or open **Customize**, find the plugin, and install it at user or project-scope.+or open Customize, find the plugin, and install it at user or project scope.## Use outside Cursor-The plugin ships three manifests for one set of skills: a root `plugin.json`+The plugin ships three manifests for one set of skills. A root `plugin.json`([Agent Plugins](https://agent-plugins.org) 1.0), `.cursor-plugin/plugin.json`(Cursor Marketplace), and `.claude-plugin/plugin.json` (Claude Code). Theskills use only portable frontmatter (`name`, `description`, `license`,`compatibility`).-**Claude Code**, via the marketplace manifest at this repository's root:+Claude Code, via the marketplace manifest at this repository's root:```text/plugin marketplace add cursor/plugins/plugin install origin-apps@cursor-plugins```-**Any agent that reads Agent Skills** (Claude Code, Codex, and others): copy-the skill directories into the agent's skills folder. Copy both; the porting+Any agent that reads Agent Skills (Claude Code, Codex, and others): copy the+skill directories into the agent's skills folder. Copy both. The portingskill refers to `origin-api` for fundamentals.```bash@@ -80,9 +80,9 @@ mkdir -p .cursor/skills && cp -r plugins/origin-apps/skills/* .cursor/skills/## Requirements- Network access to `https://cursor.com/docs/api/origin/*` during the run.-- For the porting skill: read access to the app's source. No Origin- credentials are needed to produce the brief; the hello-world path in the- brief is what you follow afterwards.+- For the porting skill, read access to the app's source. Producing the brief+ needs no Origin credentials. You follow the brief's hello-world path+ afterwards.- Optional: `python3` with PyYAML for the porting skill's`scripts/index-origin-spec.py`, which turns the fetched spec into agrep-friendly index. Without it the skill reads the spec directly.@@ -90,8 +90,8 @@ mkdir -p .cursor/skills && cp -r plugins/origin-apps/skills/* .cursor/skills/## Where the brief goesThe porting skill writes `ORIGIN-PORTING-BRIEF.md` at the repository root and-prints its path. Gap cards in the brief are yours to send: through your shared-Slack channel with Cursor if you have one, or to `[email protected]`.+prints its path. The gap cards in the brief are yours to send, through your+shared Slack channel with Cursor if you have one, or to `[email protected]`.## Licensediff --git a/origin-apps/plugin.json b/origin-apps/plugin.jsonindex 61a2f288..75ab6a38 100644--- a/origin-apps/plugin.json+++ b/origin-apps/plugin.json@@ -2,7 +2,7 @@"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json","name": "origin-apps","version": "0.1.0",- "description": "Build on the Cursor Origin API: fetch the live spec first, then apply durable practices for credentials, scopes, webhooks, paging, and errors; includes a skill that plans the port of an existing GitHub App.",+ "description": "Skills for building on the Cursor Origin API. Fetch the live spec first, then follow the Origin rules for credentials, scopes, webhooks, paging, and errors. Includes a skill that plans the port of an existing GitHub App.","author": {"name": "Cursor","email": "[email protected]"diff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.mdindex d670dc84..eb6e1ae5 100644--- a/origin-apps/skills/origin-api/SKILL.md+++ b/origin-apps/skills/origin-api/SKILL.md@@ -1,11 +1,11 @@---name: origin-apidescription: >-- Build on the Cursor Origin API: create an Origin App, authenticate as it,+ 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. Fetch-first sources plus- the gotchas GitHub instinct gets wrong.+ signatures, page tokens, or an Origin App manifest. Lists the sources to+ fetch first and the Origin rules that GitHub habits get wrong.license: MITcompatibility: >-Needs network access to https://cursor.com/docs/api/origin/* at run time.@@ -13,68 +13,73 @@ compatibility: >-# Build on the Origin API-## Fetch first; never name an endpoint, scope, slug, or header from memory+## 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+- `https://cursor.com/docs/api/origin/openapi.yaml` is the contract. Every+ operation carries `x-origin-scopes` (`scopes`, `tokenTypes`, `ambient`).+ Every webhook payload schema carries `x-origin-webhook-events`, the onlyauthoritative 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).+- `https://cursor.com/docs/api/origin/llms-full.txt` covers the installation+ flow, authentication, the scopes table, mirrored repositories, webhook+ headers and verification, the delivery envelope, retries, pagination,+ errors, and current limitations.+- `https://cursor.com/docs/api/origin/llms.txt` is the index.+ `https://cursor.com/docs/api/origin/changelog` says what moved.-Cite `operationId`s and `llms-full.txt` anchors. Where this file and the-fetched docs disagree, the docs win.+Cite `operationId`s and `llms-full.txt` anchors. If this file and the fetched+docs disagree, the docs win.-## Gotchas+## Rules GitHub habits get wrong-- **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.+- **Check native or mirror before anything else.** 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+ every other event in app settings. An unselected event is silence, not anerror.-- **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+- **Signature `v1ed` is Ed25519 over a SHA-256 digest of the raw body**, with+ keys from Origin's JWKS. It matches 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.** It is stable across retries.+ `event.id` identifies the domain event. Return `2xx` after verification and+ process asynchronously, because persistent failure pauses delivery for the+ app.+- **Payloads are lean snapshots** of the one object that changed, plus+ references to its containers. No changed-file lists, before-SHAs, web URLs,+ or inlined profiles. Follow up with the `Get…` for the object and count the+ fan-out. The action is in the slug (`pull_request.review.submitted`). Thereis no `action` field.-- **The installation receipt JWT is proof of consent, never a Bearer token.**+- **The installation receipt JWT proves consent. It is 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+- **The app JWT is EdDSA over Ed25519, not RS256.** Register only the public+ key.+- **Installation tokens are short-lived. Mint them just in time** from the+ app JWT and attenuate to the scopes and `repositoryIds` the job needs (IDs,+ not slugs). Git over HTTPS uses Basic auth with user `x-access-token` and+ the 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.+ mirror transitions) have no app-side path, and 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.+ construct, parse, or reuse one across filter changes. Send `pageSize` on+ every request, including continuations. There is no `Link` header and no+ total.- **IDs are TypeIDs** (`repo_…`, `i_…`, `cmt_…`), never integers. Cache IDs,- not slugs; `/repos/_/{repoId}` survives renames. 64-bit integers (PR+ not slugs. `/repos/_/{repoId}` survives renames. 64-bit integers (PRnumbers, 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+- **`404` means not found or no access.** Branch on status and `code`, never+ on message text. Quote `X-Request-ID` when escalating.+- **The rate limit is a per-principal point budget.** Honor `Retry-After` on+ `429`. Git HTTPS is metered separately. Cursor raises per-app budgets on+ request.+- **These are decisions, not gaps.** No commit statuses (check runs upsert on+ a caller-stable `key`). No Issues (conversation is PR comments, threads,+ reviews, and labels). No GraphQL. No per-repository webhook CRUD. No user or+ email directory. Reviews anchor to a pull request version, not a SHA. Athread 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 dbccfa72..0f17e23e 100644--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md@@ -4,8 +4,8 @@ description: >-Plan the port of an existing GitHub App to a Cursor Origin App. Use when arepo is a GitHub App (manifest, Probot, Octokit or another GitHub SDK, webhooksignature handlers) and the task is to bring it to Origin or compare it with- the Origin API. Maps the app's surface onto the live Origin spec and writes a- porting brief. No code.+ the Origin API. Maps what the app uses from GitHub onto the live Origin spec+ and writes a porting brief. No code.license: MITcompatibility: >-Needs network access to https://cursor.com/docs/api/origin/* at run time.@@ -15,53 +15,58 @@ compatibility: >-# Port a GitHub App to an Origin App-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.+Run inside the GitHub App's codebase. The output is a porting brief+(`references/brief-template.md`), not an implementation. It says what maps,+what changes shape, what is absent on purpose, and what is worth raising with+Cursor.-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:+The `origin-api` skill in this plugin covers which docs to fetch, credentials,+scopes, webhooks, paging, IDs, errors, and the deliberate differences from+GitHub. Follow it first. Nothing here repeats it. Two rules on top:1. **Discover, do not ask.** Read permissions, events, handlers, calls, tokenminting, and the receiver out of the code. Never ask for a manifest or an- endpoint list. What is genuinely undiscoverable becomes an open question.+ endpoint list. Anything you cannot find 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.+ `references/origin-isms.md` is `by-design-absent` or `reshaped`, with a+ pointer to the idiom. It never becomes a gap card.## Procedure-1. **Load the spec** (`origin-api` § Fetch first). Record `info.version` and+1. **Load the spec** (`origin-api`, "Fetch first"). Record `info.version` andthe 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`.+ `references/spec-mapping.md`. `scripts/index-origin-spec.py openapi.yaml`+ prints it and needs PyYAML.+2. **Discover** per `references/discovery.md`. Record 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 the webhook+ payload fields the code reads, not only the event names. A field GitHub+ inlines is often a follow-up read on Origin, so name the call for each+ field. Then:+ - Check `origin-isms.md` before writing `gap`. Check `gap-bar.md` before+ writing any card.+ - A GitHub feature the Origin docs never mention (Marketplace billing,+ merge queues, Actions, Pages) is `unknown` with a question. It is 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+ 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.+ `operationId`, a slug, or an `llms-full.txt` anchor. Sizes are S, M, or 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.+ first is always native or mirror, because 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).+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 and the team decides.## Reference files@@ -69,8 +74,8 @@ cards to Cursor (the brief carries them; the team decides).| --- | --- || `../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/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/gap-bar.md` | Deciding whether a difference earns a card, and writing it. || `references/brief-template.md` | Writing the output. || `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 f20b5ae3..04c9e23f 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,11 +1,11 @@# Porting brief template-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.+Write 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. 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`. One table row per capability, one line per follow-up field, one+card per gap. The team will argue over it in one sitting.## Labels@@ -13,29 +13,30 @@ per gap; the team will argue over it in one sitting.| Label | Meaning || --- | --- |-| `same` | Same capability, same shape; a path or field rename at most. |-| `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. |+| `same` | Same capability, same shape. A path or field rename at most. |+| `reshaped` | Same capability, different shape (pagination, identifier form, event granularity, key semantics). The code changes, the behavior does not. |+| `workaround` | Same outcome by a different route (follow-up read, client-side filter, marker). The Tradeoff column is 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. |+| `preview` (suffix) | The Origin operation is `x-cursor-visibility: PREVIEW`. Usable. The shape may move. |**Size** (kind of change, never time)| Size | Meaning || --- | --- |-| 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. |+| S | Adapter or client layer. A path, header, identifier, or pagination rewrite, or a re-keyed lookup. |+| M | A new code path. A follow-up read where the payload used to suffice, a handshake step, a new 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 native repositories, an open gap card. |## Template```markdown-# Origin porting brief — <app name>+# Origin porting brief for <app name>-Planning document. Maps this GitHub App's surface onto the Cursor Origin API-as published on <date>. No decisions about language, framework, or client.+Planning document. Maps what this GitHub App uses from GitHub onto the Cursor+Origin API as published on <date>. It makes no decisions about language,+framework, or client.## Provenance@@ -43,12 +44,12 @@ as published on <date>. No decisions about language, framework, or client.- Docs read: <the URLs>- Codebase: `<repo>` at `<commit>`- Re-check `workaround` and `gap` rows against the changelog before work- starts; they move most.+ starts. They are the rows most likely to have moved.## 1. What the app is today-One paragraph: what it does for its users, which events drive it, what it-writes back. Then:+One paragraph on what it does for its users, which events drive it, and what+it writes back. Then:| Facet | Finding | Evidence || --- | --- | --- |@@ -65,9 +66,9 @@ writes back. Then:## 2. First decision: which repositories<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.**+scopes only on Origin-native repositories and stable outbound mirrors.+Repositories mirrored from GitHub are read-only to apps and deliver no push+events. **Answer question 1 before attempting § 5.**## 3. Capability table@@ -79,16 +80,16 @@ 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`) | `<operationId>` | same | S | — | — |+| `GET /repos/{o}/{r}/pulls/{n}` (`src/x.ts:12`) | `<operationId>` | same | S | none | none |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.+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 everyOrigin 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.+and implied scopes (`write` implies `read`, and `repository:metadata:read` is+automatic). The install URL's `scope` parameter carries this list.## 4. Webhook payload fields the code reads@@ -97,39 +98,41 @@ automatic). This is what the install URL's `scope` parameter carries.| `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>` with the call count-per event; derivable (from what; is the format documented); absent (→ § 3's-label). Include fields read only for logging.+"How" is one of five values. Present at `<path>`. Present in the envelope+(`event.type` for GitHub's `action`). Follow-up read via `<operationId>`,+with the call count per event. Derivable, saying from what and whether the+format is documented. Absent, pointing at the row's label in § 3. Include+fields read only for logging.## 5. Hello-world path-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.+The shortest route to one real event from one native repository. Each step+is a verification, linked to `llms-full.txt`. Append one step for each+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.+1. Create the app, register the Ed25519 public key, and set the 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+3. Install on an Origin-native repository. Verify the receipt JWT and readthe 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.+4. Mint an app JWT, exchange it for an installation token, and confirm the+ repository is listed with the mirror state § 2 expects.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.+ fields arrive. If the ping arrived and this did not, 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: "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, write "No row failed+the gap bar. The workarounds in § 3 carry their tradeoffs." Do not pad.## 7. Questions for the team-Always the first three; then what discovery left open.+Always the first three, then what discovery left open.1. Native repositories (or stable outbound mirrors), or repositories mirroredfrom GitHub? Decides whether the app receives events and can write.@@ -139,12 +142,12 @@ Always the first three; then what discovery left open.Origin?4. Does anything key approvals or reviews by commit SHA rather than PRversion?-5. How do you identify your own check runs / comments / reviews today; can a- key or marker you control replace actor matching?+5. How do you identify your own check runs, comments, and 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 scopeNo implementation, no SDK or language choice, no time estimates. The brief is-a map; the route is the team's.+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 a6258c3b..bc408bc8 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,56 +1,54 @@-# Discovering the GitHub App's shape from the codebase+# Discovering what the GitHub App uses, from its codebase-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.+Everything the brief needs about the app is in the repository. Search for it.+Do not ask for it. 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.+ if it is checked in (`app.yml`, a manifest JSON, IaC that seeds the app;+ Probot keeps `default_events` and `default_permissions` in `app.yml`). If+ there is none, 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 codedispatches on (`app.on("pull_request.opened")`, a switch on- `x-github-event` + `payload.action`, SDK parsers), with the handler+ `x-github-event` plus `payload.action`, SDK parsers), with the handlerlocation.-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.+3. **Payload fields read.** Every property path each handler and its helpers+ dereference from the payload. 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 and path,+ or SDK method) with the parameters and filters the code passes, the+ response fields it reads, whether it runs per webhook or in a loop (this+ decides the fan-out tradeoff), and the pagination style in use. Pagination+ always changes. GraphQL documents count as calls. Mapping decomposes them.+5. **Authentication and token minting.** The app JWT algorithm. How the code+ identifies the installation after install (callback query, webhook, DB).+ Token lifetime handling. Whether user OAuth exists and what it is for+ (identity, repository discovery, acting for a user). Whether the app clones+ or pushes git as itself.+6. **Webhook receiver and verification.** The signature scheme. Whether the+ raw body is available at verification time (a framework that parses JSON+ first cannot verify). How the code deduplicates deliveries, if it does.+ Where the public URL is configured.+7. **Calls the framework makes on the app's behalf.** They are not in the+ app's source, but the port has to make them. List them as rows marked+ "from `<dependency>` (documented behavior)" and read the dependency's docs+ or source, not the app. Common cases:+ - Probot: the built-in receiver and HMAC verification, per-installation+ token minting and caching, `context.repo()` and `context.issue()`,+ `context.isBot`. Companions: `probot-config` reads `.github/<file>.yml`+ and falls back to the owner's `.github` repository; `probot-scheduler`+ lists installations and repositories with the app credential and emits+ `schedule.repository`; `probot-metadata` stores state in issue bodies.+ - Octokit `App`: `webhooks.verifyAndReceive`, `eachInstallation` and+ `eachRepository`, 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.+fill it in 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 fd732713..60ee0d17 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,74 +1,75 @@# The gap bar and the escalation card-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.+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 the tradeoff and an open question, not as a card.-- A **difference** is any row whose parity label is not `same`.-- 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.+- A difference is any row whose parity label is not `same`.+- A workaround reaches the same outcome with today's API by another route. 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+ fails one of the five tests below. Only gaps become cards.## Nontrivial tradeoff-At least one must hold; quote it on the card.+At least one must hold. Quote it on the card.| Tradeoff | Test || --- | --- |-| **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. |+| Fan-out at scale | Calls per event multiply by a factor that grows with repository or activity size (N commits × M files, or 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 return a wrong answer, not only a slower one. Heuristic "my own row" matching. Inferring a PR from a SHA 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. |+| Customer-visible behavior | The workaround changes what the team's users see or can do, not how the code is organized. |+| Load-bearing | The capability 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 field or filter the code does not use.- A GitHub convenience (`Link` pagination, numeric IDs, `html_url`) where theOrigin convention is a mechanical substitution.-- Something the changelog says shipped or the spec already carries. Re-check- the live spec before writing any card.+- Anything the changelog says shipped or the spec already carries. Re-read 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.+ Actions, Projects). That is `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 costs+ proportional to the matches, not the collection. If that count fails the+ bar, the card is 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 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.+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. Do not write it when the app+only logs or tidies up on that change.## The card-One per gap, in the brief's "Gaps worth raising" section, written so Cursor-can act without a call:+One per gap, in the brief's "Gaps worth raising" section. Write it so Cursor+can act without a call.```markdown### Gap: <capability, in Origin terms>-- **GitHub surface the app uses:** `<METHOD /path>` / `<event.action>` / `<permission>`, at `<file:line>`.+- **GitHub call, event, or permission:** `<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>` / `<slug>` / none, and what it lacks.+- **Closest Origin operation 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>.+- **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>`.```-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`.+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, through their shared Slack channel with Cursor or to+`[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. It 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 db4f021a..c4ca2326 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,11 +1,11 @@-# Origin-isms: GitHub surfaces Origin departs from on purpose+# Origin-isms: GitHub features Origin departs from on purposeCheck 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`.+or `reshaped`. The brief points at the idiom and never files a card. The+`origin-api` skill carries the reasoning. This table carries only the label+and the idiom. Confirm current wording in `llms-full.txt`.-| GitHub surface the app uses | Label | Origin idiom |+| GitHub call, event, or permission | 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. |@@ -26,12 +26,12 @@ what the classifier needs. Confirm current wording in `llms-full.txt`.| 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. |+| Fields GitHub inlines in payloads (changed files on push, before-SHA, `html_url`, `sender` profile) | `reshaped` | Follow-up `Get…`, `CompareCommits`, or `ListComparisonFiles` with identifiers the payload carries. Name the call for each field and 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`.+A feature that is not on this list and that the Origin docs never mention+(Marketplace billing, merge queues, Actions, Pages, Projects) is `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 0a788ba5..a3928bfd 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,30 +1,29 @@-# Reading the Origin spec and matching GitHub surface to it+# Reading the Origin spec and matching GitHub calls and events to 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.+Every mapping in the brief comes from the fetched `openapi.yaml`, not from a+table here. Build the index once. Every later step looks things up in it.## Extensions the spec carries| Extension | Where | Meaning || --- | --- | --- |-| `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. |+| `x-origin-scopes` | every operation | `scopes` the operation requires. `tokenTypes` it accepts (`app`, `installation`, `user`). `ambient: true` means there is 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 it from `$ref`s. Pushes, deletions, and reviewer requests are event-native with no REST twin. |+| `x-cursor-visibility: PREVIEW` | some operations | Usable. The shape may move. Carry the badge into the brief as a `preview` suffix. |## Build the index1. **Operations**: `operationId`, method, path, `x-origin-scopes`,- visibility, parameter names, request top-level fields, response component.+ visibility, parameter names, top-level request 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).+3. **Scopes**: the union of every `scopes` value, annotated with the+ operations that need it. Separate installation-requestable scopes from+ ambient and user-only ones. The user-only set tells you which GitHub flows+ have no app-side equivalent.4. **Resources**: component schemas returned by `Get…`/`List…`, with fieldnames, for "does the Origin object carry this field".@@ -33,10 +32,10 @@ prints all four.## Matching-Match in this order; stop at the first rule that yields a *confirmed*+Match in this order and stop at the first rule that yields a confirmedcounterpart. 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.+parameters and it answers the same question the GitHub call answers. A name+match is a candidate, never a result.**REST calls**@@ -46,21 +45,22 @@ never a result.`…/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`.+ That is a path change, not a gap. When the code uses them on real issues,+ see `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.+ `/user/installations`, `/orgs/…`, `/search/…`, and `/repositories/{id}`+ have no path counterpart. Consult `origin-isms.md` before labeling them.+4. Compare parameters as well as paths. A matching path that lacks a filter+ the code depends on is `workaround` or `gap`, not `same`.+5. Compare the response fields the code reads. Each missing field gets its+ own line as follow-up call, derivable, or absent. GitHub inlines web URLs,+ nested profiles, and counts that Origin does not.++**GraphQL.** There is 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. Findthe operations the code calls and take the union of *their*@@ -69,26 +69,27 @@ the operations the code calls and take the union of *their*`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.+slug (`pull_request` plus `synchronize` becomes `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 it.**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.+walk the mapped slug's payload schema and record one of four outcomes.+Present at `<path>`. Follow-up read via `<operationId>` with identifiers the+payload carries. Derivable from present fields, saying how and whether the+format is contractual. Absent, which goes to the gap bar. A field on the REST+component that the webhook twin lacks means a follow-up `Get…` on every+event.## Out of domain and spec-silent- A concept neither the spec nor `llms-full.txt` mentions (Marketplacebilling, 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).+ is `unknown` with an up-front question. It is never `gap`, because Origin+ has not declined it, and never `by-design-absent`, because 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+ fire for a draft PR? does `updatedAt` move on a comment?) becomes an openquestion plus a hello-world step that observes it on a native repository.- Do not resolve it from GitHub's behavior.+ Do not settle it from GitHub's behavior.