Cursor plugin specification and official plugins
TypeScript
Point at per-section reference pages
Cursor Agente7f7503434b6
diff --git a/origin-apps/skills/origin-api/SKILL.md b/origin-apps/skills/origin-api/SKILL.mdindex f45fa68e..18fdb15d 100644--- a/origin-apps/skills/origin-api/SKILL.md+++ b/origin-apps/skills/origin-api/SKILL.md@@ -20,56 +20,57 @@ rules to check first; it does not restate the docs.Do not name an endpoint, scope, event slug, header, or limit from memory.-- `https://cursor.com/docs/api/origin/openapi.yaml`: the contract. Its- `x-origin-*` extensions are summarized under `#endpoint-reference`.-- `https://cursor.com/docs/api/origin/llms-full.txt`: the prose reference.- Anchors below are sections of this file.-- `https://cursor.com/docs/api/origin/llms.txt` (index) and- `https://cursor.com/docs/api/origin/changelog` (what moved).+All paths below are under `https://cursor.com/docs/api/origin/`.-For one question, use `llms.txt` to find the section, then read only that-section. Fetch the whole `llms-full.txt` or `openapi.yaml` when the task-needs broad coverage, such as a porting brief.+- `llms.txt`: the index. Every section, endpoint, and webhook payload has its+ own page at `reference/<anchor>.md`, and the index links to each.+- `openapi.yaml`: the contract. Its `x-origin-*` extensions are summarized in+ `reference/endpoint-reference.md`.+- `llms-full.txt`: every reference page in one file. `changelog`: what moved.-Cite `operationId`s and `llms-full.txt` anchors. Where this file and the docs+For one question, read `llms.txt`, then fetch the one `reference/<anchor>.md`+that answers it. Fetch the whole `llms-full.txt` or `openapi.yaml` only for+broad work, such as a porting brief.++Cite `operationId`s and reference pages. Where this file and the docsdisagree, the docs win.## Where to look-| Question | Section of `llms-full.txt` |+| Question | Page || --- | --- |-| Which credential for which call; minting and lifetime | `#authentication` through `#git-https-authentication` |-| Install flow and the callback receipt | `#installation`, `#installation-receipt` |-| Which scope an operation needs | `x-origin-scopes` on the operation; `#scopes` |-| What an installation can do on a mirrored repository | `#mirrored-repositories` |-| Webhook headers, signature, envelope, retries, pausing, recovery | `#webhooks` |-| Which events exist and which arrive without subscribing | `#events` |-| Payload shapes | `#event-payloads` |-| Pagination, errors, request IDs, repository paths | `#common-conventions` |-| ID form and stability | `#ids` |-| What a `PREVIEW` badge means | `#preview` |-| Rate limits | `#rate-limits` |-| Check-run keys, attempts, stale writes | `#check-runs` |-| What is not there yet | `#current-limitations` |-| A checklist to build against | `#implementation-checklist` |+| Which credential for which call; minting and lifetime | `reference/authentication.md` and its subsections through `reference/git-https-authentication.md` |+| Install flow and the callback receipt | `reference/installation.md`, `reference/installation-receipt.md` |+| Which scope an operation needs | `x-origin-scopes` on the operation; `reference/scopes.md` |+| What an installation can do on a mirrored repository | `reference/mirrored-repositories.md` |+| Webhook headers, signature, envelope, retries, pausing, recovery | `reference/webhooks.md` |+| Which events exist and which arrive without subscribing | `reference/events.md` |+| Payload shapes | `reference/event-payloads.md` |+| Pagination, errors, request IDs, repository paths | `reference/common-conventions.md` |+| ID form and stability | `reference/ids.md` |+| What a `PREVIEW` badge means | `reference/preview.md` |+| Rate limits | `reference/rate-limits.md` |+| Check-run keys, attempts, stale writes | `reference/check-runs.md` |+| What is not there yet | `reference/current-limitations.md` |+| A checklist to build against | `reference/implementation-checklist.md` |## Rules to check first1. **Native or mirror.** Confirm the target repositories are Origin-nativeor stable outbound mirrors. On any other mirror state an installation can- only read, and pushes are not delivered (`#mirrored-repositories`,- `#events`).+ only read, and pushes are not delivered (`reference/mirrored-repositories.md`,+ `reference/events.md`).2. **Subscribe.** Only the `installation.*` events arrive without a- subscription; a missing subscription is silence, not an error (`#events`).+ subscription; a missing subscription is silence, not an error (`reference/events.md`).3. **Verify, dedupe, acknowledge.** Verify the signature over the raw bodybefore parsing, dedupe on the delivery ID, return `2xx`, then process- (`#signature-verification`, `#retries`, `#automatic-disable`). The digest+ (`reference/signature-verification.md`, `reference/retries.md`, `reference/automatic-disable.md`). The digeststep differs from the Standard Webhooks spec; do not assume a genericverifier passes.4. **Scopes from the spec.** Request the union of `x-origin-scopes.scopes`- over the operations the app calls (`#scopes`).+ over the operations the app calls (`reference/scopes.md`).5. **Opaque tokens and IDs.** Do not build or parse page tokens or IDs- (`#pagination`, `#ids`).+ (`reference/pagination.md`, `reference/ids.md`).Porting an existing GitHub App: the `port-github-app-to-origin` skill inthis plugin covers how its capabilities map onto Origin.diff --git a/origin-apps/skills/port-github-app-to-origin/SKILL.md b/origin-apps/skills/port-github-app-to-origin/SKILL.mdindex f40aabfe..4478a40d 100644--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md@@ -37,15 +37,16 @@ Adapt the steps to the app. The brief format matters most in its Feedbacksection.1. **Load the spec.** A brief needs broad coverage, so fetch the full- `openapi.yaml` and `llms-full.txt`. Record `info.version` and the fetch- time for provenance. Build the index per `references/spec-mapping.md`.+ `openapi.yaml` and `llms-full.txt` (see `origin-api` for URLs). Record+ `info.version` and the fetch time for provenance. Build the index per+ `references/spec-mapping.md`.2. **Discover** per `references/discovery.md`, including payload fields readonly for logging and calls the framework makes on the app's behalf. Notewhat you looked for and did not find.3. **Map** each capability (`references/spec-mapping.md`). Map the payloadfields the code reads, not only the event names; if a payload lacks afield the REST resource has, a follow-up read is the usual answer- (`#event-payloads`). Check `references/origin-isms.md` before calling+ (`reference/event-payloads.md`). Check `references/origin-isms.md` before callinganything a gap, and `references/gap-bar.md` before writing feedback. Acapability the Origin docs do not mention is not available today and getsa question. A behavior the docs neither confirm nor deny becomes a@@ -53,7 +54,7 @@ section.carried over from the app's current platform.4. **Write the brief** per `references/brief-template.md`: guidance and adefault outline, not a form. Every Origin claim names an `operationId`, a- slug, or an `llms-full.txt` anchor. When there is feedback, also write the+ slug, or a `reference/<anchor>.md` page. When there is feedback, also write theFeedback section to `ORIGIN-FEEDBACK.md` beside the brief.5. **Self-check** before finishing: every Origin claim resolves in thefetched files; every gap has a feedback entry that names a tradeoff fromdiff --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 8061f723..b8f34deb 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@@ -14,17 +14,17 @@ headings to fit the app.rest (usually native or mirror), and whether there is feedback for Cursorand if any of it blocks.- **Maps what the app uses to Origin.** Every capability the code relies on,- with the Origin operation, slug, or `llms-full.txt` anchor it maps to, or a+ with the Origin operation, slug, or reference page it maps to, or anote that nothing does. Where a webhook handler reads specific payloadfields, say per field whether it is present, comes from the envelope, needsa follow-up read (and how many per event), is derivable, or is absent.Group by facet if the table is long. End with the scopes to request: theunion of `x-origin-scopes.scopes` over the operations named, minus what- `#scopes` says is automatic or implied.+ `reference/scopes.md` says is automatic or implied.- **Gives an app-specific first-run path when it helps.** The events toselect by slug, the mirror-state check, the first event that should arriveand what it should carry, the first write. Generic setup steps belong to- `llms-full.txt#implementation-checklist`, not here. Skip for a read-only app+ `reference/implementation-checklist.md`, not here. Skip for a read-only appwith one event.- **Adds plan notes.** What drives the size of the port (a few bullets, notime estimates) and how to roll it out: dual-run or cutover, what a mirror@@ -45,7 +45,7 @@ headings to fit the app.- Every claim about the app cites evidence: `file:line`, or "from`<dependency>` (documented behavior)". Team-facing sections only.- Every claim about Origin resolves in the fetched `openapi.yaml` or- `llms-full.txt`: an `operationId`, a slug, or an anchor. Nothing from+ `llms-full.txt`: an `operationId`, a slug, or a reference page. Nothing frommemory.- Behavior the docs do not state is a question plus a first-run step thatobserves it, never an assumption.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 90304a1f..8acec6d4 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@@ -2,39 +2,39 @@Check here before calling anything a gap. Each row says whether a documentedOrigin path exists (`maps`) or nothing in the current spec covers it-(`not-available`), and where the Origin answer lives (an anchor in-`llms-full.txt` unless noted). A `maps` row is a question only if the team+(`not-available`), and where the Origin answer lives (a page under+`https://cursor.com/docs/api/origin/` unless noted). A `maps` row is a question only if the teamwants the old shape back. A `not-available` row is a question, and feedbackif it meets the bar in `gap-bar.md`. Read the source; do not copy this tableinto the brief.| What the app uses today | Mark | Where the Origin answer lives || --- | --- | --- |-| Writes or `push` events on a repository mirrored from GitHub | `maps` | Read-only until the mirror becomes a stable outbound mirror (`#mirrored-repositories`); pushes are not delivered for GitHub-sourced mirrors (`#events`). Transitioning is a user-credential operation. First question of every brief. |-| Install callback query parameters (`installation_id`, `setup_action`) | `maps` | `#installation-receipt` |-| RS256 app JWT | `maps` | `#app-jwt` |-| Long-lived installation tokens | `maps` | `#installation-access-token` |-| User OAuth, `/user`, `/user/installations`, install-by-user picker | `not-available` | No user-credential flow for apps in the current spec. Repository discovery is through the installation; namespace-wide listing is under `#current-limitations`. Ask what the flow should do. |-| Permissions `<noun>: read\|write` | `maps` | `#scopes`; `x-origin-scopes` per operation |-| Numeric IDs, `/repositories/{id}` | `maps` | `#ids`, `#repository-paths` |-| `Link` / `page` / `per_page` pagination, total counts | `maps` | `#pagination` |+| Writes or `push` events on a repository mirrored from GitHub | `maps` | Read-only until the mirror becomes a stable outbound mirror (`reference/mirrored-repositories.md`); pushes are not delivered for GitHub-sourced mirrors (`reference/events.md`). Transitioning is a user-credential operation. First question of every brief. |+| Install callback query parameters (`installation_id`, `setup_action`) | `maps` | `reference/installation-receipt.md` |+| RS256 app JWT | `maps` | `reference/app-jwt.md` |+| Long-lived installation tokens | `maps` | `reference/installation-access-token.md` |+| User OAuth, `/user`, `/user/installations`, install-by-user picker | `not-available` | No user-credential flow for apps in the current spec. Repository discovery is through the installation; namespace-wide listing is under `reference/current-limitations.md`. Ask what the flow should do. |+| Permissions `<noun>: read\|write` | `maps` | `reference/scopes.md`; `x-origin-scopes` per operation |+| Numeric IDs, `/repositories/{id}` | `maps` | `reference/ids.md`, `reference/repository-paths.md` |+| `Link` / `page` / `per_page` pagination, total counts | `maps` | `reference/pagination.md` || GraphQL | `not-available` | No GraphQL endpoint in the current spec. Decompose into REST calls and count the fan-out; a decomposition that meets the feedback bar earns an entry about that read. |-| Commit statuses (`statuses` permission, `POST /statuses/{sha}`) | `maps` | `#check-runs` (check runs with a stable `key`) |+| Commit statuses (`statuses` permission, `POST /statuses/{sha}`) | `maps` | `reference/check-runs.md` (check runs with a stable `key`) || Issues (`issues` permission, `issues.*` events, `/issues/{n}` not on a pull request) | `not-available` | No Issues endpoints or events in the current spec. Pull request comments, threads, reviews, and labels cover the pull-request half. Ask what the team needs for the rest; an issue-driven app may earn a feedback entry. || `/issues/{n}/comments`, `/issues/{n}/labels` used on a pull request | `maps` | Pull requests endpoint reference; same calls under `/pulls/{n}/…` |-| Repository webhook CRUD (`/repos/…/hooks`) | `maps` | Subscriptions are set per app through Create App / Update App `events` (`#events`). |-| App-manifest conversion | `maps` | App creation form or `CreateApp` (`#installation`, endpoint reference) |+| Repository webhook CRUD (`/repos/…/hooks`) | `maps` | Subscriptions are set per app through Create App / Update App `events` (`reference/events.md`). |+| App-manifest conversion | `maps` | App creation form or `CreateApp` (`reference/installation.md`, endpoint reference) || OAuth-app token mints | `not-available` | Nothing in the current spec. Ask what the flow was for. |-| Git Data API commit and ref writes | `maps` | Create Commit From Files, Create Git Ref (Git data endpoint reference); `#git-https-authentication` for pushes |+| Git Data API commit and ref writes | `maps` | Create Commit From Files, Create Git Ref (Git data endpoint reference); `reference/git-https-authentication.md` for pushes || Git Data API arbitrary blob or tree writes | `not-available` | Not in the current spec. Ask whether commit-from-files or a push covers the use. |-| Standalone review-thread objects | `maps` | A thread comes from its first diff-anchored comment (Pull requests endpoint reference); thread listing is under `#current-limitations`. |-| User, email, team, and member lookups | `not-available` | No directory reads in the current spec. Reviewer identifiers resolve by public id, user email, or group slug; `handle` is present when the profile is public (`#resource-references`). |-| Single `pull_request` event with an `action` field, `previous_attributes` | `maps` | `#events`, `#event-payloads` |-| `x-github-*` headers, HMAC `x-hub-signature-256` | `maps` | `#headers`, `#signature-verification` |-| Payload inlines (changed files on push, before-SHA, `html_url`, `sender` profile) | `maps` | `#resource-references`; the push commit list is under `#current-limitations` and may change. Name the follow-up call per field and count the fan-out. |-| All events delivered after app creation | `maps` | `#events` |+| Standalone review-thread objects | `maps` | A thread comes from its first diff-anchored comment (Pull requests endpoint reference); thread listing is under `reference/current-limitations.md`. |+| User, email, team, and member lookups | `not-available` | No directory reads in the current spec. Reviewer identifiers resolve by public id, user email, or group slug; `handle` is present when the profile is public (`reference/resource-references.md`). |+| Single `pull_request` event with an `action` field, `previous_attributes` | `maps` | `reference/events.md`, `reference/event-payloads.md` |+| `x-github-*` headers, HMAC `x-hub-signature-256` | `maps` | `reference/headers.md`, `reference/signature-verification.md` |+| Payload inlines (changed files on push, before-SHA, `html_url`, `sender` profile) | `maps` | `reference/resource-references.md`; the push commit list is under `reference/current-limitations.md` and may change. Name the follow-up call per field and count the fan-out. |+| All events delivered after app creation | `maps` | `reference/events.md` || Reviews keyed by `commit_id` | `maps` | `pullRequestVersion` on the review schema |-| Finding own check runs or comments by actor | `maps` | `#check-runs` (`key`); comments and reviews by a marker the app controls |+| Finding own check runs or comments by actor | `maps` | `reference/check-runs.md` (`key`); comments and reviews by a marker the app controls || Requested-reviewer team pages, `created_via` | `not-available` | Groups exist and resolve by slug; there is no group membership read in the current spec. |A capability that is not on this list and that the Origin docs do notdiff --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 54c45634..fb728aea 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,5 +1,7 @@# Reading the Origin spec and matching GitHub calls and events to it+Paths like `reference/<anchor>.md` are under `https://cursor.com/docs/api/origin/`.+Every mapping in the brief comes from the fetched `openapi.yaml`, not from atable here. Build the index once. Every later step looks things up in it.@@ -7,9 +9,9 @@ table here. Build the index once. Every later step looks things up in it.| Extension | Where | Use || --- | --- | --- |-| `x-origin-scopes` | every operation | The scope and credential rules for that operation. `llms-full.txt#scopes`, `#endpoint-reference`. |-| `x-origin-webhook-events` | payload schemas | The slugs that deliver this payload shape; a schema carrying it is a webhook family. `#event-payloads`. Infer the embedded resource from its `$ref`s; some families have no REST twin. |-| `x-cursor-visibility: PREVIEW` | operations, parameters, schemas, fields | `#preview`. Note it in the brief on any capability that touches a badged element. |+| `x-origin-scopes` | every operation | The scope and credential rules for that operation. `reference/scopes.md`, `reference/endpoint-reference.md`. |+| `x-origin-webhook-events` | payload schemas | The slugs that deliver this payload shape; a schema carrying it is a webhook family. `reference/event-payloads.md`. Infer the embedded resource from its `$ref`s; some families have no REST twin. |+| `x-cursor-visibility: PREVIEW` | operations, parameters, schemas, fields | `reference/preview.md`. Note it in the brief on any capability that touches a badged element. |## Build the index@@ -17,19 +19,20 @@ table here. Build the index once. Every later step looks things up in it.prints every `operationId` with its scope block. From it, note the unionof scopes with the operations that need each, and separateinstallation-requestable scopes from ambient and user-only ones- (`llms-full.txt#scopes` explains the difference). The user-only set tells+ (`reference/scopes.md` explains the difference). The user-only set tellsyou which GitHub flows have no app-side equivalent. Read parameters andresponse components from the spec when a rule below asks for them.2. **Webhook events**: `rg -A3 'x-origin-webhook-events:' openapi.yaml` lists- every slug with its payload schema. Each family's fields, with nested- objects expanded to dotted paths, are under its heading in- `llms-full.txt` (`rg -n '^### Pull Request Events$' llms-full.txt`, then- read to the next `###`). From `#events`, note which slugs are delivered+ every slug with its payload schema. Each family has its own page with the+ fields expanded to dotted paths (`reference/pull-request-events.md`; find+ the page in `llms.txt`). In a broad run with `llms-full.txt` already+ fetched, `rg -n '^### Pull Request Events$' llms-full.txt` and read to the+ next `###`. From `reference/events.md`, note which slugs are deliveredwithout a subscription and which must be selected.-3. **Resources**: each endpoint's "Response Fields" in `llms-full.txt`- (`rg -n '^### Get Pull Request$' llms-full.txt`) lists the fields the- object carries, nested objects expanded, for "does the Origin object carry- this field".+3. **Resources**: each endpoint's page lists its "Response Fields" with nested+ objects expanded (`reference/get-pull-request.md`), for "does the Origin+ object carry this field". Fallback in a broad run:+ `rg -n '^### Get Pull Request$' llms-full.txt`.## Matching@@ -41,7 +44,7 @@ match is a candidate, not a result.**REST calls**1. Look for the same resource path under the Origin base path- (`llms-full.txt#repository-paths` and `#ids` give the path forms). Most GitHub+ (`reference/repository-paths.md` and `reference/ids.md` give the path forms). Most GitHubrepository, pull request, check, label, branch, and commit paths have adirect or near-direct counterpart.2. Re-home GitHub's issue-flavored pull request calls (`/issues/{n}/comments`,@@ -70,12 +73,12 @@ 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 maps to at most one-slug in `llms-full.txt#events`; the action is part of the slug. A pair with+slug in `reference/events.md`; the action is part of the slug. A pair withno slug is not an event on Origin. Check whether the state change isobservable another way before classifying it.**Payload fields → schema properties.** For each field path a handler reads,-walk the mapped family's "Payload Fields" list in `llms-full.txt` and record+walk the mapped family's "Payload Fields" list on its reference page and recordone of five outcomes, matching the brief template's "How" column.Present at `<path>`. Present in the envelope (`event.type` carries whatGitHub puts in `action`). Follow-up read via `<operationId>` with identifiers@@ -86,7 +89,7 @@ event.## Out of domain and spec-silent-- A concept neither the spec nor `llms-full.txt` mentions is not available+- A concept neither the spec nor the reference pages mention is not availabletoday and gets a question rather than a gap: there is no Origin answer yetto compare against, and the question is how the team tells Cursor theyneed it.