chore(specs): vendor the spec repos we own, add AGENTS.md

[Mkassabov]

Two changes that belong together: the contributor guide says where specs live, so the specs should live somewhere worth documenting.

AGENTS.md

The load-bearing section is never edit generated files. Nearly everything under packages/*/src/services/ is compiler output — committed so consumers don't run codegen, not because it's source — and an edit there is silently reverted by the next bun run generate. It maps each kind of change to the thing that actually produces it:

You want to change	Edit
One shape/member/route in one provider	packages/<pkg>/patches/**
Emitted code shape for all providers	packages/core/src/codegen/**
One provider's emission rules	that package's SdkSpec
The upstream API surface	the spec under packages/<pkg>/specs/**

Plus: how to add a new SDK, when to use a manual spec, and the noCheck: true trap — a plain tsc -b and all editor IntelliSense only emit, so only bun run typecheck:ci proves a type change works.

Vendored specs

The eight alchemy-run/distilled-spec-* repos exist only to hold one spec and a script that refetches it. Splitting them out bought nothing: a spec bump and the SDK regeneration it forces are one change, and submodules made that two commits across two repos.

Seven are folded in:

packages/<pkg>/specs/distilled-spec-<pkg>/specs/openapi.json
  -> packages/<pkg>/specs/openapi.json
packages/<pkg>/specs/distilled-spec-<pkg>/.meta/fetch-specs.ts
  -> packages/<pkg>/scripts/fetch-specs.ts

specs:fetch drops git submodule update … for bun scripts/fetch-specs.ts. The fetch scripts now resolve output via import.meta.dir instead of a cwd-relative ../specs — they previously only worked when run from inside .meta/, so this would have broken silently otherwise.

.github/workflows/update-specs.yml replaces the seven per-repo cron jobs. Unlike them it does not push to main: a spec change moves generated SDKs, so it opens a PR through the typecheck gate. One upstream being down warns instead of failing the run.

What stays a submodule

• gcp — 519 discovery documents, 120 MB. Vendoring puts that in every clone and every CI checkout permanently, and it's not undoable without rewriting history. Flagging rather than deciding: say the word and it's a one-line follow-up.
• The other ten are upstream repos we don't own (AWS, Azure, Stripe, kubernetes, …), already maintained there.

Verification

Ran scripts/convert.ts for all seven packages: each reads its spec from the new path, and .generated-specs comes out byte-identical to what the submodules produced — so this is a pure move, with no spec drift smuggled in.

Two things surfaced while testing, neither addressed here:

• fly-io's pinned spec is 22 operations behind upstream. A live fetch produced 98 operations vs 76 from the pin. That's a real spec bump waiting to happen, and now it'll surface automatically on the next scheduled run.
• Two patches are already stale on main — fly-io/machines/forbidden-errors.patch.json and posthog/app-metrics-errors.patch.json — both targeting response codes their upstream has since moved. Pre-existing, unrelated to this change.

[alchemy-version-bot]

Install the packages built from this commit:

@distilled.cloud/core

bun add @distilled.cloud/core@https://pkg.distilled.cloud/core/40c0fd0

@distilled.cloud/aws

bun add @distilled.cloud/aws@https://pkg.distilled.cloud/aws/40c0fd0

@distilled.cloud/axiom

bun add @distilled.cloud/axiom@https://pkg.distilled.cloud/axiom/40c0fd0

@distilled.cloud/azure

bun add @distilled.cloud/azure@https://pkg.distilled.cloud/azure/40c0fd0

@distilled.cloud/cloudflare

bun add @distilled.cloud/cloudflare@https://pkg.distilled.cloud/cloudflare/40c0fd0

@distilled.cloud/coinbase

bun add @distilled.cloud/coinbase@https://pkg.distilled.cloud/coinbase/40c0fd0

@distilled.cloud/expo-eas

bun add @distilled.cloud/expo-eas@https://pkg.distilled.cloud/expo-eas/40c0fd0

@distilled.cloud/fly-io

bun add @distilled.cloud/fly-io@https://pkg.distilled.cloud/fly-io/40c0fd0

@distilled.cloud/gcp

bun add @distilled.cloud/gcp@https://pkg.distilled.cloud/gcp/40c0fd0

@distilled.cloud/kubernetes

bun add @distilled.cloud/kubernetes@https://pkg.distilled.cloud/kubernetes/40c0fd0

@distilled.cloud/mongodb-atlas

bun add @distilled.cloud/mongodb-atlas@https://pkg.distilled.cloud/mongodb-atlas/40c0fd0

@distilled.cloud/neon

bun add @distilled.cloud/neon@https://pkg.distilled.cloud/neon/40c0fd0

@distilled.cloud/planetscale

bun add @distilled.cloud/planetscale@https://pkg.distilled.cloud/planetscale/40c0fd0

@distilled.cloud/posthog

bun add @distilled.cloud/posthog@https://pkg.distilled.cloud/posthog/40c0fd0

@distilled.cloud/prisma-postgres

bun add @distilled.cloud/prisma-postgres@https://pkg.distilled.cloud/prisma-postgres/40c0fd0

@distilled.cloud/stripe

bun add @distilled.cloud/stripe@https://pkg.distilled.cloud/stripe/40c0fd0

@distilled.cloud/supabase

bun add @distilled.cloud/supabase@https://pkg.distilled.cloud/supabase/40c0fd0

@distilled.cloud/turso

bun add @distilled.cloud/turso@https://pkg.distilled.cloud/turso/40c0fd0

@distilled.cloud/typesense

bun add @distilled.cloud/typesense@https://pkg.distilled.cloud/typesense/40c0fd0

@distilled.cloud/workos

bun add @distilled.cloud/workos@https://pkg.distilled.cloud/workos/40c0fd0