@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.10

package/AUTHORING.md

@@ -18,6 +18,59 @@
 
 Provider code is the declaration input to the internal platform registry. The public SDK owns provider authoring/runtime ergonomics; internal docs, deploy, and discovery projections are built downstream from those declarations. `bun run lint:providers` enforces provider authoring standards.
 
+### User-input round-trips: never dead-end (`needs_input`)
+
+A mutation MUST NOT fail for a problem the end user can resolve by choosing among live options (a required menu/course selection, a form question, a stale-but-recoverable state token). Throwing an error there strands the consuming agent: consumer error-shaping layers routinely strip error metadata, and a model that only sees "error" narrates failure to the user instead of relaying the choice.
+
+Return the official success-shaped contract from `src/user-input.ts` instead (`ProviderNeedsInputPayload`, guard `isProviderNeedsInputPayload`):
+
+- `status: "needs_input"` plus `required_selections` — only the still-pending questions, with human-readable `label`s and `valid_options` the agent relays verbatim. The agent never chooses for the user; anything with no real choice (agreement checkboxes, single-option required groups) is the provider's job to auto-answer.
+- `selected_options` — selections already settled, echoed so the retry keeps them (copy them back and add the user's new answers).
+- a freshly minted provider state token in the same response, so the retry never races an expired token.
+
+No retry templates, next-action routing, or other agent choreography: provider payloads carry upstream-backed data only, and the consumer owns how the ask is phrased and how the retry call is shaped.
+
+Declare the union in the operation `output` schema (`z.union([CreatedSchema, NeedsInputSchema])`). Reserve hard errors for genuinely unrecoverable flows (payment-gated, unsupported input kinds) and state the concrete reason in the error `message` itself, not only in `details`. Reference implementation: `providers/catchtable` `reserve` in the platform monorepo.
+
+### Attempt tokens: the server carries the decisions
+
+When a mutation needs more than one user decision (or one decision plus a
+final go/no-go), do not make the agent re-send accumulated state across
+rounds — weak models drop or corrupt it. Split the operation into a
+**prepare/confirm pair** driven by a server-held attempt record:
+
+- The prepare operation is non-destructive. A start call takes only the
+  scalar intent fields; every response returns a fresh `attempt_token`
+  referencing a server-side record (`ctx.choice.issue` with
+  `storage.mode: "server"`) that stores every settled decision. Continue
+  calls take `attempt_token` plus only the NEW answers.
+- `needs_input` rounds list only the still-pending selections; settled
+  decisions may ride along in a display-only field but are never re-sent.
+- When nothing is pending, the prepare operation returns `status: "ready"`
+  with a human-readable summary — the consumer's user-facing confirmation.
+- The confirm operation is the only mutation and takes exactly
+  `{attempt_token}`. It re-validates everything live before executing and
+  returns `needs_input` (fresh token) instead of proceeding when upstream
+  drift invalidates a stored decision — never substitute a different option
+  for what the user picked.
+- Expired or foreign tokens fail factually (nothing happened; start a new
+  attempt with the scalar fields) — no answer salvage from a dead token.
+- **The provider must enforce consumption itself.** `ctx.choice` server
+  storage keeps tokens parseable until TTL — `parse` does not invalidate
+  them, so a confirm handler that only parses can be replayed into a second
+  booking or payment. After a successful execution, record the result under
+  the token's digest in `ctx.state` and make replays idempotent: a repeated
+  confirm returns the original created payload without touching upstream,
+  and later prepare rounds on the consumed token fail factually with the
+  existing reference. Record the result only after upstream success, so an
+  interrupted confirm stays retryable.
+
+The invariant behind all of it: complex flow state is the system's job, not
+the model's. The model carries exactly one opaque key between calls.
+Reference implementations: `providers/catchtable` `reserve`/`reserve-confirm`
+(including the consume-on-success guard) and `providers/modu-parking`
+payment state tokens in the platform monorepo.
+
 ### Description template
 
 Every operation `description` MUST be at least 150 characters and follow this structure:
@@ -256,6 +309,59 @@ External contributors are expected to submit standalone Provider source plus:
 Maintainers own monorepo import under `providers/<id>/`, registry generation,
 deployment projection checks, and release workflows.
 
+### Declared secrets are SDK-enforced
+
+Environment/secret presence validation is single-sourced in the SDK. Declare
+every env secret the provider needs in `defineProvider`:
+
+```ts
+secrets: [
+  {
+    name: "APIFUSE__PROVIDER__MY_PROVIDER__API_KEY",
+    required: true,
+    description: "Upstream API key from the vendor portal",
+  },
+],
+```
+
+The runtime validates every `required: true` declaration before any operation
+handler or auth-flow handler (except `abort`) runs. When a required secret is
+unset or whitespace-only, the invocation fails with the canonical structured
+error — code `MISSING_SECRET`, HTTP 400, `details.category:
+"credential_unavailable"`, `retryable: false`, and a `fix` naming every missing
+secret — across `/v1/{operation}`, self-test probes, `apifuse perf`, and
+`apifuse record`. The server also emits a `provider_secrets_missing` warn log
+at boot so unprovisioned deployments are visible immediately without crashing
+the pod.
+
+Provider-local presence re-validation is **deprecated**: do not write
+`requireServiceKey`/`requireApiKey`-style guards that re-check `ctx.env.get()`
+and throw a hand-rolled `CONFIGURATION_ERROR`/`MISSING_SECRET`. Those guards
+are dead weight (the SDK gate runs first) and historically diverged into
+inconsistent error shapes. The `sdk-owned-secret-presence` submit-check rule
+flags them at warn level; acknowledge a deliberate exception with
+`// @apifuse-allow sdk-owned-secret-presence: <reason>`.
+
+```ts
+// Before (deprecated): provider-local double validation
+function requireServiceKey(ctx: ProviderContext): string {
+  const value = ctx.env.get(SERVICE_KEY_ENV);
+  if (!value?.trim()) {
+    throw new ProviderError(`Missing required provider secret: ${SERVICE_KEY_ENV}`, {
+      code: "CONFIGURATION_ERROR",
+    });
+  }
+  return value;
+}
+
+// After: declare { name: SERVICE_KEY_ENV, required: true } and read directly.
+const serviceKey = ctx.env.get(SERVICE_KEY_ENV);
+```
+
+Note the asymmetry: the gate treats whitespace-only values as missing, but
+`ctx.env.get()` still returns the raw value to handlers — trim at the point of
+use if the upstream is whitespace-sensitive.
+
 ### Public local debugging checklist
 
 - Operation smoke requests use the provider server envelope:
@@ -264,6 +370,140 @@ 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`.

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.10
+
+- Release candidate for main commit c41bd919739e0293ae8fa4d72a8a32f034cef4b8.
+
+## 2.2.0-beta.9
+
+- Release candidate for main commit 5c78c8b (bundles #67 nodemaven required-secret + #68 transport vendor-advance).
+
+## 2.2.0-beta.8
+
+- Release candidate for main commit 9e8a3f028ee78b9cab29d4aa3f5494ac9cffa65f.
+
+## 2.2.0-beta.7
+
+- Release candidate for main commit 2ce4ea4bd36ce333eba8b3b474bf6e82b5e9216c.
+
+## 2.2.0-beta.6
+
+- Release candidate for main commit 17f4e41d44efe7c148ef875b950be4f2c7df1294.
+
+## 2.2.0-beta.5
+
+- Release candidate for main commit 82fa14e99a9af7edd44e3196aa3f4e87b4699edf.
+
+## 2.2.0-beta.4
+
+- Release candidate for main commit 73f2c6ec429c2fbce8ac458a67111e4844b99178.
+
+## 2.2.0-beta.3
+
+- Release candidate for main commit 74e8e18b502dd9b02dbf0d3e702f917570312fc0.
+
+## 2.2.0-beta.2
+
+- Release candidate for main commit ceefad020a1038eade542fd3b128667b39625f6f.
+
+## 2.2.0-beta.1
+
+- Release candidate for main commit 5056b8c89fe0fa8f10bafcd30f83bcc421d4b5c5.
+
+## 2.1.0-beta.22
+
+- Release candidate for main commit af84b1e91c408b69773468fdaef80a01a36707cf.
+
+## 2.1.0-beta.21
+
+- Release candidate for main commit 8124b3eb150cc7a73a86a95266b3747763a494ae.
+
+## 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.
+- Preserve identity-only operation `connectionId` values in `ProviderContext` without requiring credential material.
+
+## 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.

package/README.md

@@ -56,7 +56,7 @@ Removed legacy runtime paths are not supported:
 cd my-provider
 bun run check
 bun run test
-bun run submit-check
+bun run submit-check -- --smoke
 bun run dev
 ```
 
@@ -119,17 +119,33 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   local-only values through `connection.secrets`. Read them in handlers with
   `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")`.
+  `.env`, and read only those names through `ctx.env.get("NAME")`. The SDK
+  enforces presence of `required: true` declarations before handlers and auth
+  flows run, failing the invocation with a structured `MISSING_SECRET` error
+  (HTTP 400, category `credential_unavailable`) — do not re-check presence in
+  handlers.
+- **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.
 - **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`, `throwOnHttpError`, and
-  `stealth.insecureSkipVerify`. 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.
+  `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
@@ -233,10 +249,10 @@ be replaced before recording fixtures.
 Standalone providers include a pre-submission script:
 
 ```bash
-bun run submit-check
+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, and remediation. Blockers override the score; fix them before posting bounty evidence. The command is offline-safe by default and does not execute arbitrary upstream calls. Add local smoke notes to your assigned workspace PR after testing `/health` and `POST /v1/{operation}`. See [`SUBMISSION.md`](./SUBMISSION.md) for the full public-only bounty submission checklist shipped in the npm package.
+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
 

package/SUBMISSION.md

@@ -9,11 +9,11 @@ bunx @apifuse/provider-sdk@beta create my-provider --yes
 cd my-provider
 bun run check
 bun run test
-bun run submit-check
+bun run submit-check -- --smoke
 bun run dev
 ```
 
-`bun run submit-check` runs `apifuse submit-check . --markdown submission-report.md` in generated Providers.
+`bun run submit-check -- --smoke` runs the generated `apifuse submit-check . --markdown submission-report.md` script with measured smoke enabled.
 
 ## What submit-check scores
 
@@ -50,22 +50,21 @@ Fix all blockers before submitting:
 - High-confidence secret or token material in source, README, package metadata, or fixtures.
 - SDK-native source blockers: prefixed Provider ids, `vendor/` SDK shims or imports, raw `.describe()` prose instead of `describeKey`, raw global `fetch()` calls, and excessive `as Type` assertions.
 
-Warnings do not fail the command, but they should be addressed when practical. For example, the generated starter `ping` operation warns because it is not a real upstream-backed bounty Operation. SDK-native warnings also flag moderate `as Type` assertion counts and credentialed Providers that never reference `ctx.credential`.
+Warnings do not fail the command, but they should be addressed when practical. For example, the generated starter `ping` operation warns because it is not a real upstream-backed bounty Operation. SDK-native warnings also flag moderate `as Type` assertion counts, credentialed Providers that never reference `ctx.credential`, and provider-local re-validation of declared env secrets (`sdk-owned-secret-presence`, 0 points): the SDK already rejects invocations with a structured `MISSING_SECRET` error when a declared `required: true` secret is unset, so `requireServiceKey`-style presence guards are deprecated dead weight — delete the guard and read the value directly with `ctx.env.get()`, or acknowledge a deliberate exception with `// @apifuse-allow sdk-owned-secret-presence: <reason>`.
 
-## Safe local smoke evidence
+## Measured local smoke
 
-`submit-check` does not call arbitrary live upstream APIs by default. After replacing starter logic, run the Provider locally and record a short evidence note:
+`submit-check` does not call live upstream APIs by default. For smoke scoring,
+run measured smoke so the CLI boots the Provider, checks `/health`, and POSTs
+each operation fixture:
 
 ```bash
-bun run dev
-curl -s http://localhost:3900/health
-curl -s -X POST http://localhost:3900/v1/<operation> \
-  -H 'Content-Type: application/json' \
-  -d '{"requestId":"req_local_smoke","input":{...},"headers":{}}'
-
-bun run submit-check -- --smoke-note "GET /health and POST /v1/<operation> passed locally with redacted input."
+bun run submit-check -- --smoke
 ```
 
+`APIFUSE__PROVIDER__*` env vars enable live upstream calls. Their absence can
+still produce 7/10 smoke credit when every operation routes and returns a
+structured provider error envelope, but zero schema-valid successes are observed.
 Never paste real credentials, personal data, account numbers, access tokens, cookies, or unredacted upstream responses into workspace PR comments, chat, or reports.
 
 ## Submission evidence checklist

package/bin/apifuse-check.ts

@@ -6,9 +6,14 @@ import { pathToFileURL } from "node:url";
 
 import { z } from "zod";
 
-import type { ProviderDefinition } from "../src";
-import { lintProvider, type ProviderLintMode } from "../src/lint";
-import { safeParseSchemaSync } from "../src/schema";
+import {
+	formatPromptAssetIssues,
+	PROMPT_ASSET_SYNC_REMEDIATION,
+	verifyPromptAssets,
+} from "../src/cli/prompt-assets.js";
+import type { ProviderDefinition } from "../src/index.js";
+import { lintProvider, type ProviderLintMode } from "../src/lint.js";
+import { safeParseSchemaSync } from "../src/schema.js";
 
 const HELP_TEXT = `Usage: apifuse check [path]
 Example: apifuse check providers/korea-air-quality
@@ -24,9 +29,7 @@ export type RunChecksOptions = {
 	lintMode?: ProviderLintMode;
 };
 
-type SafeParseResult =
-	| { success: true; data: unknown }
-	| { success: false; error: unknown };
+type SafeParseResult = { success: true; data: unknown } | { success: false; error: unknown };
 
 export async function main() {
 	const args = normalizeArgs(process.argv.slice(2));
@@ -63,7 +66,7 @@ function normalizeArgs(argv: string[]): string[] {
 	return argv[0] === "check" ? argv.slice(1) : argv;
 }
 
-function resolveProviderRoot(inputPath: string): string {
+export function resolveProviderRoot(inputPath: string): string {
 	const resolvedInput = resolveFromParents(inputPath);
 
 	if (!existsSync(resolvedInput)) {
@@ -131,9 +134,26 @@ export async function runChecks(
 		checkProviderMetadata(provider),
 		checkDockerfile(dockerfilePath),
 		checkPackageJson(packageJsonPath),
+		checkPromptAssets(providerRoot),
 	];
 }
 
+export const PROMPT_ASSETS_CHECK_MESSAGE =
+	"Agent prompt assets match the installed SDK version";
+
+function checkPromptAssets(providerRoot: string): CheckResult {
+	const verification = verifyPromptAssets(providerRoot);
+	if (verification.ok) {
+		return { message: PROMPT_ASSETS_CHECK_MESSAGE, passed: true };
+	}
+
+	return {
+		message: PROMPT_ASSETS_CHECK_MESSAGE,
+		passed: false,
+		details: [...formatPromptAssetIssues(verification), PROMPT_ASSET_SYNC_REMEDIATION],
+	};
+}
+
 function isScannableProviderSourceFile(relativePath: string): boolean {
 	return (
 		/\.(?:ts|tsx|js|jsx|mjs|cjs|sh|bash)$/.test(relativePath) ||
@@ -142,17 +162,12 @@ function isScannableProviderSourceFile(relativePath: string): boolean {
 	);
 }
 
-function collectProviderSourceFiles(
-	providerRoot: string,
-): Record<string, string> {
+function collectProviderSourceFiles(providerRoot: string): Record<string, string> {
 	const sources: Record<string, string> = {};
-	const skipDirectories = new Set([
-		".git",
-		"node_modules",
-		"dist",
-		"build",
-		".next",
-	]);
+	// `.agents`/`.apifuse` are deliberately not skipped: managed content there
+	// is markdown/JSON (never matched by isScannableProviderSourceFile), and a
+	// planted `.ts`/`.sh` under those directories must stay in scanner scope.
+	const skipDirectories = new Set([".git", "node_modules", "dist", "build", ".next"]);
 	const visit = (directory: string) => {
 		for (const entry of readdirSync(directory, { withFileTypes: true })) {
 			const path = resolve(directory, entry.name);
@@ -162,10 +177,7 @@ function collectProviderSourceFiles(
 				}
 				continue;
 			}
-			if (
-				!entry.isFile() ||
-				!isScannableProviderSourceFile(path.slice(providerRoot.length + 1))
-			) {
+			if (!entry.isFile() || !isScannableProviderSourceFile(path.slice(providerRoot.length + 1))) {
 				continue;
 			}
 			sources[path.slice(providerRoot.length + 1)] = readFileSync(path, "utf8");
@@ -175,10 +187,7 @@ function collectProviderSourceFiles(
 	return sources;
 }
 
-function checkIndex(
-	indexPath: string,
-	provider: ProviderDefinition | undefined,
-): CheckResult {
+function checkIndex(indexPath: string, provider: ProviderDefinition | undefined): CheckResult {
 	if (!existsSync(indexPath)) {
 		return {
 			message: "index.ts exists and exports default defineProvider",
@@ -200,9 +209,7 @@ function checkIndex(
 	};
 }
 
-function checkOperations(
-	provider: ProviderDefinition | undefined,
-): CheckResult {
+function checkOperations(provider: ProviderDefinition | undefined): CheckResult {
 	if (!provider) {
 		return {
 			message: "All operations have handler, input, output",
@@ -277,20 +284,14 @@ function checkSchemas(provider: ProviderDefinition | undefined): CheckResult {
 			continue;
 		}
 
-		const requestResult = parseFixture(
-			operation.input,
-			operation.fixtures.request,
-		);
+		const requestResult = parseFixture(operation.input, operation.fixtures.request);
 		if (!requestResult.success) {
 			failures.push(
 				`${operationId}: request fixture invalid (${formatSchemaError(requestResult.error)})`,
 			);
 		}
 
-		const responseResult = parseFixture(
-			operation.output,
-			operation.fixtures.response,
-		);
+		const responseResult = parseFixture(operation.output, operation.fixtures.response);
 		if (!responseResult.success) {
 			failures.push(
 				`${operationId}: response fixture invalid (${formatSchemaError(responseResult.error)})`,
@@ -317,13 +318,8 @@ function checkAuthoringLint(
 		};
 	}
 
-	const diagnostics = lintProvider(
-		{ ...provider, providerSourceFiles },
-		{ mode: lintMode },
-	);
-	const errors = diagnostics.filter(
-		(diagnostic) => diagnostic.level === "error",
-	);
+	const diagnostics = lintProvider({ ...provider, providerSourceFiles }, { mode: lintMode });
+	const errors = diagnostics.filter((diagnostic) => diagnostic.level === "error");
 	const details = diagnostics.map((diagnostic) => {
 		const field = diagnostic.field ? `${diagnostic.field}: ` : "";
 		return `${diagnostic.level.toUpperCase()} ${diagnostic.rule} ${field}${diagnostic.message}`;
@@ -336,9 +332,7 @@ function checkAuthoringLint(
 	};
 }
 
-function checkProviderMetadata(
-	provider: ProviderDefinition | undefined,
-): CheckResult {
+function checkProviderMetadata(provider: ProviderDefinition | undefined): CheckResult {
 	if (!provider) {
 		return {
 			message: "Provider metadata is declared in defineProvider",
@@ -425,18 +419,12 @@ function checkPackageJson(packageJsonPath: string): CheckResult {
 	}
 }
 
-function assertProviderDefinition(
-	value: unknown,
-): ProviderDefinition | undefined {
+function assertProviderDefinition(value: unknown): ProviderDefinition | undefined {
 	return isProviderDefinition(value) ? value : undefined;
 }
 
 function isProviderDefinition(value: unknown): value is ProviderDefinition {
-	if (
-		!isRecord(value) ||
-		!isRecord(value.meta) ||
-		!isRecord(value.operations)
-	) {
+	if (!isRecord(value) || !isRecord(value.meta) || !isRecord(value.operations)) {
 		return false;
 	}
 
@@ -457,8 +445,7 @@ function hasSchemaParser(value: unknown): boolean {
 	return (
 		isRecord(value) &&
 		(typeof value.safeParse === "function" ||
-			(isRecord(value["~standard"]) &&
-				typeof value["~standard"].validate === "function"))
+			(isRecord(value["~standard"]) && typeof value["~standard"].validate === "function"))
 	);
 }
 
@@ -470,9 +457,7 @@ function formatSchemaError(error: unknown): string {
 	if (Array.isArray(error)) {
 		return error
 			.map((issue) =>
-				isRecord(issue) && typeof issue.message === "string"
-					? issue.message
-					: String(issue),
+				isRecord(issue) && typeof issue.message === "string" ? issue.message : String(issue),
 			)
 			.join(", ");
 	}