@@ -0,0 +1,12 @@
+---
+'@objectstack/skills': patch
+---
+
+docs(skills): objectstack-automation teaches `oauth2` and `app-credential` as a served recipe now that the built-in connector providers run the grant
+
+Clause-②: no
+Metadata-protocol: none
+
+- **Before.** `references/integration-recipes.md` filed the OAuth-protected vendor under "Not yet": `auth` could declare `oauth2` and `app-credential`, but "no server runs the grant yet", so the integration was to be marked blocked. Eval 1 (DocuSign) graded that answer, and `SKILL.md` listed OAuth among the documents the loader cannot take.
+- **Now.** The built-in `rest`, `openapi` and `mcp` providers ask the per-dispatch credential handle, so both kinds are served. Recipe 6 teaches the three `auth` shapes (`authorization_code`, `client_credentials`, `app-credential` with `feishu` / `dingtalk` / `wecom`), where the token is held, that `client_credentials` and `app-credential` dispatch once the ref is set, and how an administrator holding `manage_connector_connections` connects an `authorization_code` instance once per organization (`POST /api/v1/automation/connectors/:name/connection`, the vendor's redirect to the callback, status, revoke). The warning against parking a short-lived token behind a `bearer` ref stays. Eval 1 now expects that recipe and names one remaining gap (the vendor-signed webhook); `SKILL.md`'s loader-gap line no longer names OAuth. WeChat Pay stays under "Not yet" (no `signed` scheme).
+- The file's token ceiling moves to the measured count after two same-file restatement cuts; no schema, key or behaviour changes.
@@ -0,0 +1,10 @@
+---
+'@objectstack/lint': patch
+---
+
+fix(lint): the `flow-credential-literal` explanation says the built-in providers run an `oauth2` / `app-credential` grant
+
+Clause-②: no (lint advice is not a contract face; no accepted metadata shape moves)
+Metadata-protocol: none
+
+The `os explain` entry for `flow-credential-literal` said a grant-bearing instance is held degraded "until it runs that grant". The built-in `rest`, `openapi` and `mcp` providers now ask the per-dispatch credential handle, so an `oauth2` or `app-credential` instance on them is served (an `authorization_code` instance once an administrator connects it). The sentence now says so, and keeps the degraded case for a provider that does not ask the handle. No rule verdict, `fix:` line or hint changes.
@@ -4710,8 +4710,10 @@ const FLOW_CREDENTIAL_LITERAL_EXPLANATION: RuleExplanation = {
       '`api-key` with `paramName`. The schema\'s other kinds also take their secret only as a ' +
       '`credentialRef`, but none is a home a literal moves into by shape: `oauth2` (grant ' +
       '`authorization_code` or `client_credentials`) and `app-credential` (vendor `feishu`, ' +
-      '`dingtalk` or `wecom`) carry a grant whose token the server obtains per dispatch, and until it ' +
-      'runs that grant such an instance is held degraded and calls no upstream; `signed` signs each ' +
+      '`dingtalk` or `wecom`) carry a grant whose token the server obtains per dispatch through the ' +
+      'built-in `rest`, `openapi` and `mcp` providers (an `authorization_code` instance once an ' +
+      'administrator connects it); on a provider that does not ask the credential handle such an ' +
+      'instance is held degraded and calls no upstream; `signed` signs each ' +
       'request with its key. A credential in `connectorConfig.input` is dropped instead, ' +
       'because the connector authenticates through its own `auth`. No variant carries a secret in a ' +
       'url path, so a url path is not judged and no fix line promises one.',
 
@@ -486,7 +486,11 @@ export const CEILINGS = new Map([
   // three pointer lines' "Moved to", and five clause-level trims. Arithmetic in
   // priced bytes: 25860 -> 25827 (-33 net) -> ceil(25827 / 4) = 6457; re-locked
   // AT the measurement, headroom 0 tokens.
-  ['skills/objectstack-automation/SKILL.md', 6457],
+  // 6457 -> 6450 (card #28299): the loader-gap line no longer names OAuth or
+  // request signing, which the built-in providers serve (recipe 6 and the
+  // `signed` kind in references/integration-recipes.md). Re-locked AT the
+  // measurement, headroom 0 tokens.
+  ['skills/objectstack-automation/SKILL.md', 6450],
   // 13783 -> 13892 (2026-08-31 app-repo-principles raise, see the block above).
   // The invariant-vs-transition-gate choice, placed in the field-conditional-rule
   // bullet list where the tool is actually picked. Both wrong picks are silent:
@@ -931,7 +935,29 @@ export const CEILINGS = new Map([
   // and untranslated: 「A:先削重复,余额按实测提高」 — the standing path of
   // ruling record 6513306068 on #27847.
   //   ceil($(wc -c < skills/objectstack-automation/references/integration-recipes.md) / 4) == ceil(8942 / 4)
-  ['skills/objectstack-automation/references/integration-recipes.md', 2236],
+  // 8938 -> 10089 (card #28299; the file had shrunk 4 bytes under the row
+  // since, headroom 1 token): the "Not yet" OAuth bullet becomes recipe 6 —
+  // `oauth2` / `app-credential` are served on `rest`, `openapi` and `mcp` now
+  // that the built-in providers ask the credential handle: the three `auth`
+  // shapes, the per-organization connect (`POST …/connectors/:name/connection`,
+  // the callback, status, revoke) and the kept `bearer`-ref warning. Paid down
+  // first, two restatements each with a surviving home: recipe 3's agent
+  // exposure example (its pointer to objectstack-ai § Actions as AI Tools
+  // stays, and that skill teaches the shape), and recipe 5's "Each
+  // `operationId` is a named action in the flow palette and to agents" (the
+  // Holds bullet says actions come from the upstream's `operationId`s).
+  // Arithmetic after the contract-review patch round (the vendor token
+  // placements, the token lifecycle clause and the status triple restated
+  // the connectors page and are gone; the Holds `auth` bullet points at
+  // recipe 6; the delta round restored the three `vendor` values in the
+  // app-credential comment): 8938 -> 9949 (+1011 net: -308 cut, +1319 added) ->
+  // ceil(9949 / 4) = 2488; the ceiling moves +252, pinned AT the
+  // measurement. Maintainer ruling 2026-10-27 on the seat's decision card
+  // 「skills 修复卡的教学和 eval 都撞 token 天花板,怎么付?」, tap A verbatim
+  // and untranslated: 「A:先削重复,余额按实测提高」 — the standing path of
+  // ruling record 6513306068 on #27847.
+  //   ceil($(wc -c < skills/objectstack-automation/references/integration-recipes.md) / 4) == ceil(9949 / 4)
+  ['skills/objectstack-automation/references/integration-recipes.md', 2488],
   // 5569 -> 5587 (card #26298, audit #26184 row A2): the approval config table
   // gains `excludeSubmitter` (refused beside `onEmptyApprovers: 'auto_approve'`),
   // +105 tokens. Paid down first: Best Practices 1 and 4 restated the Branching
 
@@ -413,7 +413,7 @@ card, the app still writing none: the protocol is not HTTP; the work writes
 identity objects (users, units, positions); it processes files locally; one fixed
 action contract spans several vendors; the callback's signature is outside the
 `api` door's HMAC. A document the loader cannot take yet (YAML, Swagger 2.0,
-`$ref`, OAuth, request signing) is a gap named against its platform card, never a
+`$ref`) is a gap named against its platform card, never a
 reason to write code.
 
 ---
 
@@ -4,11 +4,11 @@
     {
       "id": 1,
       "prompt": "Our contract-lifecycle app (objects `contract`, `crm_account`) needs DocuSign: send a contract out for signature, read an envelope's status, and reflect status changes on the record. DocuSign publishes a 4.7 MB Swagger 2.0 document with several hundred operations, authenticates with OAuth 2.0, and its Connect webhooks sign posts with their own HMAC header. Propose what to build and where.",
-      "expected_output": "A declarative instance inside the app, not a platform plugin and not a `connector-esign` family: `defineConnector` with `provider: 'openapi'`, whose `providerConfig.spec` is a packaged OpenAPI 3.x document converted offline from the Swagger 2.0 document and trimmed to the three operations (create envelope, get envelope, list status changes) (or `providerConfig.include` names those three operation keys, the `mcp` provider's allowlist meaning, where a non-array or unknown entry is fatal). Fields on `contract` (`envelope_id`, `signature_status`). Flows dispatch `connector_action`; the callback is an `api` flow with a start-node `secretRef`. Two gaps are named plainly, each blocked on its platform card: the declarative `auth` union declares `oauth2` (`grant: 'authorization_code'`, the client secret only a `credentialRef`), but no server runs the grant yet, so such an instance is held degraded and calls no upstream: the integration is marked **blocked** on outbound OAuth (no short-lived token parked behind a `bearer` `credentialRef`); DocuSign Connect signs its own header, which the `api` door does not verify, so status is polled until vendor schemes are verified. `connectorConfig.input` is a value slot: the per-contract payload reads the record through a CEL envelope (`envelopeId: { dialect: 'cel', source: 'record.envelope_id' }`), judged against the action's `inputSchema` before dispatch. The answer proposes no `registerConnector` code and no plugin.",
+      "expected_output": "A declarative instance inside the app, not a platform plugin and not a `connector-esign` family: `defineConnector` with `provider: 'openapi'`, whose `providerConfig.spec` is a packaged OpenAPI 3.x document converted offline from the Swagger 2.0 document and trimmed to the three operations (create envelope, get envelope, list status changes) (or `providerConfig.include` names those three operation keys, the `mcp` provider's allowlist meaning, where a non-array or unknown entry is fatal). Fields on `contract` (`envelope_id`, `signature_status`). Flows dispatch `connector_action`; the callback is an `api` flow with a start-node `secretRef`. `auth` is `{ type: 'oauth2', grant: 'authorization_code', authorizationUrl, tokenUrl, scopes, clientId, credentialRef }`, the client secret only a `credentialRef` (no inline `clientSecret`, no short-lived token parked behind a `bearer` `credentialRef`): the built-in `openapi` provider obtains and refreshes the token per dispatch, and the instance stays degraded \"not connected\" until an administrator holding `manage_connector_connections` connects it once per organization (`POST /api/v1/automation/connectors/docusign/connection`, then the vendor's redirect to `GET …/connectors/oauth/callback`; `DELETE` revokes). One gap is named plainly: DocuSign Connect signs its own header, which the `api` door does not verify, so status is polled until vendor schemes are verified. `connectorConfig.input` is a value slot: the per-contract payload reads the record through a CEL envelope (`envelopeId: { dialect: 'cel', source: 'record.envelope_id' }`), judged against the action's `inputSchema` before dispatch. The answer proposes no `registerConnector` code and no plugin.",
       "files": [],
       "assertions": {
-        "must_contain": ["defineConnector", "provider: 'openapi'", "credentialRef", "connector_action", "type: 'api'", "secretRef", "Swagger 2.0", "blocked"],
-        "must_not_contain": ["registerConnector(", "connector-esign", "provider: 'docusign'", "implements Plugin", "clientSecret:", "token:"]
+        "must_contain": ["defineConnector", "provider: 'openapi'", "credentialRef", "connector_action", "type: 'api'", "secretRef", "Swagger 2.0", "oauth2", "authorization_code", "/connection"],
+        "must_not_contain": ["registerConnector(", "connector-esign", "provider: 'docusign'", "implements Plugin", "clientSecret:", "token:", "blocked on outbound OAuth"]
       }
     },
     {
 
@@ -31,7 +31,7 @@ deployment and to the sender. Scaffolded apps list the three executors in
   default `X-API-Key`, or `paramName` for a query-string key); `basic` (`username`
   stays in metadata); `signed` on `openapi` / `rest` (`scheme`
   `aliyun-acs3-hmac-sha256`, `tencentcloud-tc3-hmac-sha256` or `alipay-v3`,
-  `keyId`) signs each request. A secret in a url path has no variant — use a
+  `keyId`) signs each request; `oauth2` / `app-credential`: recipe 6. A secret in a url path has no variant — use a
   token-authenticated connector. `authentication: { token }` is refused at `os validate`.
 - `defineConnector`: `@objectstack/spec/integration`; `defineFlow`: `@objectstack/spec`; both register in `defineStack`.
 
@@ -99,9 +99,7 @@ export const WarehouseApi = defineConnector({
 // connector_action { connectorId: 'warehouse_api', actionId: 'request',
 //   input: { method: 'GET', path: '/v1/stock/low' } } → create_record `stock_alert`
 //   fields: { lines: { dialect: 'cel', source: 'low.body' } }.
-// Optional — let an agent run the sweep on request (objectstack-ai § Actions as AI Tools):
-// { name: 'refresh_low_stock', label: 'Refresh low stock', type: 'flow', target: 'low_stock_sweep',
-//   ai: { exposed: true, description: 'Pull the current low-stock lines from the warehouse API into stock_alert rows.' } }
+// To let an agent run the sweep on request: objectstack-ai § Actions as AI Tools.
 ```
 
 ## 4 · Vendor callback — an `api` flow with `secretRef`
@@ -144,15 +142,35 @@ export const LegacyErp = defineConnector({
 // connector_action { connectorId: 'legacy_erp', actionId: 'listOpenOrders', input: {} }
 ```
 
-Each `operationId` is a named action in the flow palette and to agents;
 `provider: 'rest'` instead when the path is per call.
 
-## Not yet — declare the rest, mark the integration blocked, write no plugin
+## 6 · OAuth or vendor-app token — the server runs the grant
+
+Recipe 1's shape with a grant-bearing `auth`, served on `rest`, `openapi` and
+`mcp` (`http` only; a `stdio` server's credentials ride `transport.env`): the
+token is fetched per dispatch; no metadata key holds it.
+
+```ts
+// A user grants access once (PKCE always on); the ref is the client secret, omitted for a public client.
+auth: { type: 'oauth2', grant: 'authorization_code', authorizationUrl: 'https://account.docusign.com/oauth/auth',
+        tokenUrl: 'https://account.docusign.com/oauth/token', scopes: ['signature'],
+        clientId: 'objectstack-prod', credentialRef: 'DOCUSIGN_CLIENT_SECRET' }
+// Server to server: grant: 'client_credentials' with tokenUrl, clientId, credentialRef (`resource` optional).
+// Vendor app id + app secret (`vendor`: `feishu` / `dingtalk` / `wecom`):
+auth: { type: 'app-credential', vendor: 'feishu', appId: 'cli_a1b2', credentialRef: 'FEISHU_APP_SECRET' }
+```
+
+`client_credentials` and `app-credential` dispatch once the ref is set.
+`authorization_code` is degraded "not connected" until an administrator holding
+`manage_connector_connections` (organization admins by default) connects it,
+once per organization, from a signed-in session (an agent or API key is refused):
+`POST /api/v1/automation/connectors/:name/connection` answers `{ authorizationUrl }`
+for the admin to open; the vendor redirects to `GET …/connectors/oauth/callback`.
+`GET` reads the status; `DELETE` revokes. Endpoints are `https://`; an
+`authorization_code` instance on `mcp` may omit them and `clientId`, discovered at connect.
+Still never park a short-lived token behind a `bearer` ref.
+
+## Not yet — mark the integration blocked, write no plugin
 
-- **OAuth-protected vendor** (DocuSign, Salesforce, Google): `auth` declares
-  `oauth2` (`authorization_code` / `client_credentials`) and `app-credential`
-  (`feishu` / `dingtalk` / `wecom`), but no server runs the grant yet: the
-  instance is held degraded, calling no upstream. Do not park a short-lived
-  token behind a `bearer` ref. Blocked on the outbound-OAuth card.
 - **WeChat Pay**: no `signed` scheme yet (Alipay's is `alipay-v3`, which also
   verifies responses).
Original file line number	Diff line number	Diff line change
`@@ -4,11 +4,11 @@`
`4`	`4`	`{`
`5`	`5`	`"id": 1,`
`6`	`6`	"prompt": "Our contract-lifecycle app (objects `contract`, `crm_account`) needs DocuSign: send a contract out for signature, read an envelope's status, and reflect status changes on the record. DocuSign publishes a 4.7 MB Swagger 2.0 document with several hundred operations, authenticates with OAuth 2.0, and its Connect webhooks sign posts with their own HMAC header. Propose what to build and where.",
`7`		- "expected_output": "A declarative instance inside the app, not a platform plugin and not a `connector-esign` family: `defineConnector` with `provider: 'openapi'`, whose `providerConfig.spec` is a packaged OpenAPI 3.x document converted offline from the Swagger 2.0 document and trimmed to the three operations (create envelope, get envelope, list status changes) (or `providerConfig.include` names those three operation keys, the `mcp` provider's allowlist meaning, where a non-array or unknown entry is fatal). Fields on `contract` (`envelope_id`, `signature_status`). Flows dispatch `connector_action`; the callback is an `api` flow with a start-node `secretRef`. Two gaps are named plainly, each blocked on its platform card: the declarative `auth` union declares `oauth2` (`grant: 'authorization_code'`, the client secret only a `credentialRef`), but no server runs the grant yet, so such an instance is held degraded and calls no upstream: the integration is marked blocked on outbound OAuth (no short-lived token parked behind a `bearer` `credentialRef`); DocuSign Connect signs its own header, which the `api` door does not verify, so status is polled until vendor schemes are verified. `connectorConfig.input` is a value slot: the per-contract payload reads the record through a CEL envelope (`envelopeId: { dialect: 'cel', source: 'record.envelope_id' }`), judged against the action's `inputSchema` before dispatch. The answer proposes no `registerConnector` code and no plugin.",
	`7`	+ "expected_output": "A declarative instance inside the app, not a platform plugin and not a `connector-esign` family: `defineConnector` with `provider: 'openapi'`, whose `providerConfig.spec` is a packaged OpenAPI 3.x document converted offline from the Swagger 2.0 document and trimmed to the three operations (create envelope, get envelope, list status changes) (or `providerConfig.include` names those three operation keys, the `mcp` provider's allowlist meaning, where a non-array or unknown entry is fatal). Fields on `contract` (`envelope_id`, `signature_status`). Flows dispatch `connector_action`; the callback is an `api` flow with a start-node `secretRef`. `auth` is `{ type: 'oauth2', grant: 'authorization_code', authorizationUrl, tokenUrl, scopes, clientId, credentialRef }`, the client secret only a `credentialRef` (no inline `clientSecret`, no short-lived token parked behind a `bearer` `credentialRef`): the built-in `openapi` provider obtains and refreshes the token per dispatch, and the instance stays degraded \"not connected\" until an administrator holding `manage_connector_connections` connects it once per organization (`POST /api/v1/automation/connectors/docusign/connection`, then the vendor's redirect to `GET …/connectors/oauth/callback`; `DELETE` revokes). One gap is named plainly: DocuSign Connect signs its own header, which the `api` door does not verify, so status is polled until vendor schemes are verified. `connectorConfig.input` is a value slot: the per-contract payload reads the record through a CEL envelope (`envelopeId: { dialect: 'cel', source: 'record.envelope_id' }`), judged against the action's `inputSchema` before dispatch. The answer proposes no `registerConnector` code and no plugin.",
`8`	`8`	`"files": [],`
`9`	`9`	`"assertions": {`
`10`		`- "must_contain": ["defineConnector", "provider: 'openapi'", "credentialRef", "connector_action", "type: 'api'", "secretRef", "Swagger 2.0", "blocked"],`
`11`		`- "must_not_contain": ["registerConnector(", "connector-esign", "provider: 'docusign'", "implements Plugin", "clientSecret:", "token:"]`
	`10`	`+ "must_contain": ["defineConnector", "provider: 'openapi'", "credentialRef", "connector_action", "type: 'api'", "secretRef", "Swagger 2.0", "oauth2", "authorization_code", "/connection"],`
	`11`	`+ "must_not_contain": ["registerConnector(", "connector-esign", "provider: 'docusign'", "implements Plugin", "clientSecret:", "token:", "blocked on outbound OAuth"]`
`12`	`12`	`}`
`13`	`13`	`},`
`14`	`14`	`{`