@apifuse/provider-sdk 2.1.0-beta.2 → 2.1.0-beta.20

package/AUTHORING.md

@@ -1,7 +1,7 @@
 ## Generator and runtime alignment
 
 - Canonical scaffolding command: `apifuse create`
-- Monorepo contributors should use `apifuse create <name> --preset monorepo`
+- External bounty workspaces are one-provider repositories initialized with the standalone create flow. `--preset monorepo` is an internal APIFuse maintainer path only and must reject outside the private monorepo detected by `packages/provider-sdk/package.json`.
 - Standalone bounty contributors should use `bunx @apifuse/provider-sdk@beta create <name> --yes` until this release is promoted to `latest`
 - Provider server contract is:
   - dev default `3900`
@@ -47,12 +47,36 @@ description:
 - `description` — 150+ chars English (error-level rule)
 - Every Zod field in input AND output has `.describe()` including nested objects + array items (error-level rule)
 - `fixtures.request` + `fixtures.response` both present (error-level rule)
-- Exactly one of `healthCheck` or `healthCheckUnsupported` per operation. Prefer `healthCheck` for safe read-only upstream probes; use `healthCheckUnsupported` only with a specific reason for destructive, paid, credential-sensitive, flaky, or otherwise unsafe probes.
+- Exactly one of `healthCheck`, `healthCheckUnsupported`, or `healthJourneys[].coversOperations` coverage per operation. Prefer `healthCheck` for safe read-only upstream probes; use `healthCheckUnsupported` only with a specific reason for destructive, paid, credential-sensitive, flaky, or otherwise unsafe probes. Use a provider-level health journey when a destructive or credential-sensitive flow can be proven safely only as a multi-step boundary test, such as stopping at a payment WebView URL.
 
 ### Factored operations
 
 Use `defineOperation()` when an operation is large enough to live beside helper functions or in a separate module. It preserves the same type inference as inline `defineProvider()` operations and can be placed directly in the provider `operations` map. `defineProvider()` accepts Zod and Standard Schema v1-compatible schemas. If config validation fails, the SDK names the field to fix, for example `runtime`, `auth.mode`, `operations.<id>.handler`, or `operations.<id>.fixtures.response`.
 
+### Health assertion context
+
+`healthCheck.cases[].assertions` receives a `HealthCheckAssertionContext` with
+`data`, `status`, `durationMs`, and optional `meta`. `data` is typed from the
+operation output schema, so assertions should inspect normalized output instead
+of reaching into transport internals.
+
+<!-- @magic-start:sample -->
+```ts
+healthCheck: {
+  interval: "5m",
+  cases: [{
+    name: "lookup baseline",
+    input: { q: "btc" },
+    assertions: ({ data, status, durationMs }) => {
+      if (status !== 200 || data.results.length === 0 || durationMs > 3000) {
+        return { status: "degraded", label: "lookup baseline changed" };
+      }
+    },
+  }],
+}
+```
+<!-- @magic-end:sample -->
+
 ### Strongly recommended (warn-level rules)
 
 - `description` includes "use" AND "when" phrasing
@@ -65,6 +89,158 @@ Use `defineOperation()` when an operation is large enough to live beside helper
 - `tags`: operation-level semantic tags for retrieval (e.g., `["weather", "korea", "realtime"]`)
 - `relatedOperations`: `{ alternatives?: string[] }` — links to fallback/sibling operations
 
