Skip to content

Cursor plugin specification and official plugins

TypeScript

Brief template becomes guidance; four optional marks; feedback file

Cursor Agenta8da80c63e9f
diff --git a/origin-apps/README.md b/origin-apps/README.md
index 8794cd71..4b7027c9 100644
--- a/origin-apps/README.md
+++ b/origin-apps/README.md
@@ -17,7 +17,7 @@ tokens and IDs). Use it for any Origin work.
inside the app's repository. It reads what the app uses out of the code, maps
that onto the live Origin 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, feedback for Cursor, and
+Origin, the scopes to request, a first-run path, feedback for Cursor, and
the questions your team should settle first. It plans; it writes no code
unless you ask.
@@ -81,8 +81,9 @@ mkdir -p .cursor/skills && cp -r plugins/origin-apps/skills/* .cursor/skills/
## Where the brief goes
The porting skill writes `ORIGIN-PORTING-BRIEF.md` at the repository root and
-prints its path. The Feedback for Cursor section is written to be sent as is;
-the rest of the brief is for your team.
+prints its path. When there is feedback for Cursor, it also writes that
+section to `ORIGIN-FEEDBACK.md`, ready to send as is; the rest of the brief
+is for your team.
## License
diff --git a/origin-apps/skills/port-github-app-to-origin/SKILL.md b/origin-apps/skills/port-github-app-to-origin/SKILL.md
index 5467e11e..f40aabfe 100644
--- a/origin-apps/skills/port-github-app-to-origin/SKILL.md
+++ b/origin-apps/skills/port-github-app-to-origin/SKILL.md
@@ -42,24 +42,24 @@ section.
2. **Discover** per `references/discovery.md`, 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 capability (`references/spec-mapping.md`) and label it with
- the parity labels in the brief template. Map the payload fields the code
- reads, not only the event names; if a payload lacks a field the REST
- resource has, a follow-up read is the usual answer (`#event-payloads`).
- Check `references/origin-isms.md` before labeling `gap`, and
- `references/gap-bar.md` before writing feedback. A capability the Origin
- docs do not mention is `unknown` with a question. A behavior the docs
- neither confirm nor deny becomes a question plus a hello-world step that
- observes it, rather than an assumption carried over from the app's
- current platform.
-4. **Write the brief** from the template. Every Origin cell names an
- `operationId`, a slug, or an `llms-full.txt` anchor. Sizes are S, M, or L,
- not time.
-5. **Self-check** before finishing: every Origin cell resolves in the fetched
- files; every `gap` row has a feedback entry that names a tradeoff from
- `gap-bar.md`; every `not-available` and `unknown` row has a question; the
- Feedback section contains nothing that reveals the team's internals; the
- first question is native or mirror.
+3. **Map** each capability (`references/spec-mapping.md`). Map the payload
+ fields the code reads, not only the event names; if a payload lacks a
+ field the REST resource has, a follow-up read is the usual answer
+ (`#event-payloads`). Check `references/origin-isms.md` before calling
+ anything a gap, and `references/gap-bar.md` before writing feedback. A
+ capability the Origin docs do not mention is not available today and gets
+ a question. A behavior the docs neither confirm nor deny becomes a
+ question plus a first-run step that observes it, rather than an assumption
+ carried over from the app's current platform.
+4. **Write the brief** per `references/brief-template.md`: guidance and a
+ default 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
+ Feedback section to `ORIGIN-FEEDBACK.md` beside the brief.
+5. **Self-check** before finishing: every Origin claim resolves in the
+ fetched files; every gap has a feedback entry that names a tradeoff from
+ `gap-bar.md`; the Feedback section and `ORIGIN-FEEDBACK.md` contain nothing
+ that reveals the team's internals; the summary names the native-or-mirror
+ question.
## Not in scope
@@ -76,4 +76,4 @@ Cursor yourself; the brief carries it and the team sends it.
| `references/spec-mapping.md` | Building the index. Matching calls, events, and fields. |
| `references/origin-isms.md` | Labeling a capability that maps differently. |
| `references/gap-bar.md` | Deciding what is feedback for Cursor, and writing the entry. |
-| `references/brief-template.md` | Writing the output. |
+| `references/brief-template.md` | Writing the brief and the feedback file. |
diff --git a/origin-apps/skills/port-github-app-to-origin/references/brief-template.md b/origin-apps/skills/port-github-app-to-origin/references/brief-template.md
index d17796ac..8061f723 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,158 +1,79 @@
-# Porting brief template
-
-Contents: [Labels](#labels) (parity, size) and [Template](#template)
-(provenance, §§ 1-8).
-
-A default shape; adapt it to the app. Write one Markdown file at the
-repository root (`ORIGIN-PORTING-BRIEF.md` unless the team's docs convention
-says otherwise) and print its path. Cite spec `operationId`s and
-`llms-full.txt` anchors. Sections 1 to 5 and 7 are for the team and may cite
-their code by `file:line`. Section 6 is for Cursor and must not reveal the
-team's internals; its format is the part to keep exact.
-
-## Labels
-
-**Parity**
-
-| 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). 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. |
-| `not-available` | Nothing in the current spec covers it (`origin-isms.md` or `#current-limitations`). Names the closest idiom and has a question in § 7; eligible for a feedback entry. |
-| `gap` | No workaround, or one whose tradeoff meets a test in `gap-bar.md`. Has a feedback entry in § 6. |
-| `unknown` | Discovery or the spec could not answer. Has a question in § 7. |
-| `preview` (suffix) | The row touches an element badged `x-cursor-visibility: PREVIEW` (`llms-full.txt#preview`). |
-
-**Size** (kind of change, not time)
-
-| Size | Meaning |
-| --- | --- |
-| 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 feedback entry. |
-
-## Template
-
-```markdown
-# Origin porting brief for <app name>
-
-Planning document. Maps what this app uses today onto the Cursor Origin API
-as published on <date>. It makes no decisions about language, framework, or
-client.
-
-## Provenance
-
-- Origin OpenAPI `info.version`: `<value>`, fetched <timestamp>
-- Docs read: <the URLs>
-- Codebase: `<repo>` at `<commit>`
-- Re-check `workaround` and `gap` rows against the changelog before work
- starts. They are the rows most likely to have moved.
-
-## 1. What the app is today
-
-One paragraph on what it does for its users, which events drive it, and what
-it writes back. Then:
-
-| Facet | Finding | Evidence |
-| --- | --- | --- |
-| 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, scheme, raw-body availability, dedupe | `file:line` |
-| Git as the app | clone / push / none | `file:line` |
-| Observed language and libraries | … | |
-| Looked for, not found | … | |
-
-## 2. First decision: which repositories
-
-<What the code assumes about the repositories it acts on.> What an
-installation can do on a mirrored repository is defined in
-`llms-full.txt#mirrored-repositories` and `#events`. Answer question 1 before
-attempting § 5.
-
-## 3. Capability table
-
-One row per capability the code uses today, grouped by facet (authentication,
-installation and discovery, configuration, repositories and contents, pull
-requests, reviews and comments, checks, webhook events, webhook receiver,
-git). Include rows for calls a dependency makes on the app's behalf, marked as
-such.
-
-| Capability today (evidence) | Origin equivalent | Parity | Size | Tradeoff | Open question |
-| --- | --- | --- | --- | --- | --- |
-| `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 feedback entry.
-`not-available` rows name the closest idiom and their question. `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 the scopes
-`llms-full.txt#scopes` says are automatic or implied.
-
-## 4. Webhook payload fields the code reads
-
-| Event (today → Origin) | Field read today | Origin | How |
-| --- | --- | --- | --- |
-| `<event.action>` → `<slug>` | `<field path>` | present | `payload.pullRequest.head.sha` |
-| `<event>` → `<slug>` | `<field path>` | follow-up read | `<operationId>`, one call per ref update |
-
-"How" is one of five values. Present at `<path>`. Present in the envelope
-(`event.type` carries the 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
-
-The shortest route to one real event from one native repository. The
-mechanics are in `llms-full.txt#implementation-checklist` and the sections it
-links; this list is the observations to make, in order. Append one step for
-each spec-silent behavior the brief depends on.
-
-1. App created, signing key registered, webhook URL and callback set.
-2. Every repository event from § 3 selected in app settings.
-3. Installed on an Origin-native repository; receipt verified; installation
- ID recorded.
-4. Installation token minted; the repository appears in the installation's
- repositories with the mirror state § 2 expects.
-5. Ping received and verified; a retried delivery is deduplicated.
-6. Smallest action in § 3 performed; the expected slug and the § 4 fields
- arrive. If the ping arrived and this did not, re-check steps 2 and 3
- first.
-7. Smallest write from § 3 succeeds with the scopes from the § 3 line.
-
-## 6. Feedback for Cursor
-
-Capabilities Origin should add, one entry per `gap` row in the `gap-bar.md`
-format: use case and API gap, in Origin terms, with nothing that reveals the
-team's internals. If none, write "No row met the feedback bar; the
-workarounds in § 3 carry their tradeoffs."
-
-## 7. Questions for the team
-
-Decisions the team must make before the port, not asks of Cursor. Always the
-first three, then what discovery left open.
-
-1. Native repositories (or stable outbound mirrors), or repositories in
- another mirror state? 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 pull
- request version?
-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 scope
-
-No implementation, no SDK or language choice, no time estimates. The brief is
-a map. The route is the team's.
+# The porting brief
+
+The brief is for the team that owns the app, plus one section they can send
+to Cursor as is. Write it as one Markdown file at the repository root
+(`ORIGIN-PORTING-BRIEF.md` unless the team's docs convention says otherwise)
+and print its path. A small app's brief fits on one screen; parts that have
+nothing to say collapse to a line or disappear. Choose table shapes and
+headings to fit the app.
+
+## What a good brief does
+
+- **Leads with a summary.** Three to five lines: the verdict (ports as is,
+ ports with N workarounds, blocked on X), the one question that decides the
+ rest (usually native or mirror), and whether there is feedback for Cursor
+ and 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
+ note that nothing does. Where a webhook handler reads specific payload
+ fields, say per field whether it is present, comes from the envelope, needs
+ a 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: the
+ union of `x-origin-scopes.scopes` over the operations named, minus what
+ `#scopes` says is automatic or implied.
+- **Gives an app-specific first-run path when it helps.** The events to
+ select by slug, the mirror-state check, the first event that should arrive
+ and 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
+ with one event.
+- **Adds plan notes.** What drives the size of the port (a few bullets, no
+ time estimates) and how to roll it out: dual-run or cutover, what a mirror
+ trial can and cannot show, what to gate.
+- **Asks only what the team must decide.** Repository set, tolerable event
+ volume and follow-up reads, what replaces a flow that has no Origin
+ equivalent. Do not restate a row as a question.
+- **Ends with two lines of provenance.** Spec `info.version` and fetch time;
+ codebase and commit.
+- **Closes with Feedback for Cursor.** Last section, unnumbered, written to be
+ copied verbatim (`gap-bar.md` has the shape). Nothing in it reveals the
+ team's internals. When it has at least one entry, also write it to
+ `ORIGIN-FEEDBACK.md` beside the brief. When nothing meets the bar, no file;
+ one line in the brief saying so.
+
+## What makes it trustworthy
+
+- 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
+ memory.
+- Behavior the docs do not state is a question plus a first-run step that
+ observes it, never an assumption.
+- Feedback for Cursor describes use cases and the API gap in Origin terms,
+ with no file paths, module names, framework internals, or repository names.
+
+## Vocabulary, if you want one
+
+Plain notes serve the reader as well as labels. If the table needs a compact
+mark, these four are shared with the other references: `maps` (a documented
+path exists, same or reshaped), `workaround` (same outcome by another route;
+say the tradeoff), `not-available` (nothing in the current spec; carries a
+question), `gap` (no workaround, or one whose tradeoff meets a test in
+`gap-bar.md`; produces a feedback entry). Size marks S/M/L, if used, mean
+adapter change, new code path, product or architecture change.
+
+## Default outline
+
+Adapt or skip parts; the Feedback section is the one to keep exact.
+
+```text
+# Origin porting brief: <app>
+Summary
+1. The app today one paragraph; observed stack; looked for, not found
+2. Capability map table(s); payload fields under webhook events; scopes line
+3. First run app-specific, five steps or fewer (optional)
+4. Plan notes size drivers; rollout (optional)
+5. Questions for the team
+Provenance two lines
+Feedback for Cursor unnumbered, last, copy verbatim; also ORIGIN-FEEDBACK.md
```
diff --git a/origin-apps/skills/port-github-app-to-origin/references/discovery.md b/origin-apps/skills/port-github-app-to-origin/references/discovery.md
index bc408bc8..f9c86ab0 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
@@ -50,5 +50,5 @@ Seven facets. For each, what to record:
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
+Each missing item becomes an up-front question. Do not
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.md
index 16c0d7b2..e14f6876 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
@@ -7,13 +7,16 @@ for Cursor (a capability Origin should add) and questions for the team
(decisions the team must make); it does not decide whether to speak up. It
also orders feedback so the items that block the port are read first.
-- A difference is any row whose parity label is not `same`.
+- A difference is any capability whose Origin path is not a straight
+ substitution.
- A workaround reaches the same outcome with the current 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 `workaround` row with its
- tradeoff is often the right answer.
+ client-side filter, a marker the app controls. Noting the workaround with
+ its tradeoff is often the right answer.
- A gap is a difference with no workaround, or a workaround whose tradeoff
- meets one of the tests below. Gaps become feedback entries.
+ meets one of the tests below. Gaps become feedback entries; when there is
+ at least one, the Feedback section is also written to `ORIGIN-FEEDBACK.md`
+ beside the brief.
## Tradeoffs that make a workaround insufficient
@@ -27,14 +30,14 @@ also orders feedback so the items that block the port are read first.
## Usually a workaround or a question
-- Anything `origin-isms.md` labels `reshaped`: a documented path exists.
+- Anything `origin-isms.md` marks `maps`: a documented path exists.
- A field or filter the code does not use.
- A convention difference (pagination style, identifier form, URL fields)
where the Origin convention is a mechanical substitution.
- Anything the changelog says shipped or the spec already carries. Re-read
the live spec before writing feedback.
-- A capability the Origin docs do not mention: `not-available` or `unknown`
- with a question. The team should still ask if they need it.
+- A capability the Origin docs do not mention: not available today, with a
+ question. The team should still ask if they need it.
- A query the app runs against a search API, when the spec has no search
operation for that resource. A list operation with its filters plus a
client-side predicate is the idiom; if that fails the fan-out test, the
@@ -48,8 +51,9 @@ about the event.
## The feedback format
-One entry per gap, in the brief's "Feedback for Cursor" section. Describe the
-use case and the API gap relative to it, in Origin terms. No file paths,
+One entry per gap, in the brief's "Feedback for Cursor" section. A suggested
+shape, not a form; keep whatever lines carry information. Describe the use
+case and the API gap relative to it, in Origin terms. No file paths,
module names, framework internals, code structure, or repository names; those
belong in the team-facing sections of the brief.
diff --git a/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md b/origin-apps/skills/port-github-app-to-origin/references/origin-isms.md
index 31329c29..90304a1f 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,41 +1,41 @@
# Origin-isms: GitHub features that map differently on Origin
-Check here before labeling anything `gap`. Each row names the label to use
-and where the Origin answer lives today (an anchor in `llms-full.txt` unless
-noted). `reshaped` rows have a documented path, so they get a question if
-the team wants the GitHub shape back rather than a feedback entry.
-`not-available` rows get a question, and a feedback entry if they meet the
-bar.
-Read the source; do not copy this table into the brief.
+Check here before calling anything a gap. Each row says whether a documented
+Origin 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
+wants the old shape back. A `not-available` row is a question, and feedback
+if it meets the bar in `gap-bar.md`. Read the source; do not copy this table
+into the brief.
-| GitHub call, event, or permission | Label | Where the Origin answer lives |
+| What the app uses today | Mark | Where the Origin answer lives |
| --- | --- | --- |
-| Writes or `push` events on a repository mirrored from GitHub | `reshaped` | 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`) | `reshaped` | `#installation-receipt` |
-| RS256 app JWT | `reshaped` | `#app-jwt` |
-| Long-lived installation tokens | `reshaped` | `#installation-access-token` |
+| 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` | `reshaped` | `#scopes`; `x-origin-scopes` per operation |
-| Numeric IDs, `/repositories/{id}` | `reshaped` | `#ids`, `#repository-paths` |
-| `Link` / `page` / `per_page` pagination, total counts | `reshaped` | `#pagination` |
+| 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` |
| 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}`) | `reshaped` | `#check-runs` (check runs with a stable `key`) |
+| Commit statuses (`statuses` permission, `POST /statuses/{sha}`) | `maps` | `#check-runs` (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 | `reshaped` | Pull requests endpoint reference; same calls under `/pulls/{n}/…` |
-| Repository webhook CRUD (`/repos/…/hooks`) | `reshaped` | Subscriptions are set per app through Create App / Update App `events` (`#events`). |
-| App-manifest conversion | `reshaped` | App creation form or `CreateApp` (`#installation`, endpoint reference) |
+| `/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) |
| OAuth-app token mints | `not-available` | Nothing in the current spec. Ask what the flow was for. |
-| Git Data API commit and ref writes | `reshaped` | 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); `#git-https-authentication` 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 | `reshaped` | A thread comes from its first diff-anchored comment (Pull requests endpoint reference); thread listing is under `#current-limitations`. |
+| 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` | `reshaped` | `#events`, `#event-payloads` |
-| `x-github-*` headers, HMAC `x-hub-signature-256` | `reshaped` | `#headers`, `#signature-verification` |
-| Payload inlines (changed files on push, before-SHA, `html_url`, `sender` profile) | `reshaped` | `#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 | `reshaped` | `#events` |
-| Reviews keyed by `commit_id` | `reshaped` | `pullRequestVersion` on the review schema |
-| Finding own check runs or comments by actor | `reshaped` | `#check-runs` (`key`); comments and reviews by a marker the app controls |
+| 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` |
+| 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 |
| 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 feature that is not on this list and that the Origin docs do not mention
-is `unknown` with a question.
+A capability that is not on this list and that the Origin docs do not
+mention is not available today; ask the team whether they need it.
diff --git a/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md b/origin-apps/skills/port-github-app-to-origin/references/spec-mapping.md
index f043a6c7..54c45634 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
@@ -9,7 +9,7 @@ table here. Build the index once. Every later step looks things up in it.
| --- | --- | --- |
| `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`. Carry it into the brief as a `preview` suffix on any row that touches a badged element. |
+| `x-cursor-visibility: PREVIEW` | operations, parameters, schemas, fields | `#preview`. Note it in the brief on any capability that touches a badged element. |
## Build the index
@@ -54,7 +54,7 @@ match is a candidate, not a result.
`/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`.
+ the code depends on is a workaround or a gap, not a straight match.
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.
@@ -86,10 +86,10 @@ event.
## Out of domain and spec-silent
-- A concept neither the spec nor `llms-full.txt` mentions is `unknown`
- with an up-front question rather than `gap`: there is no Origin answer yet
+- A concept neither the spec nor `llms-full.txt` mentions is not available
+ today and gets a question rather than a gap: there is no Origin answer yet
to compare against, and the question is how the team tells Cursor they
- need it. Use `not-available` only for `origin-isms.md` rows.
+ need it.
- A behavior the code depends on that the docs do not state (does an event
fire for a draft pull request? does `updatedAt` move on a comment?) becomes an open
question plus a hello-world step that observes it on a native repository.