v1.4.1

Changed

• The release script bumps both plugin manifests, the builder.md stamp, and the changelog in lockstep with the CLI. scripts/release.sh gained a --lockstep mode (skips the confirm prompt, tolerates an empty [Unreleased] for a CLI-only release) and now also stamps agents/builder.md. The normal entry point is the CLI repo's scripts/release.sh, which invokes this with --lockstep so both repos release at the same version.

v1.4.0

Added

• Migrations are forward-only — a new immutability rule. A migration becomes immutable the moment it is either committed to git or deployed to any environment: editing a committed migration is forbidden (fix forward with a new db migrate), and an uncommitted migration may be edited/regenerated only after confirming with the user that it has not reached production (a prod deploy from a dirty tree can push one). Added at the decision layer in agents/builder.md and as an authoritative section in skills/cli/references/migration_system.md; the "Fix a broken migration" / "Remove a migration" troubleshooting steps and the cli skill's manual-fix list were reconciled to gate on uncommitted-and-not-deployed instead of telling the agent to edit migration files.
• AGENTLINK_VERSION stamp in agents/builder.md. Records the current version (plugin + CLI ship in lockstep, same number) and how the agent should reason about contract drift from a project's agentlink.json (version / appliedVersion). Kept in sync by the release script.

Changed