+### STT runtime capability for audio OTP and short transcription
+
+Providers that need speech-to-text should use the SDK runtime capability instead
+of constructing a vendor client inside provider code. Declare STT at the provider
+level, then call `ctx.stt` from operation handlers or auth-flow handlers.
+
+<!-- @magic-start:sample -->
+```ts
+export default defineProvider({
+  id: "example-provider",
+  // ...metadata, auth, operations, allowedHosts
+  stt: { mode: "required" },
+  operations: {
+    verifyAudioOtp: {
+      input: z.object({
+        audioBase64: z.string().describe("Base64-encoded short OTP audio"),
+        mediaType: z.string().optional().describe("Audio MIME type"),
+      }),
+      output: z.object({ code: z.string().describe("Verification code") }),
+      async handler(ctx, input) {
+        const transcript = await ctx.stt.transcribe({
+          audio: {
+            kind: "base64",
+            data: input.audioBase64,
+            mediaType: input.mediaType,
+          },
+          language: "ko-KR",
+          mode: "otp",
+          verificationCode: { codeLengths: [4, 6] },
+        });
+
+        const code =
+          transcript.verificationCode?.code ??
+          ctx.stt.extractVerificationCode(transcript.text, {
+            locale: "ko-KR",
+            codeLengths: [4, 6],
+          }).code;
+
+        return { code };
+      },
+      healthCheckUnsupported: {
+        reason: "Audio OTP transcription is cost-bearing and requires explicit smoke evidence.",
+      },
+    },
+  },
+});
+```
+<!-- @magic-end:sample -->
+
+Best-practice rules:
+
+- `stt: { mode: "required" }` is the production path for providers that depend
+  on STT; APIFuse provider manifests project STT credentials, model config, and
+  Cloudflare egress only for required STT. Use `mode: "optional"` only when STT
+  is a host/test override or truly best-effort capability that can remain
+  unavailable in production.
+- Do not assume OTPs are always four digits. Configure accepted lengths, for
+  example `[4, 6]`, and keep the returned code as a string to preserve leading
+  zeros.
+- Prompts are hints, not correctness guarantees. General transcription sends no
+  prompt by default. OTP mode may send a default digit-preserving hint. Use a
+  custom `initialPrompt` only with `promptPolicy: "custom-hint"`, and do not log
+  prompts, transcripts, raw audio, or OTP values.
+- STT v1 accepts JSON-safe base64 audio only. Do not fetch arbitrary audio URLs
+  from provider code; URL input needs separate SSRF/private-network policy.
+- Local and production wiring use the same env-backed runtime path. For the
+  Cloudflare Workers AI backend, set `APIFUSE__STT__BACKEND=cloudflare-workers-ai`,
+  `APIFUSE__STT__MODEL=@cf/openai/whisper-large-v3-turbo`,
+  `APIFUSE__CLOUDFLARE__ACCOUNT_ID`, and `APIFUSE__STT__CLOUDFLARE_API_TOKEN` in `.env.local` or the
+  provider workload environment. Do not deploy a Cloudflare Worker proxy for the
+  MVP; the SDK runtime calls Workers AI REST directly.
+- Submission checks and health checks must not invoke live STT by default.
+  Provide explicit smoke evidence when a provider depends on audio OTP behavior.
+
+
+### Health journey DX for SMS/payment flows
+
+Use `defineSmsOtpMatcher()` plus `defineHealthJourney()` when a real health signal requires an OTP ceremony and a safe handoff boundary. Keep matcher fields standards-backed: ISO 3166-1 alpha-2 `country`, BCP 47 `locale`, E.164 `phoneNumber` when present, ISO 8601 durations, and `nationalServiceCode` origins for local service senders. Do not add custom allowlist fields such as `senderAllowlist`; model the sender as an origin instead.
+
+<!-- @magic-start:sample -->
+```ts
+import {
+	defineHealthJourney,
+	defineProvider,
+	defineSmsOtpMatcher,
+	every,
+} from "@apifuse/provider-sdk";
+
+const phoneOtp = defineSmsOtpMatcher({
+	id: "phone-otp",
+	country: "KR",
+	locale: "ko-KR",
+	origins: [
+		{
+			kind: "nationalServiceCode",
+			country: "KR",
+			value: "16615270",
+			display: "1661-5270",
+		},
+	],
+	code: { pattern: /인증번호는\s*\[([0-9]{4})\]/, capture: 1 },
+	maxAge: "PT5M",
+	waitTimeout: "PT2M30S",
+	clockSkew: "PT10S",
+});
+
+const paymentWebviewJourney = defineHealthJourney({
+	id: "sms-payment-webview",
+	schedule: every("8h", { jitter: "PT20M" }),
+	timeout: "PT5M",
+	cooldown: "PT8H",
+	requiredSecrets: [
+		"APIFUSE__HEALTH_MONITOR__PROVIDER_PHONE",
+		"APIFUSE__HEALTH_MONITOR__PROVIDER_PASSWORD",
+		"APIFUSE__HEALTH_MONITOR__PROVIDER_CANARY_ORDER_JSON",
+	],
+	coversOperations: ["verify-phone", "confirm-phone", "place-order"],
+	smsMatchers: [phoneOtp],
+	steps: [
+		{ id: "send-phone-otp", kind: "operation", operationId: "verify-phone" },
+		{ id: "wait-phone-otp", kind: "smsOtp", usesSmsMatcher: "phone-otp" },
+		{ id: "confirm-phone-otp", kind: "operation", operationId: "confirm-phone" },
+		{
+			id: "create-payment-webview",
+			kind: "operation",
+			operationId: "place-order",
+			safeBoundary: "paymentWebviewUrl",
+		},
+	],
+});
+
+export default defineProvider({
+	id: "example-provider",
+	// ...metadata, auth, operations, allowedHosts
+	healthJourneys: [paymentWebviewJourney],
+});
+```
+<!-- @magic-end:sample -->
+
+The journey runner supplies `ctx.gateway`, `ctx.sms.waitForOtp()`, `ctx.journal.sideEffect()`, `ctx.state`, and `ctx.event.operation()` to the optional journey `run` function. Provider authors should keep `run` small: call the covered operations in step order, stop at the declared safe boundary, and let the generated health metadata carry schedule, timeout, required secret, and SMS matcher information to the health monitor.
+
+For authenticated journeys, open a fresh connection inside `run` with `ctx.gateway.connect({ input: { ... } })`, execute covered operations with the returned `connectionId`, and disconnect in a `finally` block. Do not require or store long-lived `HEALTH_MONITOR_*_CONNECTION_ID` secrets; those stale connection IDs can hide broken login ceremonies.
+
+Use the runtime capabilities narrowly:
+
+- `ctx.gateway.execute()` is the default path for operation health evidence; the runner records operation success/failure automatically.
+- `ctx.journal.sideEffect()` wraps non-replayable provider mutations such as create/cancel/send operations.
+- `ctx.state.namespace(name, policy)` stores bounded lifecycle memory and recovery cursors with TTL/quota/value-size policy. It is not a replacement for the side-effect journal.
+- `ctx.event.operation()` records only synthetic operation outcomes proven by the journey, such as recovery/manual-review checks that are not direct gateway calls. The runtime rejects events for operations outside `coversOperations`.
+
+Do not import `apps/health-monitor`, generated health artifacts, database repositories, schedulers, or recorders from provider code. If a journey needs provider-specific helper code, place it under the provider package (for example `providers/<id>/health-journeys/*`) and keep the SDK boundary generic.
+
 ### External bounty submission evidence
 
 External contributors are expected to submit standalone Provider source plus:
