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

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.1.0-beta.21
+
+- Release candidate for main commit 8124b3eb150cc7a73a86a95266b3747763a494ae.
+
 ## 2.1.0-beta.20
 
 - Release candidate for main commit 2a07cc5aef0d517c3b01d20445105f1669446bd3.

package/bin/apifuse-submit-check.ts

@@ -7,6 +7,7 @@ import { createServer } from "node:net";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
+import * as acorn from "acorn";
 import { z } from "zod";
 
 import packageJson from "../package.json";
@@ -1544,6 +1545,9 @@ function scoreRepositoryDx(providerRoot: string): SubmitCheck {
 	if (!existsSync(resolve(providerRoot, ".gitignore"))) {
 		missing.push(".gitignore");
 	}
+	if (!existsSync(resolve(providerRoot, "AGENTS.md"))) {
+		missing.push("AGENTS.md");
+	}
 
 	const packageJsonPath = resolve(providerRoot, "package.json");
 	const packageScripts = readPackageScripts(packageJsonPath);
@@ -1572,7 +1576,7 @@ function scoreRepositoryDx(providerRoot: string): SubmitCheck {
 		maxPoints: 0,
 		message: `Generated repository DX guardrails are missing: ${missing.join(", ")}.`,
 		remediation:
-			"Regenerate with the current `apifuse create` template or add .gitignore plus `type-check: tsc --noEmit` and include it from `check`.",
+			"Regenerate with the current `apifuse create` template or restore the missing files: .gitignore, AGENTS.md (agent contribution guide), plus `type-check: tsc --noEmit` included from `check`.",
 		evidence: missing,
 	};
 }