• Prefer the project-local CLI (pnpm exec agentlink) over npx …@latest for in-project work (pairs with the CLI's 1.4 devDependency pinning). agents/builder.md and the cli skill gained a "Running the CLI" section explaining the convention and the name split — the package is agentlink-sh, the installed binary is agentlink, and bare npx agentlink is unsafe (it resolves a different npm package when no local install exists). Swept ~230 in-project command references across the skills, README.md, rules/agentlink.mdc, and the destructive-DB hooks from npx agentlink-sh@latest <cmd> to pnpm exec agentlink <cmd>; create and recovery commands keep @latest (no local CLI exists yet). The hooks now point users at pnpm exec agentlink db rebuild — the block matcher is invocation-prefix-agnostic, so destructive-reset blocking still fires.

v1.3.1

Added

• database skill: "deprecate, don't delete" rule for deployed cron/storage resources. The imperative deploy step only applies files that are present and never reconciles deletions (unlike rbac/), so removing a cron/ or storage/ file leaves the resource live in an already-deployed DB. New rule in skills/database/SKILL.md: rename to deprecated-<name>.sql, comment out the original definition, then for cron append an idempotent cron.unschedule(jobid) FROM cron.job WHERE jobname='<name>' (the bare unschedule throws when absent and rolls back the cron folder); for storage emit no SQL and delete the bucket from the dashboard (objects cascade), since DELETE FROM storage.buckets orphans objects that keep counting against Storage usage.

v1.3.0

Added

• New notifications skill — the entry point for transactional / non-auth email. Teaches the builder how AgentLink sends app-driven email (welcome, "export ready", receipts, alerts) through the queue: api._admin_send_email → PGMQ → internal-queue-worker → internal-send-email → Resend, with public.internal_logs_email for idempotency/observability. SKILL.md covers the server-only send rule, the send API, the welcome sample + its confirmation-timing nuance, and cross-links auth (auth emails), cli (per-env Resend setup), edge-functions, and database. references/transactional-email.md is the deep dive: add-an-email recipe, the internal_logs_* convention, retry/dead-letter via read_ct, local resend-box testing, and troubleshooting. Registered in agents/builder.md (now 7 preloaded skills); auth and edge-functions SKILLs cross-link it so non-auth email is routed to the right place.
• builder agent: the transactional-vs-auth email split is now spelled out at the decision layer. Two new rows in the architecture matrix (agents/builder.md) route app-driven email to api._admin_send_email(...) → internal-send-email (notifications skill) and Supabase Auth email to the _hook_send_email → internal-send-auth-email hook (auth skill, flagged a separate function). A new "Email: two paths, never crossed" subsection adds the originator litmus test (does your code decide to send it? → notifications; does an auth event trigger it? → auth hook), warns against routing auth email through api._admin_send_email or adding auth templates to the internal-send-email registry, and notes the scaffolded welcome email is deliberately a notification, not an auth hook, so it never collides with the signup confirmation.
• notifications skill: migration guide for projects scaffolded before the unified email path. New section in skills/notifications/SKILL.md for older projects that shipped a dedicated internal-invite-member edge function: recommend consolidating onto the invite registry entry in internal-send-email (confirm with the user first — it removes a function and leaves an orphaned cloud deployment to delete), with exact steps (add the invite template, repoint _internal_admin_create_invitation/_resend_invitation to api._admin_send_email('invite', …) with no dedupe_key, delete the function + its config.toml block, db apply/db migrate/deploy, then supabase functions delete on cloud). Generalizes to any bespoke per-email function; notes auth emails stay on the auth hook.

Changed

• Prescriptive docs migrated off the per-function invite pattern to the unified api._admin_send_email('invite') → internal-send-email path. agents/references/recipes.md (Recipe 2), skills/auth/SKILL.md (invitation RPC row + troubleshooting), skills/auth/references/rls_patterns.md, skills/edge-functions/SKILL.md (naming table + resend link), and skills/cli/references/resend.md no longer teach the standalone internal-invite-member function as the canonical invite-email path.

v1.2.4

Added

• New skills/cli/references/resend.md — the single source for Resend configuration. Covers both consumers of Resend (Auth SMTP for the built-in mailer + _hook_send_email, and the transactional edge functions like internal-invite-member), now that Resend is configured per cloud environment: the FROM address is the source of truth in agentlink.json (cloud.environments.<env>.resend.fromEmail, hand-editable) while the API key lives only in that env's Supabase secret store and is sticky (untouched unless --api-key is passed). Documents the --api-key/--email/--name flags (positionals are deprecated), the first-time all-or-nothing rule, the cross-domain --yes confirmation, local resend-box vs cloud SMTP, recipes (change display name, rotate key, promote dev→prod), and the "email not sending" debug flow.

Changed

• Skills updated for per-env Resend. skills/auth/SKILL.md's "Email Hooks with Resend" troubleshooting no longer keys off check's resend_configured (that field was removed from the CLI — Resend is per-env now); it tells the agent to read cloud.environments.<env>.resend in agentlink.json and validate the env's secret store, and links to the new cli/references/resend.md. skills/cli/SKILL.md updates the Resend prerequisite row and reference list to point at it; skills/edge-functions/SKILL.md cross-links it from the reference list for email-sending functions. The embedded RESEND_API_KEY / RESEND_FROM_EMAIL component descriptions (cli/src/components.json, regenerated) were rewritten to the per-env / source-of-truth model.

v1.2.3

Changed

• withSupabase: migrate the edge-functions docs to the new @supabase/server auth API. The wrapper's allow option is deprecated in favor of auth (allow still works but warns and will be removed in a future major), and the auth values were renamed — 'public' → 'publishable' and 'always' → 'none' (including colon variants like 'public:<name>'), with the ctx.authType field now ctx.authMode. Updated all references across skills/edge-functions/ (SKILL.md, references/with_supabase.md, edge_functions.md, api_key_migration.md) and rules/agentlink.mdc to use auth: and the new value names, taking care not to touch the unrelated public schema. The scaffold's bundled functions only ever used auth: "secret" / auth: "user", so generated code needed no value renames.

v1.2.2

Changed

• Document prerequisites and stop the agent from hand-creating a scaffold. Two failure modes where the agent built project files by hand instead of running the CLI. (1) No Node/npx on the machine — the npx agentlink-sh@latest call timed out and the agent treated the failure as a cue to create files manually. Added a Prerequisites section to README.md and skills/cli/SKILL.md (Node 18+ always; Supabase CLI; Docker + psql for local; a Supabase account for cloud; Resend for transactional email), with an explicit ⚠️ that a missing node/npx makes the command time out and is a stop-and-install signal, never a reason to scaffold by hand. (2) The Scaffold Map read as a build checklist on an unscaffolded project — added a 🛑 banner to references/scaffold-map.md stating it's an inventory of what the CLI already created (no agentlink.json = unscaffolded = run the CLI, never hand-create the listed tables/RPCs/routes), and stated the precondition in cli/SKILL.md's reference list. Also hardened rules/agentlink.mdc: an unscaffolded-detection rule at the entry point (no agentlink.json → CLI first, never hand-create) and a directory/init-ordering rule (settle location + dev env, then let the CLI create and init the directory — don't mkdir/git init/lay out structure by hand; check node --version first).

v1.2.1

Changed

• Cursor: the always-on rule now engages AgentLink on the default agent, not just the selected builder. In Cursor the builder agent is user-selectable rather than a forced default (unlike Claude Code's settings.json wiring), so a user who opens a normal chat and asks to "build an app" gets Cursor's generic agent — which asked raw frontend/backend questions instead of using AgentLink. Since rules/agentlink.mdc (alwaysApply: true) is the only surface guaranteed to load regardless of agent selection, it's been promoted from pure architecture guardrails to also be the entry point/router: a new "Engaging AgentLink" section tells any agent to treat build/scaffold/Supabase-backend requests as AgentLink tasks (load the matching skill, scaffold only via the CLI, don't improvise a stack), and a "Building a new app" section ports the essential builder behaviors the generic agent was missing (plan-first; the blank-project kickoff — multi-tenancy / entry point + look-and-feel / product + entities → brief in AGENTS.md; ask-about-product-not-architecture; DB/deploy work via the CLI, never the Supabase connector MCP).
• Scaffold guidance: the local-vs-cloud dev-env question is now on the surfaces that actually load at scaffold time. The "ask the user local Docker vs Supabase Cloud first" instruction previously lived only in agents/builder.md and references/workflows.md — neither reliably reaches the model in Cursor (no forced agent) or when only cli/SKILL.md is loaded. cli/SKILL.md framed --skip-env as the unconditional "canonical path when an AGENT is doing the scaffolding", so the agent ran --skip-env -y and handed off env add dev without ever asking. Added a 🛑 scaffold-decision callout to the top of cli/SKILL.md's "Scaffold a new project" section and reframed --skip-env as the cloud path after the user chose cloud (not a blanket default); added a matching "Scaffolding a new project" section to rules/agentlink.mdc.

v1.2.0

Added

• Cursor-compatible plugin (same repo, dual-format). The plugin now installs in Cursor as well as Claude Code, sharing the skills, builder agent, references, and assets verbatim. Added the Cursor-native files alongside the Claude Code ones: .cursor-plugin/plugin.json (manifest with explicit agents/skills/rules/hooks paths so Cursor doesn't auto-discover the Claude-format hooks/hooks.json), .cursor-plugin/marketplace.json, and rules/agentlink.mdc — an always-on rule carrying the core guardrails (schema isolation, RPC-first, function-naming security model, RLS-on-every-table, write-apply-migrate / never-reset, withSupabase allow values). The destructive-DB guard is ported to Cursor's contract in hooks/cursor.hooks.json + hooks/block-destructive-db.cursor.sh: same db reset / db rebuild / db push --force matching as the Claude hook, but reading the beforeShellExecution top-level command and blocking via a {"permission":"deny"} JSON verdict (exit 0) instead of stderr + exit 2. Nothing existing changed behavior — claude --plugin-dir ./agent is unaffected. In Cursor the builder is a user-selectable agent rather than a forced default. scripts/release.sh now bumps both plugin.json manifests together so they never drift.

Changed

• database + auth skills: explicit workflow for cron / storage / RBAC changes, and the GRANT-vs-RBAC-permission distinction. A change to cron/, storage/, or rbac/ is excluded from db apply's schema diff, so the skills now spell out the loop — edit the imperative file → apply it with db apply (applies them alongside schema) or the new db resources (those folders only) — plus a concrete "what you're changing → which file → then" table, and a 🛑 that dropping a cron.schedule()/bucket/policy/RBAC row into a schemas/ file silently never runs. Also disambiguates the two things called "permission": a SQL GRANT on a table/function is DDL (lives in the object's schema file, applies with db apply), whereas the RBAC permission model (auth_verify_access keys + role bindings) is reference data in rbac/ (applies with db resources). The auth skill's "add a gated capability" steps now name both apply commands.
• Skills corrected for the new default db apply / db migrate / db rebuild behavior, then scrubbed of all under-the-hood detail. Two passes. First, docs describing the old create-only / Docker behavior were fixed: db apply now applies changes to existing objects (an ALTER) directly with no Docker, db migrate needs no Docker, db rebuild is genuine recovery (not needed to pick up a schema edit, and it never regenerates migration files), npx supabase db diff isn't used, and standalone seed DML in schema files is rejected. Second — and the bigger cleanup — every implementation detail the app-building agent doesn't act on was removed from the agent-facing docs and re-expressed as observable behavior. Out: engine/library names (pg-delta, pg-topo, pglite, "the converger", "shadow database", "declarative apply", "catalog-export", "materialize"); internal CLI function/constant names (runSQL, bootstrapCloudEnv, getApiKeys, ensureAccessToken, pickOrg, setDefaultEnvironment, MANAGED_KEYS, writeMigrationTemplates, repairMigrations); and CLI-maintainer content misplaced in app skills (the migration_system.md "Adding an Extension/Migration → edit cli/src/… → rebuild the CLI" sections — an app agent never edits CLI source). migration_system.md was rewritten from a maintainer deep-dive into a lean agent reference. In: the same rules and behaviors — "db apply resolves dependency order automatically", "strips surrounding quotes from identifiers" (the snake_case rule + 42601), "a blanket grant gets applied after the per-function REVOKEs" (the dev/prod-divergence why), no-Docker, ALTER-aware, prod-is-migrations-only. Net: the skills describe what the commands do and what rules to follow, never the library that produces it — which also makes them staleness-proof against a future engine swap. Swept across cli/{SKILL.md, references/*}, database/{SKILL.md, references/*}, rpc/references/rpc_patterns.md, auth/{SKILL.md, references/rls_patterns.md}, agents/builder.md, and rules/agentlink.mdc.
• Docs are now editor-neutral — Cursor is a co-equal agent editor, not a footnote. The CLI gained an editor choice (Claude Code / Cursor / both) and never requires an agent editor on PATH to scaffold, so the skills + agent now say so. skills/cli/SKILL.md: the Prerequisites section no longer claims the CLI "validates Claude Code is present" (it never did — that abort was removed long ago); it now states the CLI needs the Supabase CLI (+ psql for local) and writes editor config regardless of which agent is installed. The scaffold descriptions say "configures your chosen agent editor (Claude Code and/or Cursor)". references/troubleshooting.md: replaced the stale "Claude Code not found on PATH → scaffold aborts" entry with a "plugin/skills don't show up after scaffold" entry covering both editors (Claude Code auto-installs from .claude/settings.local.json on first launch; Cursor needs a one-time /add-plugin tomaspozo/agentlink), and fixed the quick-reference table row. references/workflows.md: "prompt passed to Claude Code" → "to your agent". agents/builder.md: the cloud hand-off line and scaffold-completion line are editor-neutral. README.md: the wizard intro, the existing-project install section (now shows the Cursor /add-plugin path next to the Claude Code marketplace commands), and local-dev note mention both editors.
• builder agent + cli skill: corrected the new-project scaffold guidance (wrong flag, folder nesting, no env choice). The "New project setup" section in agents/builder.md and Workflow #1 in skills/cli/references/workflows.md now: (1) tell the agent to ask the user local-Docker vs Supabase-Cloud for the dev environment first, and pick the command accordingly (--local the agent can run end-to-end; cloud needs browser OAuth → --skip-env then hand off env add dev); (2) document the . vs <name> target rule — a <name> arg always resolves to a subfolder (cwd/<name>), so when already inside the target dir use ., and never cd foo && npx … foo (it nests into foo/foo/); (3) fix the malformed npx . --skip-env to npx agentlink-sh@latest . --skip-env; and (4) list the real scaffold flags and call out that --no-launch does not exist (removed) — an unknown flag errors before anything scaffolds. Also removed the stale --no-launch row from the cli skill's flag table (skills/cli/SKILL.md), which was the source the agent learned the dead flag from. Fixes the observed failure where the agent passed --no-launch (command errored) and then nested a project by re-running with a name from inside the target directory.
• database skill: declarative schema files are now explicitly DDL-only — no seed/data DML. Added a prominent rule (and a "Seed / default rows" row to the where-to-put-objects table) forbidding standalone INSERT/UPDATE/DELETE/MERGE/TRUNCATE in supabase/database/schemas/ files. Such data is silently dropped by the converger (db apply/db migrate diff catalog objects, not rows), and the CLI now hard-errors on it — so the skill directs seed/reference data to its proper home: supabase/seed.sql (local), a migration (prod-bound reference data), or the rbac/ reconcile (roles/permissions). Clarifies that DML inside a function body is fine (it's part of the function's DDL).
• Plugin renamed link → agentlink; marketplace namespace is now tomaspozo. Install is now /plugin install agentlink@tomaspozo (the /plugin marketplace add tomaspozo/agentlink GitHub path is unchanged). Swept the live references: settings.json (agentlink:builder), the agentlink:frontend skill cross-ref in agents/builder.md, and the README. The CLI that scaffolds projects (cli/src/claude-settings.ts) and the landing page install snippet (www/components/start-page-plugin.tsx) were updated to match — without the CLI change, newly scaffolded projects would register a plugin/marketplace name that no longer resolves and silently fail to load it.
• Destructive-command hook now blocks db rebuild (the CLI's db reset was removed; db rebuild is the reset). The CLI consolidated db reset into db rebuild — db rebuild now runs supabase db reset internally (replays migrations) then re-applies schema files + imperative resources, without regenerating migrations. So the hook that keeps resets user-initiated now matches agentlink … db rebuild (in addition to a raw supabase db reset) and points the user at npx agentlink-sh@latest db rebuild. The cli skill's "Database rebuild" section + the troubleshooting entries are reworded to the new reset-then-re-apply behavior (no more migration regeneration), and stale db reset command references across the skills are updated to db rebuild.
• frontend + cli skills: documented the scaffold's page-anatomy primitives and the neutral-shadcn list/picker rules. The scaffold now ships PageHeader (page hero) + a real PageShell (page wrapper) and a curated shadcn ui/ set, so the skills teach the agent to compose them instead of re-inventing. frontend/SKILL.md corrects the Shared Components table (PageShell = wrapper, PageHeader = hero), adds a page anatomy section (PageShell → PageHeader → content; lists use shadcn Table, pickers use shadcn Select, never a native <select>; loading uses ListSkeleton, empty uses EmptyState), lists the curated ui/ components, and adds the on-demand escape hatch (npx shadcn@latest add <name> --yes) as the first move for any missing primitive — never hand-roll or fall back to a native element. `references/...

v1.1.0

Added

• builder agent: orchestration recipes reference (agents/references/recipes.md). Cross-cutting, end-to-end worked examples that combine the layers the architecture keeps separate — api.* RPCs, edge functions, and pg_cron + PGMQ wired through the prebuilt admin functions. Three recipes: a scheduled outbound-HTTP "ping engine" (with a PGMQ fan-out variant), a queued side-effect (invite-member email), and a periodic third-party sync — each ending with a "what goes where" mapping back to the principles. The database and edge-functions skills' background-work sections link to it.
• cli skill: Scaffold Map reference (skills/cli/references/scaffold-map.md). A deterministic, version-matched inventory of everything a fresh scaffold ships with — every table, RPC, _auth_*/_internal_admin_*/_hook_* function, RBAC role + permission, and frontend route/hook/component — so the agent reads it instead of doing a discovery pass on a freshly scaffolded project.

Changed

• database + cli skills: documented the imperative resource folders (cron/, storage/, rbac/). These three top-level folders under supabase/database/ are excluded from declarative apply and from migrations, and applied imperatively by the deploy step on every env (incl. prod) — the only path that reliably reaches prod for cron jobs, storage buckets/policies, and RBAC data (pg-delta's Supabase integration filters the cron + storage schemas; RBAC is reference data). Cron files moved from schemas/api/cron/ to the top-level cron/ folder; added storage/ guidance with the idempotency rules (cron.schedule upserts by name; buckets via INSERT … ON CONFLICT; policies via DROP POLICY IF EXISTS + CREATE POLICY). Swept the database SKILL + naming_conventions, the cli SKILL + migration_system, the scaffold-map reference, and the builder recipes to the new paths. Added a db reset section + a troubleshooting entry: a raw supabase db reset drops custom roles/cron/storage (migrations-only replay) — use npx agentlink-sh db reset (resets + re-applies imperative resources) or db apply to restore them.
• builder agent: the Architecture section is now a decision framework, not just a description of layers. Added a decision matrix (concern → default decision → owning skill), a Decision protocol (decide from the principles by default; confirm when the user dictates an implementation; research the Supabase docs then decide for uncovered patterns), and named the prebuilt cron/queue building blocks the agent must reuse (_internal_admin_call_edge_function, api._admin_enqueue_task, the queue lifecycle helpers, internal-queue-worker, process-stale-tasks). Reworded the discovery-phase guidance into two explicit buckets — product decisions (ask) vs. architecture & runtime mechanics (decide) — so the agent stops surfacing settled choices like "edge function vs. in-database pg_net?" as user questions.
• edge-functions skill: outbound HTTP is always an edge function, never in-database pg_net. Added an explicit rule (with the canonical cron → call edge fn → RPC fetch → fetch URLs → RPC write flow) scoping pg_net to its only sanctioned use — waking an edge function via _internal_admin_call_edge_function. The database skill's cron-file convention now points to it.
• builder agent: trimmed the always-loaded prompt ~40% (453 → 267 lines). Reference-grade detail that duplicated the on-demand skills — the CLI command table, check/--force-update/info/--debug/upgrading prose, the managed-files/base-snapshot mechanics, the supabase/database/ tree diagram, the schema-usage table, and the long .from() / SECURITY INVOKER code blocks — was reduced to a rule plus a "Load the X skill" pointer (verified each is covered as well or better in the owning skill). Invariants the agent must obey even with no skill loaded (RPC-first / never .from(), never-reset / migrations-only, the prod-deploy CAN/MUST-NOT boundary, the function-prefix table, the decision framework) stay inline. Removed a redundant end-of-file "How the CLI tracks schema files" block that duplicated the Managed-files section.

Fixed

• Destructive-command hook no longer lets npx supabase db reset through. The block regex was anchored such that it only matched a bare supabase db reset at the start of the command — the common npx supabase db reset (and any path/prefixed form) slipped past unblocked. Rewrote it to match db reset in every form of both supabase and agentlink invocations (npx / path / @latest prefixes, inside &&/;/| chains), so the agent can't reset the database — directly or via the new agentlink db reset wrapper — without the user. The block message now points the user at npx agentlink-sh@latest db reset (which also restores the imperative resources a raw reset drops).