@@ -74,6 +250,7 @@ External contributors are expected to submit standalone Provider source plus:
 - Health coverage table for every Operation.
 - `bun run check` output.
 - `bun run test` output.
+- `bun run submit-check` score/verdict and generated `submission-report.md`.
 - Fixture evidence and known upstream constraints.
 
 Maintainers own monorepo import under `providers/<id>/`, registry generation,
@@ -87,15 +264,160 @@ deployment projection checks, and release workflows.
 - Credential-backed smoke requests pass local-only credential material in
   `connection.secrets`. Keep real values in shell env or `.env`, never in source
   or fixtures.
+- Hand-written auth flows should use `ctx.auth` helpers and return exactly one
+  terminal/next turn from each handler: `ctx.auth.nextForm(...)` or
+  `ctx.auth.nextPoll(...)` to ask Gateway for the next user/system step,
+  `ctx.auth.complete(...)` to finish with `data.credential`, or
+  `ctx.auth.abort(...)` to stop safely. Keep abort `data` and `actionHint`
+  JSON-safe and secret-free; never include raw cookies, credentials, headers,
+  HTML, or upstream `Error` objects.
+
+```ts
+export default defineProvider({
+  id: "example-provider",
+  version: "1.0.0",
+  runtime: "standard",
+  auth: {
+    mode: "credentials",
+    flow: {
+      async start(ctx) {
+        return ctx.auth.nextForm({
+          fields: {
+            email: { type: "email", labelKey: "auth.email.label" },
+            password: { type: "password", labelKey: "auth.password.label" },
+          },
+          hintKey: "auth.signIn",
+        });
+      },
+      async continue(ctx, input) {
+        const result = await loginWithSubmittedFields(ctx, input);
+        if (result.blocked) {
+          return ctx.auth.abort({
+            code: "account_action_required",
+            retry: "after_user_action",
+            actionHint: { kind: "open_provider_app" },
+            message: "Approve the login in the provider app.",
+          });
+        }
+        return ctx.auth.complete({
+          credential: { cookie: result.cookie },
+          metadata: { accountId: result.accountId },
+        });
+      },
+    },
+  },
+  credential: { keys: ["cookie"] },
+  // ...metadata and operations
+});
+```
+
+- Credentials auth providers should use `defineCredentialsAuth()` instead of
+  hand-writing `auth.flow.start/continue`. The helper exposes one happy path:
+  declare form `fields`, declare `credentialKeys`, and put upstream login/session
+  creation in `login(ctx, input)`. It returns both `auth` and `credential` for
+  `defineProvider()` and builds the complete turn as `data.credential`, which is
+  the only value Gateway persists onto the connection.
+
+```ts
+import { defineCredentialsAuth, defineProvider } from "@apifuse/provider-sdk";
+
+const credentialsAuth = defineCredentialsAuth({
+  fields: {
+    email: { type: "email", labelKey: "auth.email.label" },
+    password: { type: "password", labelKey: "auth.password.label" },
+  },
+  credentialKeys: ["cookie"] as const,
+  storesReusableSecret: true,
+  justification: "Session cookie is required for authenticated operations.",
+  async login(ctx, input) {
+    const cookie = await loginAndBuildSessionCookie(ctx, input);
+    return { credential: { cookie } };
+  },
+});
+
+export default defineProvider({
+  id: "example-provider",
+  version: "1.0.0",
+  runtime: "standard",
+  auth: credentialsAuth.auth,
+  credential: credentialsAuth.credential,
+  context: credentialsAuth.context,
+  // ...metadata and operations
+});
+```
+
+For OTP, MFA, CAPTCHA handoff, or user-approved login, return a challenge from
+`login()` instead of hand-writing `contextPatch`, `poll`, and final credential
+turns. SDK stores the pending challenge in auth-flow context, returns the next
+form/pending turn, and still persists only the final `data.credential`.
+
+```ts
+import {
+  credentialsAuthChallenge,
+  defineCredentialsAuth,
+} from "@apifuse/provider-sdk";
+
+const credentialsAuth = defineCredentialsAuth({
+  fields: {
+    email: { type: "email" },
+    password: { type: "password" },
+  },
+  credentialKeys: ["cookie"] as const,
+  async login(ctx, input) {
+    const result = await passwordLogin(ctx, input);
+    if (result.otpRequired) {
+      return credentialsAuthChallenge("otp", {
+        state: { transactionId: result.transactionId },
+        hintKey: "auth.otp.prompt",
+      });
+    }
+    if (result.manualApprovalRequired) {
+      return credentialsAuthChallenge("manualApproval", {
+        state: { transactionId: result.transactionId },
+        hintKey: "auth.manualApproval.openApp",
+        timing: { suggestedPollIntervalMs: 3000, maxWaitMs: 120000 },
+      });
+    }
+    return { credential: { cookie: result.cookie } };
+  },
+  challenges: {
+    otp: {
+      fields: { otp: { type: "otp", labelKey: "auth.otp.label" } },
+      async verify(ctx, input, state) {
+        const result = await verifyOtp(ctx, state.transactionId, input.otp);
+        return { credential: { cookie: result.cookie } };
+      },
+    },
+    manualApproval: {
+      async poll(ctx, state) {
+        const result = await checkApproval(ctx, state.transactionId);
+        if (!result.approved) return null;
+        return { credential: { cookie: result.cookie } };
+      },
+    },
+  },
+});
+```
 - Auth-flow debugging starts with `/auth/start`, continues with
   `/auth/continue`, and carries returned `contextPatch` values into the next
   request's `context`.
