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

package/dist/cli/create.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { cancel, intro, isCancel, note, outro, select, text, } from "@clack/prompts";
+import { cancel, intro, isCancel, note, outro, select, text } from "@clack/prompts";
 import { z } from "zod";
 import packageJson from "../../package.json";
 export const PROVIDER_NAME_REGEX = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
@@ -17,12 +17,7 @@ export const CATEGORY_OPTIONS = [
     "communication",
     "other",
 ];
-export const AUTH_MODE_OPTIONS = [
-    "none",
-    "platform-managed",
-    "credentials",
-    "oauth2",
-];
+export const AUTH_MODE_OPTIONS = ["none", "platform-managed", "credentials", "oauth2"];
 export const RUNTIME_OPTIONS = ["standard", "browser"];
 export const PRESET_OPTIONS = ["standalone", "monorepo"];
 const CREATE_CONFIG_SCHEMA = z.object({
@@ -64,9 +59,7 @@ export async function main() {
         return;
     }
     const parsed = parseArgs(normalizedArgs);
-    const config = parsed.configPath
-        ? await loadConfig(parsed.configPath)
-        : undefined;
+    const config = parsed.configPath ? await loadConfig(parsed.configPath) : undefined;
     const resolved = await resolveCreateOptions(parsed, config, process.cwd());
     const plan = await buildProviderCreatePlan(resolved, process.cwd());
     if (resolved.dryRun) {
@@ -174,9 +167,7 @@ async function resolveCreateOptions(parsed, config, cwd) {
         category: parsed.category ?? config?.category,
         authMode: parsed.authMode ?? config?.authMode,
         runtime: parsed.runtime ?? config?.runtime,
-        sdkSpecifier: parsed.sdkSpecifier ??
-            config?.sdkSpecifier ??
-            process.env.APIFUSE__SDK__SPECIFIER,
+        sdkSpecifier: parsed.sdkSpecifier ?? config?.sdkSpecifier ?? process.env.APIFUSE__SDK__SPECIFIER,
         dryRun: parsed.dryRun,
         json: parsed.json,
         yes: parsed.yes,
@@ -267,9 +258,7 @@ async function promptValue(prompt) {
     return result;
 }
 export async function buildProviderCreatePlan(options, cwd) {
-    const resolvedWorkspaceRoot = options.preset === "monorepo"
-        ? findApifuseInternalWorkspaceRoot(cwd)
-        : undefined;
+    const resolvedWorkspaceRoot = options.preset === "monorepo" ? findApifuseInternalWorkspaceRoot(cwd) : undefined;
     if (options.preset === "monorepo" && !resolvedWorkspaceRoot) {
         throw new Error("Monorepo preset is internal to the APIFuse repository. External bounty workspaces are one-provider repositories; use the standalone default create flow.");
     }
@@ -278,9 +267,7 @@ export async function buildProviderCreatePlan(options, cwd) {
     if (options.outputDir) {
         providerRoot = resolve(cwd, options.outputDir);
         installCwd =
-            options.preset === "monorepo" && resolvedWorkspaceRoot
-                ? resolvedWorkspaceRoot
-                : providerRoot;
+            options.preset === "monorepo" && resolvedWorkspaceRoot ? resolvedWorkspaceRoot : providerRoot;
     }
     else if (options.preset === "monorepo" && resolvedWorkspaceRoot) {
         providerRoot = resolve(resolvedWorkspaceRoot, "providers", options.name);
@@ -293,8 +280,7 @@ export async function buildProviderCreatePlan(options, cwd) {
     if (existsSync(providerRoot)) {
         throw new Error(`Target directory already exists: ${providerRoot}`);
     }
-    if (options.sdkSpecifier?.startsWith("workspace:") &&
-        !resolvedWorkspaceRoot) {
+    if (options.sdkSpecifier?.startsWith("workspace:") && !resolvedWorkspaceRoot) {
         throw new Error("workspace:* is only valid inside the APIFuse monorepo because public Provider SDK scaffolds must install from npm or an explicit tarball/file specifier.");
     }
     const sdkSpecifier = options.sdkSpecifier ??
@@ -419,6 +405,38 @@ export async function buildProviderCreatePlan(options, cwd) {
                 PROVIDER_ID: options.name,
             }),
         },
+        {
+            path: resolve(providerRoot, "AGENTS.md"),
+            content: await renderTemplate("AGENTS.md.tpl", {}),
+        },
+        {
+            path: resolve(providerRoot, "CLAUDE.md"),
+            content: await renderTemplate("CLAUDE.md.tpl", {}),
+        },
+        {
+            path: resolve(providerRoot, "skills", "normalization-standards", "SKILL.md"),
+            content: await renderTemplate("skills/normalization-standards/SKILL.md.tpl", {}),
+        },
+        {
+            path: resolve(providerRoot, "skills", "upstream-contract-verification", "SKILL.md"),
+            content: await renderTemplate("skills/upstream-contract-verification/SKILL.md.tpl", {}),
+        },
+        {
+            path: resolve(providerRoot, "skills", "fixtures-and-recording", "SKILL.md"),
+            content: await renderTemplate("skills/fixtures-and-recording/SKILL.md.tpl", {}),
+        },
+        {
+            path: resolve(providerRoot, "skills", "pagination-and-counts", "SKILL.md"),
+            content: await renderTemplate("skills/pagination-and-counts/SKILL.md.tpl", {}),
+        },
+        {
+            path: resolve(providerRoot, "skills", "health-checks-and-fail-closed", "SKILL.md"),
+            content: await renderTemplate("skills/health-checks-and-fail-closed/SKILL.md.tpl", {}),
+        },
+        {
+            path: resolve(providerRoot, "skills", "upstream-notes", "README.md"),
+            content: await renderTemplate("skills/upstream-notes/README.md.tpl", {}),
+        },
     ];
     return {
         displayName: options.displayName,
@@ -434,7 +452,7 @@ export async function buildProviderCreatePlan(options, cwd) {
         validationCommands: [
             "bun run check",
             "bun run type-check",
-            "bun run submit-check",
+            "bun run submit-check -- --smoke",
             "bun run test",
         ],
         workspaceRoot: resolvedWorkspaceRoot,
@@ -461,7 +479,6 @@ function renderPackageJson(input) {
             "submit-check": "apifuse submit-check . --markdown submission-report.md",
             test: "apifuse test .",
             record: "apifuse record .",
-            "perf:sample": "apifuse perf . --operation ping --runs 3",
             start: "bun start.ts",
         },
         dependencies: {
@@ -544,8 +561,8 @@ function renderAuthBlock(authMode) {
             return `{
     mode: "credentials",
     flow: {
-      start: async () => ({
-        kind: "input",
+      start: async (_ctx) => ({
+        kind: "form",
         turnId: crypto.randomUUID(),
         expectedInput: {
           schema: {
@@ -588,7 +605,7 @@ function renderAuthBlock(authMode) {
             return `{
     mode: "oauth2",
     flow: {
-      start: async () => ({
+      start: async (_ctx) => ({
         kind: "redirect",
         turnId: crypto.randomUUID(),
         data: {
@@ -716,9 +733,7 @@ async function runCommand(command, cwd, jsonMode) {
                 resolvePromise();
                 return;
             }
-            rejectPromise(new Error(`Command failed (${command}) in ${cwd}${stdout || stderr
-                ? `\n${[stdout, stderr].filter(Boolean).join("\n")}`
-                : ""}`));
+            rejectPromise(new Error(`Command failed (${command}) in ${cwd}${stdout || stderr ? `\n${[stdout, stderr].filter(Boolean).join("\n")}` : ""}`));
         });
     });
 }
@@ -752,7 +767,7 @@ function printResult(plan, jsonMode, dryRun) {
         console.log(`Validation: (cd ${plan.providerRoot} && ${command})`);
     }
     console.log(`Next local dev: ${plan.nextDevCommand}`);
-    console.log("Submission evidence: run `bun run submit-check`, save the generated report, and note `/health` plus `POST /v1/{operation}` smoke results.");
+    console.log("Submission evidence: run `bun run submit-check -- --smoke` to archive measured `/health` and `POST /v1/{operation}` results.");
     if (plan.files.some((file) => file.content.includes('runtime: "browser"'))) {
         console.log("Browser runtime: run `bunx playwright install chromium` locally or set `APIFUSE__CDP_POOL__URL` before browser-backed smoke tests.");
     }

package/dist/cli/templates/provider/.dockerignore.tpl

@@ -0,0 +1,22 @@
+node_modules/
+.git/
+.github/
+
+# Environment and local secrets
+.env
+.env.*
+!.env.example
+
+# Local reports and generated artifacts
+submission-report.md
+coverage/
+dist/
+.cache/
+.turbo/
+.bun/
+*.tsbuildinfo
+
+# OS/editor junk
+.DS_Store
+Thumbs.db
+*.swp

package/dist/cli/templates/provider/.gitignore.tpl

@@ -0,0 +1,22 @@
+node_modules/
+
+# Environment and local secrets
+.env
+.env.*
+!.env.example
+
+# Build, coverage, cache, and local runtime artifacts
+coverage/
+dist/
+.cache/
+.turbo/
+.bun/
+*.tsbuildinfo
+
+# Bounty submission output
+submission-report.md
+
+# OS/editor junk
+.DS_Store
+Thumbs.db
+*.swp

package/dist/cli/templates/provider/AGENTS.md.tpl

@@ -0,0 +1,87 @@
+# APIFuse Provider Workspace — Agent Guide
+
+You are building an APIFuse provider. APIFuse turns messy upstream APIs into
+normalized, typed, evidence-backed public APIs. A provider that merely proxies
+the upstream is a failed provider, even if every check passes.
+
+This file is the core contract. Detailed procedures live in `skills/` — load
+the matching skill BEFORE working on that area (index at the bottom).
+
+## Non-negotiable principles
+
+### 1. Normalize, don't proxy
+Public output is an APIFuse contract, not the upstream's shape.
+- Field names: `snake_case`, semantic, English. Never leak vendor keys
+  (`dutyTel1`, `hvec`, `MKioskTy7`) into public output.
+- Timestamps: ISO 8601 in public output. Vendor formats (`20260707222855`)
+  are parsed inside mappers only. If a value cannot be parsed, omit/null it —
+  never pass the raw vendor string through.
+- Enums: normalize vendor status text/codes (`Y` / `불가능` / `정보미제공`) into a
+  declared enum. Mixed raw-text passthrough is a contract failure.
+- Units: every numeric field name states its unit (`distance_meters`), and the
+  mapper proves the conversion. Never relabel an upstream number without
+  verifying its unit against docs or live data.
+
+### 2. Fail closed, never fabricate
+- Never invent output values to satisfy a schema. Missing upstream data → null
+  field or structured error, never a plausible dummy.
+- Parse failures are errors, not defaults. Returning `0`, `[]`, or `null`
+  when the upstream shape changed hides breakage from every downstream gate.
+- If a non-empty upstream collection normalizes to zero rows, throw
+  `UPSTREAM_SCHEMA_ERROR` — silent empty success is the worst failure mode.
+- Model the upstream's real value domain. Check live data before adding
+  constraints like `nonnegative()` — some upstreams legitimately return
+  negative counts (e.g. overcapacity) and a wrong constraint silently
+  nulls real data.
+
+### 3. Preserve every input or fail loudly
+- Every accepted input must be representable in the upstream request. If it
+  isn't, reject at the schema or throw — never silently drop it.
+- Upstream parameter dependencies (param B ignored without param A) must be
+  enforced in YOUR schema. The upstream ignoring input silently is not an
+  excuse for your provider to do the same.
+
+### 4. Evidence over assumption
+- Upstream parameter names and response fields must be verified against the
+  official spec AND at least one live call. Do not guess casing or
+  underscores; do not copy from a sibling API without re-verifying.
+- No speculative field probing (`row.distance ?? row.dist ?? row.Distance`).
+  Map exactly the fields you have evidence for. One verified name per field.
+- Fixtures are recorded live evidence (`bun run record`), never hand-written.
+  Placeholder-looking values (`02-1234-5678`, "테헤란로 123") mean the fixture
+  is fabricated and the submission is not reviewable.
+- An empty result set from a dense query (0 hospitals within 5km of a city
+  center) is a request bug, not a valid fixture. Investigate before recording.
+
+### 5. Honest pagination and counts
+- If you filter rows client-side, the upstream `totalCount` is no longer your
+  `total_count`. Either expose upstream semantics honestly (documented) or
+  don't expose a total at all. A count the caller cannot page against is a lie.
+
+### 6. Health checks must detect real regressions
+- `Array.isArray(data.items)` alone can never fail. Every list operation's
+  health check must also flag the zero-rows case for a query that is known to
+  return data (dense-area query), so a broken upstream contract degrades
+  visibly instead of passing forever.
+
+## Verification loop (before every submit)
+
+```bash
+bun run check        # apifuse check + type-check
+bun run test         # your tests — cover mappers, error paths, edge rows
+bun run submit-check # structural score; a high score does NOT prove quality
+```
+
+`submit-check` is a structural gate. Every principle above can be violated
+while scoring 95/100 — reviewers and CI audit for exactly these classes.
+
+## Skill index — load before working on:
+
+| Area | Load |
+| --- | --- |
+| Output schemas, mappers, field naming, timestamps, enums | `skills/normalization-standards/SKILL.md` |
+| Upstream request params, new endpoint wiring, field mapping | `skills/upstream-contract-verification/SKILL.md` |
+| Recording fixtures, writing tests against fixtures | `skills/fixtures-and-recording/SKILL.md` |
+| List operations, paging, totals, client-side filtering | `skills/pagination-and-counts/SKILL.md` |
+| healthCheck blocks, error classification, fail-closed guards | `skills/health-checks-and-fail-closed/SKILL.md` |
+| Upstream-specific known pitfalls for THIS bounty | `skills/upstream-notes/` (read every file) |

package/dist/cli/templates/provider/CLAUDE.md.tpl

@@ -0,0 +1 @@
+@AGENTS.md

package/dist/cli/templates/provider/Dockerfile.tpl

@@ -0,0 +1,7 @@
+FROM oven/bun:1.2-alpine
+WORKDIR /provider
+COPY package.json bun.lockb* ./
+RUN bun install --frozen-lockfile
+COPY . .
+EXPOSE 3000
+CMD ["bun", "run", "start"]

package/dist/cli/templates/provider/README.md.tpl

@@ -0,0 +1,163 @@
+# {{DISPLAY_NAME}}
+
+Generated with `apifuse create`.
+
+## Commands
+
+```bash
+bun run dev
+bun run check
+bun run test
+bun run submit-check -- --smoke
+bunx apifuse perf . --operation <operation-id> --runs 3
+```
+
+
+## Module layout
+
+The generated provider uses the recommended split layout:
+
+```text
+index.ts              # composition root: defineProvider() and wiring only
+meta.ts               # provider metadata
+operations/           # APIFuse operation contracts and handlers
+schemas/              # public input/output schemas near operations
+upstream/             # upstream ceremony: clients, auth, request builders
+mappers/              # upstream-to-APIFuse normalization helpers
+domain/               # shared provider-specific business ceremony
+```
+
+Small providers may stay in one file, but larger providers are easier to
+review when `index.ts` remains a short composition root.
+
+## Pre-submission report
+
+Before posting bounty evidence, run:
+
+```bash
+bun run submit-check -- --smoke
+```
+
+This writes `submission-report.md` with a review-readiness score, blockers,
+warnings, health coverage notes, fixture/schema evidence, and remediation. A
+score is not a payout guarantee; blockers must be fixed before maintainer
+review. The generated `ping` starter intentionally warns until you replace it
+with real upstream-backed Operations. `APIFUSE__PROVIDER__*` env vars enable
+live upstream calls; without them, structured provider errors can still verify
+runtime routing. The full public-only checklist is shipped in
+`node_modules/@apifuse/provider-sdk/SUBMISSION.md`.
+
+
+## Operation guide
+
+### Parameters
+
+Starter `ping` accepts `{ "value": string }`. Replace this section with each
+real operation's input schema, required fields, formats, limits, and examples
+before submitting bounty evidence.
+
+### Response
+
+Starter `ping` returns `{ "ok": boolean, "message": string }`. Replace this
+section with the normalized response fields, units, enum values, pagination,
+and upstream caveats for each real operation.
+
+### Example
+
+```json
+{
+	"requestId": "req_local_ping",
+	"input": { "value": "hello" },
+	"headers": {}
+}
+```
+
+## Provider server contract
+
+- Dev default: `3900`
+- Start/Docker/container contract: `3000`
+- `GET /health`
+- `POST /v1/{operation}`
+- `POST /auth/start`
+- `POST /auth/continue`
+- `POST /auth/poll`
+- `POST /auth/disconnect`
+
+## Local smoke
+
+```bash
+curl -s http://localhost:3900/health
+curl -s -X POST http://localhost:3900/v1/ping \
+  -H 'Content-Type: application/json' \
+  -d '{"requestId":"req_local_ping","input":{"value":"hello"},"headers":{}}'
+```
+
+The `POST /v1/{operation}` body is a request envelope:
+
+- `requestId` is required and can be any unique local debugging string.
+- `input` contains the operation input shape.
+- `headers` is optional.
+- `connection` is optional; omit it for no-auth/public operations. For
+  credential debugging, pass `{ "id", "mode", "secrets", "metadata",
+  "externalRef" }` with local-only secret values.
+
+Structured errors return an `error` object with `code`, `message`,
+`requestId`, and optional `details`; validation failures include field paths in
+`details`, and the `apifuse dev` terminal prints a structured provider log.
+
+## Debugging checklist
+
+- `invalid_request`: include `requestId` and `input`; omit `connection` for
+  public/no-auth operations and never send `connection: null`.
+- Credentials: declare `credential.keys`, pass local-only values through
+  `connection.secrets`, and read them with `ctx.credential`.
+- Auth flow: call `/auth/start`, then `/auth/continue` with the same `flowId`;
+  carry returned `contextPatch` values into the next request's `context`.
+- Stealth/browser runtime: keep access-sensitive operations on `ctx.stealth.fetch()` with an
+  SDK stealth `profile`; the TypeScript stealth runtime uses `impit` internally.
+  `ctx.stealth` supports Chrome/Firefox-style profiles. For TypeScript browser
+  Providers or Safari-specific behavior use `browser.engine: "playwright-stealth"`
+  (`nodriver` is Python-runtime only), then install local Chromium with
+  `bunx playwright install chromium` or set `APIFUSE__CDP_POOL__URL`.
+
+## Next steps
+
+1. Replace the sample `ping` operation with real upstream logic.
+2. Once the real operation declares `upstream.baseUrl` and uses `ctx.http` or
+   `ctx.stealth`, record a fixture with:
+   `bun run record -- --operation <operation> --params '<json-input>'`.
+3. Replace the starter `healthCheckUnsupported` with a real `healthCheck` for read-only upstream operations when safe.
+4. Extend tests and operation metadata until the provider is bounty-ready.
+
+`apifuse record` is not expected to work with the generated local-only `ping`
+operation because it intentionally has no upstream response to capture.
+
+## Health-check authorship
+
+Every operation must declare exactly one of:
+
+- `healthCheck` — preferred for safe read-only upstream probes.
+- `healthCheckUnsupported` — allowed only when a probe is destructive, paid,
+  credential-sensitive, flaky by design, or otherwise unsafe. Use a specific
+  reason; reviewers reject placeholder reasons such as "TODO" or "later".
+
+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 parsed operation output. Use this shape in real operations:
+
+```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" };
+      }
+    },
+  }],
+}
+```

package/dist/cli/templates/provider/dev.ts.tpl

@@ -0,0 +1,5 @@
+import { startDevServer } from "@apifuse/provider-sdk";
+
+import provider from "./index";
+
+startDevServer(provider, { port: Number(process.env.APIFUSE__RUNTIME__PORT) || 3900 });

package/dist/cli/templates/provider/domain/README.md.tpl

@@ -0,0 +1,3 @@
+# Domain
+
+Put provider-specific business ceremony here when it is shared across operations and too complex to live inside one operation module.

package/dist/cli/templates/provider/index.test.ts.tpl

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "bun:test";
+import { runStandardTests } from "@apifuse/provider-sdk/testing";
+
+import provider from "../index";
+
+runStandardTests(provider);
+
+describe("{{PROVIDER_ID}}", () => {
+  it("exposes provider metadata from defineProvider", () => {
+    expect(provider.id).toBe("{{PROVIDER_ID}}");
+    expect(provider.reviewed).toBe("community");
+  });
+});

package/dist/cli/templates/provider/index.ts.tpl

@@ -0,0 +1,15 @@
+import { defineProvider } from "@apifuse/provider-sdk/provider";
+
+import { providerMeta } from "./meta";
+import { operations } from "./operations";
+
+export default defineProvider({
+  id: "{{PROVIDER_ID}}",
+  version: "1.0.0",
+  runtime: "{{RUNTIME}}"{{BROWSER_BLOCK}},
+  allowedHosts: ["api.example.com"],
+  reviewed: "community",
+  {{SECRETS_BLOCK}}{{CREDENTIAL_BLOCK}}auth: {{AUTH_BLOCK}},
+  meta: providerMeta,
+  operations: operations,
+});

package/dist/cli/templates/provider/mappers/README.md.tpl

@@ -0,0 +1,3 @@
+# Mappers
+
+Put normalization helpers here when upstream responses need to become public APIFuse operation outputs.

package/dist/cli/templates/provider/meta.ts.tpl

@@ -0,0 +1,7 @@
+export const providerMeta = {
+  displayName: "{{PROVIDER_ID}}",
+  displayNameKey: "meta.displayName",
+  descriptionKey: "meta.description",
+  category: "{{CATEGORY}}",
+  tags: ["{{PROVIDER_ID}}", "starter", "community"],
+} as const;

package/dist/cli/templates/provider/operations/index.ts.tpl

@@ -0,0 +1,5 @@
+import { pingOperation } from "./ping";
+
+export const operations = {
+  ping: pingOperation,
+};

package/dist/cli/templates/provider/operations/ping.ts.tpl

@@ -0,0 +1,24 @@
+import { defineOperation } from "@apifuse/provider-sdk/provider";
+
+import { pingInputSchema, pingOutputSchema } from "../schemas/ping";
+
+export const pingOperation = defineOperation({
+  descriptionKey: "operations.ping.description",
+  input: pingInputSchema,
+  output: pingOutputSchema,
+  handler: async ({{HANDLER_CTX}}, input) => {
+    {{BROWSER_HANDLER_BLOCK}}
+    return {
+      ok: true,
+      message: "{{DISPLAY_NAME}} received: " + input.value{{BROWSER_RESPONSE_FIELDS}},
+    };
+  },
+  fixtures: {
+    request: { value: "hello" },
+    response: { ok: true, message: "{{DISPLAY_NAME}} received: hello" },
+  },
+  healthCheckUnsupported: {
+    reason:
+      "Generated local-only scaffold operation. Replace this with a real healthCheck for upstream-backed bounty operations when safe; keep healthCheckUnsupported only for destructive, paid, credential-sensitive, or otherwise unprobeable operations with a specific rationale.",
+  },
+});

package/dist/cli/templates/provider/schemas/ping.ts.tpl

@@ -0,0 +1,24 @@
+import { describeKey, z } from "@apifuse/provider-sdk/provider";
+
+export const pingInputSchema = describeKey(
+  z.object({
+    value: describeKey(z.string(), "schemaDescriptions.input.value"),
+  }),
+  "schemaDescriptions.input.root",
+);
+
+export const pingOutputSchema = describeKey(
+  z.object({
+    ok: describeKey(z.boolean(), "schemaDescriptions.output.ok"),
+    message: describeKey(z.string(), "schemaDescriptions.output.message"),
+    pageTitle: describeKey(
+      z.string().optional(),
+      "schemaDescriptions.output.pageTitle",
+    ),
+    frameCount: describeKey(
+      z.number().int().nonnegative().optional(),
+      "schemaDescriptions.output.frameCount",
+    ),
+  }),
+  "schemaDescriptions.output.root",
+);

package/dist/cli/templates/provider/skills/fixtures-and-recording/SKILL.md.tpl

@@ -0,0 +1,58 @@
+---
+name: fixtures-and-recording
+description: Recording live fixtures and writing trustworthy tests from them. Load before touching __fixtures__/ or writing operation tests.
+---
+
+# Fixtures and recording
+
+Fixtures are evidence, not examples. Reviewers treat fixtures as proof your
+provider ran against the real upstream.
+
+## Recording
+- Always record from the live upstream: `bun run record -- --operation <op>
+  --params '<json>'` with the real service key configured.
+- Record queries that RETURN DATA. Choose dense/known-good inputs (major city
+  district, a real entity id from a prior list call).
+- Re-record after any request-param or mapper change; stale fixtures make
+  every downstream test meaningless.
+
+## Forbidden fixture states
+- **Hand-written fixtures.** Values like `02-1234-5678`, "테헤란로 123",
+  round-number coordinates, or sequential ids are fabrication tells. If it
+  wasn't returned by the upstream, it cannot be in `__fixtures__/`.
+- **Empty-result fixtures for dense queries.** `items: [], total_count: 0`
+  for "hospitals within 5km of Gangnam" is not a fixture — it is an
+  unfixed request bug (wrong param name/format). Investigate first.
+- **Fixtures that contradict each other.** If one operation's fixture proves
+  `total_count: 541` while returning 1 filtered row, your count semantics are
+  broken (see pagination skill), not your fixture.
+
+## Fixture shape
+`apifuse record` (`bun run record`) writes the captured RAW UPSTREAM payload
+to `__fixtures__/raw.json` (secrets sanitized). With `--append` it
+accumulates an array of raw payloads. The recorder does NOT write your
+normalized output — raw.json is upstream evidence only.
+
+Derive normalized expectations in TESTS, not in the fixture file: load the
+recorded raw payload, run your mapper over it, and assert the exact expected
+normalized rows inline in the test. If you keep expected-output snapshots,
+generate them from the mapper and review them row by row — never hand-author
+values that the upstream did not return.
+
+## Tests to derive from fixtures
+- Mapper: `map(recordedUpstreamRow)` equals the expected normalized row
+  (toEqual, not toMatchObject, for full rows — partial matching hides
+  dropped fields).
+- Edge rows: single-item object vs array (`items.item` unwrapping), missing
+  optional fields, unpadded/numeric time values, vendor error headers.
+- Error paths: upstream error `resultCode`, HTTP failure, missing secret,
+  NO_DATA — each asserts the structured `ProviderError` code.
+- Handler-level: run the operation handler against a mock ctx that returns
+  the fixture upstream body; assert the full normalized envelope.
+
+## Checklist
+- [ ] Every fixture recorded live; no placeholder-looking values
+- [ ] No empty-result fixture for a query that must have data
+- [ ] normalized expectations derived from mapper(recorded raw), not
+      hand-authored
+- [ ] Error and edge-shape rows covered, not just the happy row