@@ -1972,6 +1976,7 @@ function scoreFixtureCoverage(provider: ProviderDefinition): SubmitCheck {
 function scoreHealthCoverage(provider: ProviderDefinition): SubmitCheck {
 	const operations = Object.entries(provider.operations);
 	const missing: string[] = [];
+	const vacuous: string[] = [];
 	const placeholder: string[] = [];
 	const unsupported: string[] = [];
 	const generatedStarter: string[] = [];
@@ -1983,6 +1988,9 @@ function scoreHealthCoverage(provider: ProviderDefinition): SubmitCheck {
 			missing.push(operationId);
 			continue;
 		}
+		if (hasCheck && !hasUnsupported && hasOnlyVacuousHealthCases(operation.healthCheck)) {
+			vacuous.push(operationId);
+		}
 		if (hasUnsupported) {
 			const reason = operation.healthCheckUnsupported?.reason ?? "";
 			unsupported.push(operationId);
@@ -2008,6 +2016,17 @@ function scoreHealthCoverage(provider: ProviderDefinition): SubmitCheck {
 		);
 	}
 
+	if (vacuous.length > 0) {
+		return blocker(
+			"health-coverage",
+			"health",
+			"One or more operations have healthCheck cases with empty assertions.",
+			`healthCheck.assertions for ${vacuous.join(", ")} is empty — assert on status and response shape (e.g. throw or return {status:'degraded'} when the upstream contract breaks), or declare healthCheckUnsupported with a specific reason if the operation genuinely cannot be probed.`,
+			CATEGORY_MAX_POINTS.health,
+			vacuous.map((operationId) => `${operationId}: empty healthCheck.assertions`),
+		);
+	}
+
 	if (placeholder.length > 0) {
 		return {
 			id: "health-coverage",
@@ -2059,6 +2078,381 @@ function scoreHealthCoverage(provider: ProviderDefinition): SubmitCheck {
 	);
 }
 
+function hasOnlyVacuousHealthCases(
+	healthCheck: ProviderDefinition["operations"][string]["healthCheck"],
+): boolean {
+	const cases = healthCheck?.cases;
+	if (!Array.isArray(cases) || cases.length === 0) {
+		return true;
+	}
+	return cases.every((healthCase) => isVacuousAssertionFunction(healthCase?.assertions));
+}
+
+function isVacuousAssertionFunction(assertions: unknown): boolean {
+	if (typeof assertions !== "function") {
+		return true;
+	}
+
+	let source: string;
+	try {
+		source = Function.prototype.toString.call(assertions);
+	} catch {
+		return false;
+	}
+
+	// Native / bound functions stringify to `function () { [native code] }` with
+	// no inspectable body or params. The underlying implementation may inspect
+	// ctx, so fail open (do not flag) rather than mistake it for an empty body.
+	if (/\[native code\]/.test(source)) {
+		return false;
+	}
+
+	const fn = parseAssertionFunction(source);
+	if (!fn) {
+		// Unparseable source → fail open (treat as a real assertion). A false
+		// negative here only misses a no-op; a false positive would wrongly
+		// reject a valid contributor.
+		return false;
+	}
+
+	// A real health assertion MUST either throw when the upstream contract
+	// breaks, or inspect the probe response, which is delivered exclusively
+	// through the assertion's own parameter(s). Working on the parsed AST (not
+	// text) makes this precise at the syntactic layer: a `throw` only counts
+	// when it is a real ThrowStatement in THIS function's body (not inside a
+	// nested, uninvoked function), and a parameter reference is checked against
+	// the actual bound names (destructuring binds the local alias, not the
+	// property key). This closes the whole equivalent-no-op class — empty
+	// bodies, `void 0`, `({})`, `Promise.resolve()`, `await Promise.resolve()`,
+	// `.then()`, `new Promise(r => r())`, side-effect-only bodies, throws hidden
+	// in uninvoked closures — without enumerating spellings.
+	if (functionThrows(fn)) {
+		return false;
+	}
+	const bound = new Set<string>();
+	for (const param of fn.params) {
+		collectBoundNames(param, bound);
+	}
+	if (bound.size === 0) {
+		return true;
+	}
+	// A parameter reference anywhere in the (reachable) body is treated as
+	// inspecting the response. This is deliberately syntactic, not a dataflow
+	// analysis.
+	//
+	// KNOWN LIMITATION (accepted): a body that reads the parameter but never
+	// turns that read into an outcome — no throw, no returned verdict — still
+	// passes, e.g. `({ status }) => { console.info(status); }`. Precisely
+	// rejecting it would require tracking whether the read flows to a throw
+	// argument or return value through arbitrary local bindings and invoked
+	// helpers (`const ok = ctx.output.ok; return ok ? ...` / a called helper that
+	// throws). That is transitive use-def dataflow, and an imprecise version
+	// FALSE-BLOCKS real assertions of exactly those shapes — verified
+	// empirically. Under the fail-open contract (rejecting a real contributor is
+	// strictly worse than missing a no-op) we accept the miss here. This gate
+	// stops accidental/lazy no-ops (empty bodies, `void 0`, `Promise.resolve()`,
+	// throws in uninvoked closures); a determined bypass via a decorative ctx
+	// read is no easier than writing the real one-line `throw`, and the actual
+	// defense against a runtime-empty assertion is the live `--smoke` probe.
+	return !referencesBoundNames(fn, bound);
+}
+
+type AssertionFunctionNode =
+	| acorn.ArrowFunctionExpression
+	| acorn.FunctionExpression
+	| acorn.FunctionDeclaration;
+
+function isFunctionNode(node: acorn.AnyNode): node is AssertionFunctionNode {
+	return (
+		node.type === "ArrowFunctionExpression" ||
+		node.type === "FunctionExpression" ||
+		node.type === "FunctionDeclaration"
+	);
+}
+
+/**
+ * Parse the `Function.prototype.toString()` output of an assertion into its AST
+ * function node. The stringified form can be an arrow (`(a) => {}`), a function
+ * expression (`function (a) {}`), or a bare method (`foo() {}`), so try a few
+ * wrappers until one parses. Returns undefined on any parse failure so callers
+ * fail open.
+ */
+function parseAssertionFunction(source: string): AssertionFunctionNode | undefined {
+	const candidates = [source, `(${source})`, `({${source}})`];
+	for (const candidate of candidates) {
+		let program: acorn.Program;
+		try {
+			program = acorn.parse(candidate, { ecmaVersion: "latest" });
+		} catch {
+			continue;
+		}
+		const fn = findFirstFunction(program);
+		if (fn) {
+			return fn;
+		}
+	}
+	return undefined;
+}
+
+/** Depth-first search for the first function node in a parsed program. */
+function findFirstFunction(root: acorn.AnyNode): AssertionFunctionNode | undefined {
+	let found: AssertionFunctionNode | undefined;
+	walkAst(root, (node) => {
+		if (found) {
+			return false;
+		}
+		if (isFunctionNode(node)) {
+			found = node;
+			return false;
+		}
+		return true;
+	});
+	return found;
+}
+
+/**
+ * Collect the identifier names actually BOUND by a parameter pattern. For
+ * destructuring, the binding is the local target (`value`), not the source
+ * property key — so `({ status: ignored })` binds `ignored`, and a body that
+ * merely mentions `status` is not referencing a parameter.
+ */
+function collectBoundNames(pattern: acorn.Pattern | null, out: Set<string>): void {
+	if (!pattern) {
+		return;
+	}
+	switch (pattern.type) {
+		case "Identifier":
+			out.add(pattern.name);
+			break;
+		case "AssignmentPattern":
+			collectBoundNames(pattern.left, out);
+			break;
+		case "RestElement":
+			collectBoundNames(pattern.argument, out);
+			break;
+		case "ArrayPattern":
+			for (const element of pattern.elements) {
+				collectBoundNames(element, out);
+			}
+			break;
+		case "ObjectPattern":
+			for (const property of pattern.properties) {
+				if (property.type === "RestElement") {
+					collectBoundNames(property.argument, out);
+				} else {
+					// `.value` is the local binding target, `.key` is the source
+					// property name — bind only the former.
+					collectBoundNames(property.value, out);
+				}
+			}
+			break;
+	}
+}
+
+/**
+ * True if the function contains a real `throw` statement in ITS OWN body —
+ * descending through control flow but NOT into nested functions, whose throws
+ * do not execute unless that nested function is invoked.
+ */
+function functionThrows(fn: AssertionFunctionNode): boolean {
+	if (fn.body.type !== "BlockStatement") {
+		// Concise arrow returning an expression cannot contain a throw statement.
+		return false;
+	}
+	let throws = false;
+	walkAst(fn.body, (node) => {
+		if (throws) {
+			return false;
+		}
+		if (node.type === "ThrowStatement") {
+			throws = true;
+			return false;
+		}
+		// Do not descend into nested function bodies.
+		if (isFunctionNode(node)) {
+			return false;
+		}
+		return true;
+	});
+	return throws;
+}
+
+/**
+ * True if the function's body references any of the given bound parameter names
+ * as an actual value. Property KEYS (`{ status: ... }`, `obj.status`) are not
+ * references; computed members (`obj[status]`) are. Nested functions that
+ * re-bind the same name shadow it, so their bodies are searched with the
+ * shadowed name removed from the target set.
+ */
+function referencesBoundNames(fn: AssertionFunctionNode, bound: Set<string>): boolean {
+	if (bound.size === 0) {
+		return false;
+	}
+	let referenced = false;
+	walkAstValues(fn.body, bound, fn.body, null, null, () => {
+		referenced = true;
+	});
+	return referenced;
+}
+
+/**
+ * Walk `node`, invoking `onReference` when an Identifier in value position
+ * matches a name in `names`. Skips property keys and non-computed member
+ * properties. On entering a nested function, removes any parameter names it
+ * rebinds (shadowing) from the active set for that subtree, and does NOT descend
+ * into a PROVABLY-UNINVOKED helper — a function bound to a local name that is
+ * never referenced again anywhere in the assertion body, so it cannot run when
+ * the assertion runs (e.g. `(ctx) => { const later = () => ctx.status; }`). Its
+ * parameter reads therefore must not count as inspecting the response, mirroring
+ * how `functionThrows` ignores throws inside nested functions.
+ *
+ * Crucially, a helper that IS referenced again (a call site like `check()`) is
+ * NOT skipped — its body is searched — so real assertions that factor the check
+ * into a local helper still pass. Immediately-invoked callbacks (`.every(cb)`,
+ * IIFEs, callees) are likewise searched. When in doubt we descend (fail open):
+ * the only skip is a helper we can prove is never invoked.
+ */
+function walkAstValues(
+	node: acorn.AnyNode,
+	names: Set<string>,
+	outerBody: acorn.AnyNode,
+	parent: acorn.AnyNode | null,
+	parentKey: string | null,
+	onReference: () => void,
+): void {
+	if (names.size === 0) {
+		return;
+	}
+	if (node.type === "Identifier") {
+		if (names.has(node.name)) {
+			onReference();
+		}
+		return;
+	}
+	// Nested function: subtract its own parameter bindings (shadowing) before
+	// descending into its body — and skip it only when it is a provably
+	// uninvoked helper.
+	if (isFunctionNode(node)) {
+		const shadowed = new Set<string>();
+		for (const param of node.params) {
+			collectBoundNames(param, shadowed);
+		}
+		const visible = new Set<string>();
+		for (const name of names) {
+			if (!shadowed.has(name)) {
+				visible.add(name);
+			}
+		}
+		if (visible.size === 0 || isProvablyUninvokedHelper(node, parent, parentKey, outerBody)) {
+			return;
+		}
+		for (const [key, child] of childEntries(node)) {
+			if (key === "params") {
+				continue;
+			}
+			walkAstValues(child, visible, outerBody, node, key, onReference);
+		}
+		return;
+	}
+	for (const [key, child] of childEntries(node)) {
+		// Skip non-computed property keys (`{ status: x }`) and member
+		// properties (`obj.status`) — these are names, not references.
+		if (key === "key" && node.type === "Property" && !node.computed) {
+			continue;
+		}
+		if (key === "property" && node.type === "MemberExpression" && !node.computed) {
+			continue;
+		}
+		walkAstValues(child, names, outerBody, node, key, onReference);
+	}
+}
+
+/**
+ * True if `fn` is a local helper bound to a name that is NEVER referenced again
+ * anywhere in `outerBody` — meaning it is never invoked, so its body does not run
+ * as part of evaluating the assertion. Only these provably-dead helpers are
+ * skipped; a helper with any call site (its name appearing more than once, i.e.
+ * beyond its own declaration) is treated as potentially executed and searched.
+ * Anonymous functions in expression position (call args, callees, returns) are
+ * never "uninvoked helpers" — they may run — so they are not skipped here.
+ */
+function isProvablyUninvokedHelper(
+	fn: AssertionFunctionNode,
+	parent: acorn.AnyNode | null,
+	parentKey: string | null,
+	outerBody: acorn.AnyNode,
+): boolean {
+	let helperName: string | undefined;
+	if (fn.type === "FunctionDeclaration" && fn.id) {
+		helperName = fn.id.name;
+	} else if (
+		parent &&
+		parent.type === "VariableDeclarator" &&
+		parentKey === "init" &&
+		parent.id.type === "Identifier"
+	) {
+		helperName = parent.id.name;
+	}
+	if (helperName === undefined) {
+		// Not a name-bound helper (anonymous callback / expression). It may run,
+		// so do not skip it.
+		return false;
+	}
+	// Count every occurrence of the helper name in the assertion body. Exactly
+	// one occurrence is its own binding declaration; more than one means there is
+	// at least one reference (call site), so the helper can run.
+	let occurrences = 0;
+	walkAst(outerBody, (node) => {
+		if (node.type === "Identifier" && node.name === helperName) {
+			occurrences += 1;
+		}
+		return true;
+	});
+	return occurrences <= 1;
+}
+
+/** Generic pre-order AST walk; `visit` returns false to stop descending. */
+function walkAst(node: acorn.AnyNode, visit: (node: acorn.AnyNode) => boolean): void {
+	if (!visit(node)) {
+		return;
+	}
+	for (const child of childNodes(node)) {
+		walkAst(child, visit);
+	}
+}
+
+function* childNodes(node: acorn.AnyNode): Generator<acorn.AnyNode> {
+	for (const [, child] of childEntries(node)) {
+		yield child;
+	}
+}
+
+function* childEntries(node: acorn.AnyNode): Generator<[string, acorn.AnyNode]> {
+	for (const key of Object.keys(node)) {
+		if (key === "type" || key === "start" || key === "end" || key === "loc" || key === "range") {
+			continue;
+		}
+		const value = (node as unknown as Record<string, unknown>)[key];
+		if (Array.isArray(value)) {
+			for (const item of value) {
+				if (isAstNode(item)) {
+					yield [key, item];
+				}
+			}
+		} else if (isAstNode(value)) {
+			yield [key, value];
+		}
+	}
+}
+
+function isAstNode(value: unknown): value is acorn.AnyNode {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		typeof (value as { type?: unknown }).type === "string"
+	);
+}
+
 function scoreSmoke(
 	smokeResult: SmokeResult | undefined,
 	smokeNote: string | undefined,

package/dist/cli/create.js

@@ -405,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,

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/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

package/dist/cli/templates/provider/skills/health-checks-and-fail-closed/SKILL.md.tpl

@@ -0,0 +1,65 @@
+---
+name: health-checks-and-fail-closed
+description: Writing health checks that can actually fail, and fail-closed guards at envelope and row level. Load before writing healthCheck blocks or error handling.
+---
+
+# Health checks and fail-closed guards
+
+## Health checks that can actually fail
+`Array.isArray(data.items)` alone can never fail. Every list operation's
+health check must be able to detect the zero-rows regression.
+
+Assertion contract (per SDK `HealthCheckCase`): THROW to fail the case
+(recorded as `down`); return `{ status: "degraded", label }` to flag without
+failing; return nothing for `ok`. There is no `"down"` return value.
+
+```ts
+assertions: ({ status, data }) => {
+  if (status !== 200) {
+    throw new Error(`<op> request failed with status ${status}`);
+  }
+  if (!Array.isArray(data.items)) {
+    throw new Error("<op> missing items array");
+  }
+  // Dense query MUST return rows; zero rows = upstream contract drift
+  if (data.items.length === 0) {
+    return { status: "degraded", label: "<op> dense query returned 0 rows" };
+  }
+}
+```
+
+- Choose health-check inputs that are guaranteed-dense (major city district,
+  a stable well-known entity id). Verify the id still exists when picking it.
+- Also assert one semantic field on the first row (e.g. `items[0].name` is a
+  non-empty string) so a mapper regression that empties fields degrades too.
+
+## Fail-closed: envelope level
+- Upstream error headers/codes → structured `ProviderError` with a stable
+  `code` (`UPSTREAM_AUTH_ERROR`, `UPSTREAM_ERROR`, `NO_DATA`, ...).
+- Non-JSON body, unexpected content type → `UPSTREAM_SCHEMA_ERROR`.
+- HTTP non-2xx → classified error; never a fake empty success envelope.
+  Fixture-based tests cannot catch swallowed errors — write an explicit test:
+  mock a non-ok response and assert the handler REJECTS.
+
+## Fail-closed: row level
+Envelope guards are not enough. The silent killer is: response is valid,
+array is non-empty, but every row normalizes to nothing.
+- If a non-empty upstream collection produces zero normalized rows, throw
+  `UPSTREAM_SCHEMA_ERROR` instead of returning `items: []`.
+- Identity fields (id, name) missing on a row → throw, don't skip the row
+  silently.
+- Regression-test both layers separately: a bad envelope AND a good envelope
+  with unmappable rows.
+
+## Error message hygiene
+`ProviderError.message` reaches the tenant verbatim. Never interpolate
+upstream free text that may contain personal data (names, phone numbers,
+addresses); allowlist known code tokens and keep raw bodies in server-side
+details/logs only.
+
+## Checklist
+- [ ] Every list op health check flags 0 rows on a dense query
+- [ ] One semantic field asserted on a real row
+- [ ] Swallowed-error test exists (non-ok mock → handler rejects)
+- [ ] Non-empty upstream → zero normalized rows throws
+- [ ] No upstream free text in customer-facing error messages

package/dist/cli/templates/provider/skills/normalization-standards/SKILL.md.tpl

@@ -0,0 +1,57 @@
+---
+name: normalization-standards
+description: Public output contract rules — field naming, timestamps, enums, units, nullability. Load before writing or editing any output schema or mapper.
+---
+
+# Normalization standards
+
+Public output is the product. Apply these to every schema + mapper pair.
+
+## Field naming
+- `snake_case`, English, semantic. `emergency_phone`, not `dutyTel3`.
+- Never expose vendor key vocabularies (`hv1`..`hv12`, `MKioskTy*`, `duty*`)
+  as public field names OR as dynamic record keys. A
+  `z.record(z.string(), ...)` keyed by vendor codes is still a vendor leak —
+  map codes to a stable public vocabulary (enum keys or an array of
+  `{ code, label, status }` objects with normalized status).
+
+## Timestamps and dates
+- Public: ISO 8601 (`2026-07-07T22:28:55+09:00`, dates `2026-07-07`,
+  clock times `HH:MM`). Include the upstream's timezone offset; Korean public
+  APIs are KST (+09:00) — verify, then encode it.
+- Vendor formats (`YYYYMMDDHHmmss`, `HHmm`, unpadded `900`) are parsed inside
+  the mapper. Unparseable → `null`, plus a test for that row shape.
+- Never emit a raw vendor timestamp string in public output, including
+  fixtures.
+
+## Enums
+- Vendor status values (codes, `Y`/`N`, Korean labels like `불가능`,
+  `정보미제공`) → declared `z.enum`. Unknown value → explicit `unknown` member
+  or fail closed; never pass raw text through.
+- Map from the OFFICIAL code table, not from guessing what live samples mean.
+  Add a regression test per enum member.
+
+## Numbers and units
+- Field name states the unit: `distance_meters`, `radius_meters`,
+  `price_krw`. Mapper proves the conversion (upstream km → `* 1000`).
+- Verify the upstream unit from spec or live-data sanity check (a "distance"
+  of `1.2` from a nearby search is km, not meters). Sibling endpoints of the
+  same vendor may differ — verify each one.
+- Value-domain constraints (`nonnegative`, `min`, `max`) must reflect the
+  upstream's REAL domain observed in live data, not what seems sensible.
+  A wrong `nonnegative()` turns real negative values into `null`/errors
+  silently.
+
+## Nullability
+- `null` means "upstream did not provide it" — never "parsing failed" and
+  never a placeholder for invented data.
+- Required-for-identity fields (ids, names) missing → throw
+  `UPSTREAM_SCHEMA_ERROR`; do not emit partial rows.
+
+## Checklist before submitting a schema/mapper change
+- [ ] No vendor key visible in any public field name or record key
+- [ ] All timestamps ISO 8601 with timezone; parsing tested for real vendor
+      shapes (padded/unpadded, string/number)
+- [ ] All status-like strings are declared enums with official-table mapping
+- [ ] Every numeric field's unit is in its name and conversion is tested
+- [ ] Constraints checked against live data, not intuition

package/dist/cli/templates/provider/skills/pagination-and-counts/SKILL.md.tpl

@@ -0,0 +1,52 @@
+---
+name: pagination-and-counts
+description: total_count semantics, client-side filtering, and paging honesty. Load before implementing any list/search operation.
+---
+
+# Pagination and counts
+
+A caller uses `total_count`, `page`, and `limit` to plan iteration. If those
+numbers don't describe what the caller can actually page through, the
+operation is lying.
+
+## The client-side filtering trap
+If the upstream has no server-side filter for one of your inputs (e.g. no
+radius param) and you filter rows after fetching:
+
+- Upstream `totalCount` counts UNFILTERED rows. Returning it as your
+  `total_count` while returning filtered rows means: caller sees
+  `total_count: 541`, gets 1 row on page 1, and pages 2..28 return rows that
+  are outside the filter or empty. This is a contract failure, not a nuance.
+
+Acceptable resolutions, in preference order:
+1. **Don't accept the input.** If the upstream can't filter by it and you
+   can't enumerate all pages, drop the input from the schema and document the
+   upstream's real semantics (e.g. "results are distance-sorted; no radius
+   cutoff").
+2. **Expose upstream semantics honestly.** Distance-sorted paging with a
+   documented "no radius filter" contract and no fake `radius` input.
+3. **Filter AND fix the metadata.** If you must filter client-side, do not
+   return the upstream total. Return only what you can prove (`returned_count`
+   plus a `has_more` you can actually compute) and document that totals are
+   unavailable.
+
+Never combine: accepted filter input + client-side filter + upstream total.
+
+## Count integrity
+- Parse failure of `totalCount` → `UPSTREAM_SCHEMA_ERROR`, not `0`.
+  A fail-open zero disguises upstream drift as an empty dataset.
+- If `total_count > 0` but the page's row array normalizes to empty on
+  page 1, throw — that combination means broken extraction, not empty data.
+
+## Page/limit echo
+- Echo the EFFECTIVE values: if you clamp `limit` to the upstream max, return
+  the clamped value, not the requested one.
+- `page`/`limit` semantics must match the upstream's paging model
+  (1-indexed vs 0-indexed) — verify with two live pages, checking the
+  returned rows actually differ.
+
+## Checklist
+- [ ] No input is filtered client-side while `total_count` comes from upstream
+- [ ] totalCount parse failure fails closed
+- [ ] Effective (clamped) limit echoed
+- [ ] Two-page live check proves paging advances

package/dist/cli/templates/provider/skills/upstream-contract-verification/SKILL.md.tpl

@@ -0,0 +1,45 @@
+---
+name: upstream-contract-verification
+description: How to establish evidence for upstream request params and response fields before coding. Load before wiring any new endpoint or mapping new fields.
+---
+
+# Upstream contract verification
+
+Most provider P0s come from guessed upstream contracts. Every param name and
+response field needs evidence BEFORE it ships.
+
+## Request parameters
+1. Start from the official spec document (data.go.kr 활용가이드, vendor API
+   docs). Copy exact names — casing and underscores matter
+   (`WGS84_LAT` ≠ `WGS84LAT`; the wrong one is often silently ignored).
+2. Confirm with ONE live call per endpoint. A param being ignored does not
+   produce an error — it produces plausible-looking wrong results, so compare:
+   - filtered vs unfiltered `totalCount` (identical → param ignored)
+   - a dense-area query returning 0 rows (→ param name/format wrong)
+3. Do NOT copy param names from a sibling endpoint or sibling API of the same
+   vendor without re-verifying. Same vendor ≠ same contract; endpoints drift.
+4. If a param only works together with another param (district requires
+   province), encode that dependency in the input schema with a clear error.
+   Test it: dependent-param-alone must be rejected, not silently national.
+
+## Response fields
+- Map exactly the field names present in your recorded live fixtures.
+- No speculative fallback chains (`row.distance ?? row.dist ?? row.Distance`).
+  If two shapes genuinely exist, you need a recorded fixture proving EACH
+  branch plus a row-level test per branch; otherwise map one name only.
+- Field presence varies by endpoint within the same vendor. Detail endpoints
+  often return more/differently-named fields than list endpoints — record
+  fixtures per endpoint, not per vendor.
+
+## When results look wrong
+- Same response body across different request payloads → the upstream is
+  ignoring your variation; stop tuning fields and re-check param names/auth.
+- Empty result for a query that must have data (city-center radius search,
+  major-district listing) → treat as a request bug. Never record it as a
+  fixture and never ship it.
+
+## Deliverables per endpoint
+- [ ] Spec reference (URL or doc name + section) noted in the PR/commit
+- [ ] One recorded live fixture proving request params take effect
+- [ ] Negative evidence checked: filtered count differs from unfiltered
+- [ ] Param dependencies enforced in the input schema with tests

package/dist/cli/templates/provider/skills/upstream-notes/README.md.tpl

@@ -0,0 +1,13 @@
+# Upstream notes
+
+Per-vendor / per-API-family pitfalls proven by live evidence. These are the
+highest-value files in this workspace: general principles are knowable, but
+"this API silently ignores param X" is only discoverable by getting burned.
+
+- Read EVERY file here before your first upstream call.
+- When you discover a new upstream quirk (silently ignored param, unit
+  surprise, undocumented value domain, error-shape oddity), ADD it here in
+  the same format — evidence line included. Reviewers treat contributed
+  upstream notes as part of submission quality.
+
+Format per entry: **Symptom → Cause → Rule → Evidence**.

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.1.0-beta.20",
+	"version": "2.1.0-beta.21",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -88,6 +88,7 @@
 	"dependencies": {
 		"@clack/prompts": "^1.5.1",
 		"@types/ms": "^2.1.0",
+		"acorn": "^8.17.0",
 		"ajv": "^8.17",
 		"hono": "^4.12.25",
 		"impit": "0.14.1",

package/src/cli/create.ts

@@ -538,6 +538,38 @@ export async function buildProviderCreatePlan(
 				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 {

package/src/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/src/cli/templates/provider/CLAUDE.md.tpl

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

package/src/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

package/src/cli/templates/provider/skills/health-checks-and-fail-closed/SKILL.md.tpl

@@ -0,0 +1,65 @@
+---
+name: health-checks-and-fail-closed
+description: Writing health checks that can actually fail, and fail-closed guards at envelope and row level. Load before writing healthCheck blocks or error handling.
+---
+
+# Health checks and fail-closed guards
+
+## Health checks that can actually fail
+`Array.isArray(data.items)` alone can never fail. Every list operation's
+health check must be able to detect the zero-rows regression.
+
+Assertion contract (per SDK `HealthCheckCase`): THROW to fail the case
+(recorded as `down`); return `{ status: "degraded", label }` to flag without
+failing; return nothing for `ok`. There is no `"down"` return value.
+
+```ts
+assertions: ({ status, data }) => {
+  if (status !== 200) {
+    throw new Error(`<op> request failed with status ${status}`);
+  }
+  if (!Array.isArray(data.items)) {
+    throw new Error("<op> missing items array");
+  }
+  // Dense query MUST return rows; zero rows = upstream contract drift
+  if (data.items.length === 0) {
+    return { status: "degraded", label: "<op> dense query returned 0 rows" };
+  }
+}
+```
+
+- Choose health-check inputs that are guaranteed-dense (major city district,
+  a stable well-known entity id). Verify the id still exists when picking it.
+- Also assert one semantic field on the first row (e.g. `items[0].name` is a
+  non-empty string) so a mapper regression that empties fields degrades too.
+
+## Fail-closed: envelope level
+- Upstream error headers/codes → structured `ProviderError` with a stable
+  `code` (`UPSTREAM_AUTH_ERROR`, `UPSTREAM_ERROR`, `NO_DATA`, ...).
+- Non-JSON body, unexpected content type → `UPSTREAM_SCHEMA_ERROR`.
+- HTTP non-2xx → classified error; never a fake empty success envelope.
+  Fixture-based tests cannot catch swallowed errors — write an explicit test:
+  mock a non-ok response and assert the handler REJECTS.
+
+## Fail-closed: row level
+Envelope guards are not enough. The silent killer is: response is valid,
+array is non-empty, but every row normalizes to nothing.
+- If a non-empty upstream collection produces zero normalized rows, throw
+  `UPSTREAM_SCHEMA_ERROR` instead of returning `items: []`.
+- Identity fields (id, name) missing on a row → throw, don't skip the row
+  silently.
+- Regression-test both layers separately: a bad envelope AND a good envelope
+  with unmappable rows.
+
+## Error message hygiene
+`ProviderError.message` reaches the tenant verbatim. Never interpolate
+upstream free text that may contain personal data (names, phone numbers,
+addresses); allowlist known code tokens and keep raw bodies in server-side
+details/logs only.
+
+## Checklist
+- [ ] Every list op health check flags 0 rows on a dense query
+- [ ] One semantic field asserted on a real row
+- [ ] Swallowed-error test exists (non-ok mock → handler rejects)
+- [ ] Non-empty upstream → zero normalized rows throws
+- [ ] No upstream free text in customer-facing error messages

package/src/cli/templates/provider/skills/normalization-standards/SKILL.md.tpl

@@ -0,0 +1,57 @@
+---
+name: normalization-standards
+description: Public output contract rules — field naming, timestamps, enums, units, nullability. Load before writing or editing any output schema or mapper.
+---
+
+# Normalization standards
+
+Public output is the product. Apply these to every schema + mapper pair.
+
+## Field naming
+- `snake_case`, English, semantic. `emergency_phone`, not `dutyTel3`.
+- Never expose vendor key vocabularies (`hv1`..`hv12`, `MKioskTy*`, `duty*`)
+  as public field names OR as dynamic record keys. A
+  `z.record(z.string(), ...)` keyed by vendor codes is still a vendor leak —
+  map codes to a stable public vocabulary (enum keys or an array of
+  `{ code, label, status }` objects with normalized status).
+
+## Timestamps and dates
+- Public: ISO 8601 (`2026-07-07T22:28:55+09:00`, dates `2026-07-07`,
+  clock times `HH:MM`). Include the upstream's timezone offset; Korean public
+  APIs are KST (+09:00) — verify, then encode it.
+- Vendor formats (`YYYYMMDDHHmmss`, `HHmm`, unpadded `900`) are parsed inside
+  the mapper. Unparseable → `null`, plus a test for that row shape.
+- Never emit a raw vendor timestamp string in public output, including
+  fixtures.
+
+## Enums
+- Vendor status values (codes, `Y`/`N`, Korean labels like `불가능`,
+  `정보미제공`) → declared `z.enum`. Unknown value → explicit `unknown` member
+  or fail closed; never pass raw text through.
+- Map from the OFFICIAL code table, not from guessing what live samples mean.
+  Add a regression test per enum member.
+
+## Numbers and units
+- Field name states the unit: `distance_meters`, `radius_meters`,
+  `price_krw`. Mapper proves the conversion (upstream km → `* 1000`).
+- Verify the upstream unit from spec or live-data sanity check (a "distance"
+  of `1.2` from a nearby search is km, not meters). Sibling endpoints of the
+  same vendor may differ — verify each one.
+- Value-domain constraints (`nonnegative`, `min`, `max`) must reflect the
+  upstream's REAL domain observed in live data, not what seems sensible.
+  A wrong `nonnegative()` turns real negative values into `null`/errors
+  silently.
+
+## Nullability
+- `null` means "upstream did not provide it" — never "parsing failed" and
+  never a placeholder for invented data.
+- Required-for-identity fields (ids, names) missing → throw
+  `UPSTREAM_SCHEMA_ERROR`; do not emit partial rows.
+
+## Checklist before submitting a schema/mapper change
+- [ ] No vendor key visible in any public field name or record key
+- [ ] All timestamps ISO 8601 with timezone; parsing tested for real vendor
+      shapes (padded/unpadded, string/number)
+- [ ] All status-like strings are declared enums with official-table mapping
+- [ ] Every numeric field's unit is in its name and conversion is tested
+- [ ] Constraints checked against live data, not intuition

package/src/cli/templates/provider/skills/pagination-and-counts/SKILL.md.tpl

@@ -0,0 +1,52 @@
+---
+name: pagination-and-counts
+description: total_count semantics, client-side filtering, and paging honesty. Load before implementing any list/search operation.
+---
+
+# Pagination and counts
+
+A caller uses `total_count`, `page`, and `limit` to plan iteration. If those
+numbers don't describe what the caller can actually page through, the
+operation is lying.
+
+## The client-side filtering trap
+If the upstream has no server-side filter for one of your inputs (e.g. no
+radius param) and you filter rows after fetching:
+
+- Upstream `totalCount` counts UNFILTERED rows. Returning it as your
+  `total_count` while returning filtered rows means: caller sees
+  `total_count: 541`, gets 1 row on page 1, and pages 2..28 return rows that
+  are outside the filter or empty. This is a contract failure, not a nuance.
+
+Acceptable resolutions, in preference order:
+1. **Don't accept the input.** If the upstream can't filter by it and you
+   can't enumerate all pages, drop the input from the schema and document the
+   upstream's real semantics (e.g. "results are distance-sorted; no radius
+   cutoff").
+2. **Expose upstream semantics honestly.** Distance-sorted paging with a
+   documented "no radius filter" contract and no fake `radius` input.
+3. **Filter AND fix the metadata.** If you must filter client-side, do not
+   return the upstream total. Return only what you can prove (`returned_count`
+   plus a `has_more` you can actually compute) and document that totals are
+   unavailable.
+
+Never combine: accepted filter input + client-side filter + upstream total.
+
+## Count integrity
+- Parse failure of `totalCount` → `UPSTREAM_SCHEMA_ERROR`, not `0`.
+  A fail-open zero disguises upstream drift as an empty dataset.
+- If `total_count > 0` but the page's row array normalizes to empty on
+  page 1, throw — that combination means broken extraction, not empty data.
+
+## Page/limit echo
+- Echo the EFFECTIVE values: if you clamp `limit` to the upstream max, return
+  the clamped value, not the requested one.
+- `page`/`limit` semantics must match the upstream's paging model
+  (1-indexed vs 0-indexed) — verify with two live pages, checking the
+  returned rows actually differ.
+
+## Checklist
+- [ ] No input is filtered client-side while `total_count` comes from upstream
+- [ ] totalCount parse failure fails closed
+- [ ] Effective (clamped) limit echoed
+- [ ] Two-page live check proves paging advances

package/src/cli/templates/provider/skills/upstream-contract-verification/SKILL.md.tpl

@@ -0,0 +1,45 @@
+---
+name: upstream-contract-verification
+description: How to establish evidence for upstream request params and response fields before coding. Load before wiring any new endpoint or mapping new fields.
+---
+
+# Upstream contract verification
+
+Most provider P0s come from guessed upstream contracts. Every param name and
+response field needs evidence BEFORE it ships.
+
+## Request parameters
+1. Start from the official spec document (data.go.kr 활용가이드, vendor API
+   docs). Copy exact names — casing and underscores matter
+   (`WGS84_LAT` ≠ `WGS84LAT`; the wrong one is often silently ignored).
+2. Confirm with ONE live call per endpoint. A param being ignored does not
+   produce an error — it produces plausible-looking wrong results, so compare:
+   - filtered vs unfiltered `totalCount` (identical → param ignored)
+   - a dense-area query returning 0 rows (→ param name/format wrong)
+3. Do NOT copy param names from a sibling endpoint or sibling API of the same
+   vendor without re-verifying. Same vendor ≠ same contract; endpoints drift.
+4. If a param only works together with another param (district requires
+   province), encode that dependency in the input schema with a clear error.
+   Test it: dependent-param-alone must be rejected, not silently national.
+
+## Response fields
+- Map exactly the field names present in your recorded live fixtures.
+- No speculative fallback chains (`row.distance ?? row.dist ?? row.Distance`).
+  If two shapes genuinely exist, you need a recorded fixture proving EACH
+  branch plus a row-level test per branch; otherwise map one name only.
+- Field presence varies by endpoint within the same vendor. Detail endpoints
+  often return more/differently-named fields than list endpoints — record
+  fixtures per endpoint, not per vendor.
+
+## When results look wrong
+- Same response body across different request payloads → the upstream is
+  ignoring your variation; stop tuning fields and re-check param names/auth.
+- Empty result for a query that must have data (city-center radius search,
+  major-district listing) → treat as a request bug. Never record it as a
+  fixture and never ship it.
+
+## Deliverables per endpoint
+- [ ] Spec reference (URL or doc name + section) noted in the PR/commit
+- [ ] One recorded live fixture proving request params take effect
+- [ ] Negative evidence checked: filtered count differs from unfiltered
+- [ ] Param dependencies enforced in the input schema with tests

package/src/cli/templates/provider/skills/upstream-notes/README.md.tpl

@@ -0,0 +1,13 @@
+# Upstream notes
+
+Per-vendor / per-API-family pitfalls proven by live evidence. These are the
+highest-value files in this workspace: general principles are knowable, but
+"this API silently ignores param X" is only discoverable by getting burned.
+
+- Read EVERY file here before your first upstream call.
+- When you discover a new upstream quirk (silently ignored param, unit
+  surprise, undocumented value domain, error-shape oddity), ADD it here in
+  the same format — evidence line included. Reviewers treat contributed
+  upstream notes as part of submission quality.
+
+Format per entry: **Symptom → Cause → Rule → Evidence**.