-- TLS/browser providers may require local runtime setup outside Provider code:
-  use `bun pm untrusted`/`bun pm trust koffi` for blocked native TLS dependency
-  scripts, `browser.engine: "playwright-stealth"` for TypeScript browser
-  Providers (`nodriver` is Python-runtime only), `bunx playwright install
-  chromium` for local Playwright browser assets, or
-  `CDP_POOL_URL`/`APIFUSE_CDP_POOL_URL` for remote browser debugging.
+- Stealth/browser providers may require local runtime setup outside Provider code:
+  keep access-sensitive operations on `ctx.stealth.fetch()` with an SDK stealth
+  `profile`; the TypeScript runtime uses `impit` behind that interface, so do
+  not add per-operation JA3, HTTP/2 SETTINGS, or pseudo-header tuning. `ctx.stealth`
+  supports Chrome/Firefox-style profiles; use `browser.engine:
+  "playwright-stealth"` for Safari-specific or real browser Providers
+  (`nodriver` is Python-runtime only); install local browser assets with
+  `bunx playwright install chromium`, or set
+  `APIFUSE__CDP_POOL__URL` for remote browser debugging.
+
+### Running the pre-submission report
+
+```bash
+bun run submit-check
+```
+
+The report scores review readiness across definition metadata, operation/schema quality, fixtures/tests, health coverage, local smoke evidence, auth safety, secret hygiene, and submission docs. It is not a payout guarantee; any blocker must be fixed before review. For the complete public-only submission checklist, see `SUBMISSION.md` in the SDK package.
 
 ### Running the lint locally
 

package/CHANGELOG.md

@@ -1,11 +1,95 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.1.0-beta.20
+
+- Release candidate for main commit 2a07cc5aef0d517c3b01d20445105f1669446bd3.
+
+## 2.1.0-beta.19
+
+- Release candidate for main commit 71d76385f722b1202880f26b14ea3916a07852eb.
+
+## 2.1.0-beta.18
+
+- Release candidate for main commit 46f93ecf8c2c8aab1afd0f23f5f62a87cbb45f6d.
+
+## 2.1.0-beta.17
+
+- Release candidate for main commit c4466ffc8a30cb99740b50687a62b92cec9ba10e.
+
+## 2.1.0-beta.16
+
+- Release candidate for main commit c0d8a1c4be519e1c1abc59e0304efc64f371634d.
+
+## Unreleased
+
+- Add `arrayBuffer()` and `bytes()` to `HttpResponse` so `ctx.http` consumers can read binary-safe upstream bodies; internal response handling is now byte-first.
+
+## 2.1.0-beta.15
+
+- Release candidate for main commit 4f51232d87828082f117dcc9f0c257a46f37c040.
+
+## 2.1.0-beta.14
+
+- Release candidate for main commit 6eb132be6abf34ad9a70bfe28c6d26b36348ff4a.
+
+## 2.1.0-beta.13
+
+- Release candidate for main commit d7b12716f54781df3e40206144c167844a485f8f.
+
+## 2.1.0-beta.12
+
+- Release candidate for main commit 2bc1061c6a68facaa2efde08bee31bf5cd96945e.
+
+## 2.1.0-beta.11
+
+- Release candidate for main commit b98ddc5024698f8c79e05e3295f7c8c8e8fe5a8a.
+
+## 2.1.0-beta.9
+
+- Preserve raw stealth response bytes through the public SDK response wrapper.
+- Add `arrayBuffer()` and `bytes()` to `StealthResponse` so consumers can inspect binary-safe upstream bodies.
+
+## 2.1.0-beta.8
+
+- Fix release automation for compiled `dist` package exports by building before package self-tests.
+- Provide `GH_TOKEN` to the GitHub release creation step.
+
+## 2.1.0-beta.7
+
+- Publish compiled `dist` exports for npm consumers so Next.js/Vercel builds do not parse TypeScript from `node_modules`.
+- Keep public CLI/template source files in the package while routing library exports through generated JavaScript and declarations.
+
+## 2.1.0-beta.6
+
+- Public repository clean-import release for `APIFuseHQ/provider-sdk`.
+- Preserves the monorepo SDK exports required by ApiFuse provider registry cutover, including `./contract` and provider i18n helpers.
+
+
+## 2.1.0-beta.5
+
+- Republish the bounty workspace DX hardening that accepts generated readonly metadata and factored `defineOperation()` maps during standalone TypeScript checks.
+- Ensure new bounty workspaces can install the public SDK version that matches their generated scaffold and pass `bun run check` immediately after bootstrap.
+
+## 2.1.0-beta.4
+
+- Align `apifuse create` with the bounty program topology: external contributors use the standalone one-provider-repository scaffold even when their assigned repo contains workspace-like files.
+- Stop auto-detecting `providers/` directories as public monorepo scaffolds. `--preset monorepo` is now reserved for the private APIFuse monorepo where `packages/provider-sdk` is actually present.
+- Remove public CLI/docs examples that present monorepo placement as a contributor workflow.
+
+## 2.1.0-beta.3
+
+- Replace the legacy TypeScript request transport with `ctx.stealth`, backed by `impit` browser-grade TLS/HTTP2 impersonation without Python runtime dependencies.
+- Add the public `apifuse submit-check` / `apifuse bounty-check` CLI for score-based pre-submission provider quality checks.
+- Ship `SUBMISSION.md` in the npm package so bounty contributors can follow the checklist without access to the private monorepo.
+- Include submit-check in generated provider validation scripts and packed-artifact smoke coverage.
+- Warn, instead of hard-block, generated OAuth starters that have not yet declared persisted credential keys.
+
 ## 2.1.0-beta.2
 
 - Harden public bounty contributor DX with server-contract accurate README and generated Provider smoke examples.
 - Add packed-artifact regression checks so stale `connection: null` or missing `requestId` examples cannot ship again.
 - Extend clean-room packed SDK smoke coverage to boot the generated dev server and call `/health` plus `POST /v1/ping`.
-- Document credential, auth-flow, TLS, browser, and Bun trusted-dependency troubleshooting for SDK-only local development.
+- Document credential, auth-flow, stealth, browser, and Bun trusted-dependency troubleshooting for SDK-only local development.
 
 ## 2.1.0-beta.1
 

package/README.md

@@ -1,6 +1,6 @@
 # @apifuse/provider-sdk
 
-ApiFuse Provider SDK — build provider declarations and runtimes with one public SDK surface and one canonical CLI.
+APIFuse Provider SDK — build provider declarations and runtimes with one public SDK surface and one canonical CLI.
 
 ## Install
 
@@ -29,13 +29,11 @@ The canonical `create` flow:
 3. runs baseline validation,
 4. prints the exact next local-dev command.
 
-### Monorepo preset
+### Repository shape
 
-Inside the ApiFuse repository:
+The Provider SDK is a public bounty-contributor tool first. External bounty workspaces are one-provider repositories initialized from the standalone create flow. The generated provider must be installable without private APIFuse monorepo access.
 
-```bash
-apifuse create my-provider --preset monorepo
-```
+Do not use internal monorepo placement for bounty workspaces. Accepted provider work is imported into the private APIFuse monorepo later by maintainers or trusted automation.
 
 ## Provider server contract
 
@@ -58,6 +56,7 @@ Removed legacy runtime paths are not supported:
 cd my-provider
 bun run check
 bun run test
+bun run submit-check -- --smoke
 bun run dev
 ```
 
@@ -70,7 +69,7 @@ curl -s -X POST http://localhost:3900/v1/ping \
   -d '{"requestId":"req_local_ping","input":{"value":"hello"},"headers":{}}'
 ```
 
-The operation request body is the same envelope used by the ApiFuse gateway:
+The operation request body is the same envelope used by the APIFuse gateway:
 
 | Field | Required | Notes |
 |---|---:|---|
@@ -88,7 +87,7 @@ curl -s -X POST http://localhost:3900/v1/me \
     "requestId":"req_local_me",
     "input":{},
     "connection":{
-      "id":"conn_local_debug",
+      "id":"af_con_local_debug",
       "mode":"credentials",
       "secrets":{"apiKey":"dev-only-secret"},
       "scopes":[],
@@ -121,17 +120,32 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   `ctx.credential.get("key")` or `ctx.credential.getAccessToken()`.
 - **Provider env secrets**: declare `secrets[]`, set values in your shell or
   `.env`, and read only those names through `ctx.env.get("NAME")`.
+- **Credentials auth flows**: prefer `defineCredentialsAuth()` over hand-written
+  `auth.flow`. Declare the form fields and credential keys once, then put the
+  upstream login/session creation in `login(ctx, input)`. Return
+  `credentialsAuthChallenge("otp" | "manualApproval" | ...)` for MFA, CAPTCHA
+  handoff, or user-approved login branches. The helper returns
+  `{ auth, credential, context }` for `defineProvider()` and always completes
+  with `data.credential`, which is the value Gateway persists onto the
+  connection.
 - **Auth flows**: call `/auth/start`, then `/auth/continue` with the same
   `flowId`; preserve any returned `contextPatch` in the next local request's
   `context` object.
-- **TLS-sensitive providers**: if Bun reports blocked lifecycle scripts after
-  install, run `bun pm untrusted`; when it lists trusted SDK native dependencies
-  such as `koffi`, run `bun pm trust koffi` (or `bun pm trust`) before debugging
-  `ctx.tls` failures.
+- **Stealth-sensitive providers**: use `ctx.http` for normal JSON/REST calls and
+  `ctx.stealth.fetch()` when you need browser-like session or cookie control.
+  `ctx.stealth.fetch()` uses the impit-backed browser stealth transport and
+  accepts request controls for `params`, `proxy`, `timeout`, `profile`,
+  `redirect`, `throwOnHttpError`, and `stealth.insecureSkipVerify`. For login
+  flows that must inspect intermediate `Location`/`Set-Cookie` headers, create
+  a session with `ctx.stealth.createSession()` and use `session.redirects.run()`;
+  inspect accumulated cookies through `session.cookies`. Select an SDK stealth
+  `profile` such as `chrome-146`; do not tune JA3, HTTP/2 SETTINGS, or
+  pseudo-header order in provider code. Chrome/Firefox-style profiles are
+  supported; use `ctx.browser` when Safari-specific behavior is required.
 - **Browser providers**: for TypeScript Providers use `runtime: "browser"` plus
   `browser.engine: "playwright-stealth"`; `nodriver` is a Python-runtime path.
   Install local browser assets with `bunx playwright install chromium` when
-  using the Playwright runtime, or set `CDP_POOL_URL`/`APIFUSE_CDP_POOL_URL`
+  using the Playwright runtime, or set `APIFUSE__CDP_POOL__URL`
   when debugging against a remote browser pool.
 
 ## Authoring ergonomics
@@ -147,6 +161,9 @@ const search = defineOperation({
   async handler(ctx, input) {
     return { count: input.q.length }
   },
+  healthCheckUnsupported: {
+    reason: "Example operation only; replace with a real upstream probe.",
+  },
 })
 
 export default defineProvider({
@@ -172,6 +189,24 @@ Every operation must declare exactly one of:
 The generated `ping` operation uses `healthCheckUnsupported` only because it is
 a local scaffold check, not a real upstream API probe.
 
+`healthCheck.cases[].assertions` receives `{ data, status, durationMs, meta }`.
+`data` is the operation output parsed by the declared output schema:
+
+```ts
+healthCheck: {
+  interval: "5m",
+  cases: [{
+    name: "search responds",
+    input: { q: "weather" },
+    assertions: ({ data, status, durationMs }) => {
+      if (status !== 200 || data.count < 1 || durationMs > 3000) {
+        return { status: "degraded", label: "unexpected search baseline" }
+      }
+    },
+  }],
+}
+```
+
 ### Operation annotations
 
 Operations declare non-functional metadata via `annotations`:
@@ -193,16 +228,28 @@ Operations declare non-functional metadata via `annotations`:
 apifuse create <name>
 apifuse dev [path]
 apifuse check [path]
-apifuse record [path] --operation <operation> --params '{"value":"hello"}'
+apifuse record providers/korea-air-quality --operation realtime --params '{"stationName":"종로구"}'
 apifuse test [path]
-apifuse perf <path> --operation <operation>
+apifuse submit-check [path] --tier bronze --markdown submission-report.md
+apifuse bounty-check [path]
+apifuse perf providers/korea-air-quality --operation realtime --params '{"stationName":"종로구"}'
 ```
 
 `apifuse record` is for real upstream-backed operations that declare
-`upstream.baseUrl` and call the upstream through `ctx.http` or `ctx.tls`. The
+`upstream.baseUrl` and call the upstream through `ctx.http` or `ctx.stealth`. The
 generated local-only `ping` operation intentionally has no upstream and should
 be replaced before recording fixtures.
 
+## Bounty submission readiness
+
+Standalone providers include a pre-submission script:
+
+```bash
+bun run submit-check -- --smoke
+```
+
+This runs the public review-readiness evaluator and writes `submission-report.md`. The report contains provider metadata, a 100-point readiness score, hard blockers, warnings, checklist evidence, measured smoke details, and remediation. Blockers override the score; fix them before posting bounty evidence. `--smoke` boots the local dev server, checks `/health`, and POSTs every operation fixture. Set `APIFUSE__PROVIDER__*` env vars when live upstream credentials are available; without them, structured provider errors can still earn runtime-path smoke credit. See [`SUBMISSION.md`](./SUBMISSION.md) for the full public-only bounty submission checklist shipped in the npm package.
+
 ## Scope boundary
 
 Generator v1 scaffolds **TypeScript providers only** for this redesign. Python generation remains future work.
@@ -213,6 +260,6 @@ Generator v1 scaffolds **TypeScript providers only** for this redesign. Python g
 Provider cataloging, deployment enrollment, docs indexing, and runtime discovery are internal platform-registry responsibilities and are not part of the public `@apifuse/provider-sdk` contract.
 
 External bounty contributors should submit standalone Provider source plus
-`bun run check` / `bun run test` evidence. ApiFuse maintainers own monorepo
+`bun run check` / `bun run test` evidence. APIFuse maintainers own monorepo
 import, registry generation, deployment projection checks, and release
 publishing.