# Cloudflare DNS: agent notes

Load this when the plan uses `dns=cloudflare`.

## 1. Logging in: a zone-scoped API token

Cloudflare is **token-only**. `wrangler login` can't be used: its browser login has no DNS-write
scope, so every DNS write would fail with 403. Don't send the human there.

Walk the human through creating the token (it goes into the credentials file, never this chat):
1. Cloudflare dashboard → **My Profile → API Tokens** → **Create Token**.
2. Start from the **"Edit zone DNS"** template (Zone → DNS → Edit).
3. **Add** a permission: **Zone → Zone → Read** (lets golive find the zone by name).
4. **Zone Resources → Include → Specific zone → their domain.** This limits the token to that one
   domain, so a leak can't touch anything else.
5. Optional but good: set an expiry. Create the token; Cloudflare shows it **once**.
6. On macOS run `credentials --prompt CLOUDFLARE_API_TOKEN --json`; they enter the value in the
   private native dialog. Their own editor is the fallback if unavailable, unsupported, or preferred;
   follow [How the human connects accounts](../SKILL.md#how-the-human-connects-accounts) for fallback,
   replacement and cancellation. Never put the value in chat or arguments. A token exported in their
   own terminal doesn't reach the agent's shell.

Notes:
- `CF_API_TOKEN` is accepted as an older alias. The **Global API Key** (`CLOUDFLARE_API_KEY`) is
  refused: it can do anything on the account. Ask for a scoped token instead.
- Account-owned tokens only verify under their account: also set `CLOUDFLARE_ACCOUNT_ID` (not a
  secret; the agent's environment or the credentials file).

## 2. What golive does vs. what stays with the human

golive automates (DNS writes always need `--confirm-dns`):
- Finds the domain's **active** zone in the human's Cloudflare account through the API. If that lookup
  fails (token permissions, rate limit, network), `plan` warns and plans no DNS step.
- For each record it needs, looks at the existing records at that name, then creates it, adopts an
  identical record as-is, or updates one it created earlier. Records golive creates carry a comment
  starting `golive:`, so later runs know they're its own. Changes are applied **one record at a time**
  (not one batch): if a step stops midway, records already written stay, and re-running `apply`
  continues.
- Sets **proxy off** on records it creates or owns.
- **SPF:** merges the sender's mechanisms into the one existing `v=spf1` record. Mechanisms are
  compared without qualifiers, so nothing is duplicated. If the existing SPF already has the sender's
  mechanism with a `~`, `-` or `?` qualifier, golive stops and asks the human to change that term to a
  plain `include:` (SPF could never pass otherwise). It also stops past 10 DNS lookups.
- **One-per-name records:** a DKIM key TXT at `<selector>._domainkey.<domain>` and a return-path MX
  (`feedback-smtp.<region>.amazonses.com`). A stale one golive owns is updated in place (e.g. after
  the Resend domain was recreated or its region changed). One someone else created stops golive with
  a conflict error and nothing is changed. Other TXT/MX records sit alongside existing values.
- **CNAME exclusivity:** golive never puts a CNAME on a name that also holds TXT/MX/CAA records, or
  those records next to a CNAME, except at the zone apex. It stops with an error listing the
  records; for mail records it suggests deleting them or recreating the Resend domain with a different
  custom return path (e.g. `bounce`).
- Doesn't write DMARC (the `email-dns` check suggests one).
- Retries: record updates are retry-safe; a record create is not re-sent after a timeout or 5xx
  (re-running `apply` adopts it if it landed).
- Verifies: `domain:dns:records` (the zone holds the records), then `domain-live`, `email-dns`,
  `email-verified` from outside.

Stays with the human (and why):
- **Nameservers.** If the zone is `pending`, the domain's registrar still points elsewhere. The human
  sets the two Cloudflare nameservers shown in the dashboard at their registrar.
- **Records golive didn't create that conflict with what's needed** (e.g. an old `www` pointing at a
  previous host, a proxied record with the right value, a CNAME clash). golive never overwrites or
  deletes them: the error names them, and the human edits or deletes them in the dashboard (or sets
  their comment to start with `golive:` to let golive manage them), then re-runs.
- Buying the domain; domains that live in someone else's Cloudflare account.
- SPF over 10 DNS lookups after merging: a human decision about which senders to keep.

## 3. Explain these in plain words

- **Orange cloud off.** Cloudflare's proxy in front of Vercel breaks certificates and verification,
  and proxied email CNAMEs never verify. Records the human made earlier may be orange; golive leaves
  those alone and warns. The human switches them to "DNS only" (grey).
- **Only one SPF record.** Two `v=spf1` records at the same name make SPF fail completely. New senders
  get merged into the existing record.
- **Propagation takes time.** Cloudflare updates within about a minute, but other resolvers cache. A
  name looked up *before* it existed can stay "not found" for up to **30 minutes** (negative caching).
  Don't test a name by hand before golive creates it, and let `verify` retry.
- **Root domain for Vercel:** use the A record from `plan` (Vercel's verifier expects it).
- **A name can't have both a CNAME and other records** (except at the apex, where Cloudflare flattens).

## 4. Troubleshooting

| Symptom | What to do |
|---|---|
| `doctor`: token missing or not active | Create/recreate the token (§1) and put it in the credentials file. |
| Zone not found | Token isn't scoped to this domain, lacks Zone Read, the zone is `pending`, or it's in another account. Fix the token. |
| Zone status `pending` | Nameservers not changed at the registrar yet. Human updates them; can take hours. |
| 403 on writes | Token lacks DNS Edit (e.g. a wrangler token). Use the "Edit zone DNS" token. |
| "DNS conflict at <name>" | A record golive didn't create is in the way (A/CNAME clash, CNAME next to TXT/MX, foreign DKIM/return-path). Follow the error: edit/delete it in the dashboard, then re-run. |
| `domain:dns`: "the DNS records … requires … changed since the plan was approved" | The host now wants different records than the human approved; nothing was written. Run `plan` again and get re-approval with `--confirm-dns`. |
| "SPF … already has `~include:…`" | Change that term to plain `include:…` in the dashboard, then re-run. |
| Several SPF records at one name | Merge them into one in the dashboard, then re-run. |
| Error 81058 "An identical record already exists" | Already there; golive adopts it. Harmless. |
| Warning "recovering a stale zone id for …" | The zone id in `.golive/state.json` was rejected (zone deleted/re-created, or the token re-scoped); golive re-found the zone and continued, naming both zones. If the domain doesn't go live, confirm the zone golive used is the one that serves the domain, then re-run `plan`. |
| Error "The cached Cloudflare zone … was rejected … no active zone … anymore" | The zone was deleted or re-created, the nameservers changed, or the token was re-scoped/revoked. Check the Cloudflare dashboard (zone exists and is active, token still scoped to it), then re-run `plan`. |
| 429 | Rate limit (1,200 requests / 5 minutes); wait and re-run. |
| Vercel says misconfigured; lookups show Cloudflare IPs (104.16.x, 172.64.x) | Record is proxied. Turn the orange cloud off. |
| Email domain won't verify (Cloudflare "Code 1004") | Proxied email CNAME. Set it to DNS only. |
| Still "not found" right after creating | Negative caching; wait up to 30 minutes and re-run `verify`. |

## Unverified

- Whether a token with only DNS Edit (no Zone Read) can still find its zone by name. The safe setup
  above includes Zone Read.
- "Dashboard proxies new records by default" comes from community reports, not current official docs.

# GoDaddy DNS

Automated DNS-record adapter with two transports — same endpoints and safety rules either way: the
official GoDaddy CLI (`gddy`, the default when installed and logged in) and a scoped REST Personal
Access Token (the fallback). The Vercel-attached custom-domain journey passed disposable live runs
on both transports: the CLI path created both records through `gddy api call` with the user's OAuth
session, and the v3 update-by-ID (PUT) endpoint was separately validated through that same session.
golive's owned-record update flows (SPF merge, singleton replace, TTL drift) and the REST
update-by-ID path remain mock-covered. The GoDaddy MCP cannot modify DNS.

1. Use `dns=godaddy` only when the domain's **authoritative DNS** is hosted at GoDaddy. Buying a
   domain there is not enough if its nameservers point elsewhere. golive checks public delegation and
   zone access, including subdomain delegations; it never changes nameservers.
2. Preferred sign-in: install the official CLI and log in once. That installer is GoDaddy's own,
   published on their release page —
   `curl -fsSL https://github.com/godaddy/cli/releases/latest/download/install.sh | bash` — and the
   **human runs it in their own terminal**: never pipe a vendor script into a shell on their behalf.
   They may install `gddy` by their own route instead (download and inspect that script, or a package
   manager), because golive only needs it on PATH. Then
   `gddy auth login -s domains.dns:update` in the human's terminal (browser OAuth; the session stays
   in the CLI's own store, never in chat, arguments or golive's files). Include `domains.dns:update`
   from the start: in a non-interactive run gddy does not prompt for the scope, and a write without
   it fails with HTTP 403 (whose message names this command).
3. Fallback when the CLI is unavailable (headless hosts, no extra binary): have the human create a
   Personal Access Token at `developer.godaddy.com` with `domains.domain:read` and
   `domains.dns:update` only. No purchase or nameserver permissions.
4. PAT path only: on macOS run `credentials --prompt GODADDY_API_TOKEN --json` for private native
   entry. Their own editor is the fallback if unavailable, unsupported, or preferred; follow
   [How the human connects accounts](../SKILL.md#how-the-human-connects-accounts) for fallback,
   replacement and cancellation. Never put the value in chat or arguments. Classic key/secret pairs are not used.
5. Run `doctor`. Current GoDaddy documentation allows domain management when the account holds at
   least one domain, or has a qualifying plan; a 403 may indicate missing scope or account eligibility.
6. Show the complete plan and obtain explicit DNS approval before `apply --confirm-dns`.

golive preserves unrelated records. It can change records it created only while their stored
fingerprints still match; existing matching records are accepted without taking ownership. An
unmanaged conflicting record, duplicate SPF or a delegated child zone stops the write. Ask the human
to resolve the specified record in the dashboard or choose a fresh subdomain, then re-plan. Existing
SPF policies requiring an added sender need manual review unless golive created the policy.

GoDaddy requires TTL 600–86400 and does not support an apex CNAME. Use the host's apex A/AAAA
instructions or a subdomain. Domain purchases, renewals, transfers and nameserver changes are outside
this adapter. `golive teardown` removes fingerprint-matched records after plan approval and
`--confirm-destroy`; manual dashboard removal should likewise use the record IDs tracked under
`godaddy.recordFingerprint:<zone>:<recordId>` and confirm their current state first.

Official references: [DNS API](https://developer.godaddy.com/en/docs/api-users/domains/manage/dns),
[PAT setup](https://developer.godaddy.com/en/docs/api-users/auth),
[MCP limits](https://developer.godaddy.com/en/docs/api-users/mcp).

# Guided providers

Use this when the human picked a provider golive doesn't automate yet (`menu` shows `automated: false`,
or a provider that isn't listed at all). Help execute a documented path where possible, then guide
the human through the parts that need them. This is best-effort assistance, not a promise that an
adapter exists or that this provider can take the app live.

Keep providers the app already uses. Check framework/runtime compatibility before suggesting a new
one; changing hosting does not migrate the app's database or Auth. Use the menu's exact provider id
when present. Otherwise choose a descriptive lowercase letters/digits/hyphens id, for example
`init --stack hosting=example-host,db=supabase --json`. Replace `example-host` with the provider's
id, not `other`. This only records the choice; no new capability is installed.

`doctor` may return `ok: false` / exit code 2 for guided providers because no adapter exists.
Do not repeatedly request credentials to fix that. The `accounts` check covers automated providers
only; its passing result does not prove a guided provider's login or account ownership.

## How to guide

1. **Find a supported path in current official documentation.** Check the specific operation,
   required permissions, account/project scope, price and verification method. Link the relevant
   documentation. Do not guess command flags, API endpoints or dashboard controls.
2. **Choose tools by capability.** Prefer the official CLI when it supports the operation and a
   usable account login. An available official MCP or the official API can fill a gap, subject to
   the secret rules below. No MCP installation is required; do not mechanically try every tool.
   If automation lacks the needed capability, guide the provider's dashboard flow. Use a direct
   provider integration when it safely connects the two services without exposing credentials.
3. **Establish identity before writes.** Use read-only, non-secret observations to identify the
   selected account/team, project and any existing resources. The human completes signup, login,
   purchases and identity checks. Interactive logins, prompts and pickers need a **separate terminal
   window**: Claude Code's `!` prefix has no TTY. Verify the installed CLI is on PATH, then resume the
   same stage. Never use a `--token` / `--key` flag: argv exposes the secret.
4. **Get approval for the concrete external operations.** Add existing account/team/project IDs
   and proposed new resource names/settings, intended changes, permissions, costs and verification
   steps to `docs/GOLIVE-<stage>-PLAN.md`, and summarize
   them in chat before requesting approval. The CLI `planId` approves only its listed steps; it does
   not cover separate CLI/MCP/API/dashboard writes. State which operations are outside `apply`.
   Resolve unknown scope or cost first; never automate purchases. Live payments and exact DNS
   changes need explicit category approval. A changed destination or operation needs a new plan.
5. **Execute or guide one bounded step at a time.** After approval, perform supported operations
   with safe tool outputs. For human steps, give the exact action and expected result, then wait
   for confirmation. If an operation times out, inspect its remote outcome before retrying; do not
   create duplicates. Follow `troubleshooting.md` for a concrete repair and resume the same stage.
6. **Verify and record what the evidence establishes.** Run applicable CLI checks as described
   below. For external tooling, confirm the exact project/resource and record the observation,
   source, time and any newly assigned resource IDs in `docs/GOLIVE-<stage>-RESULT.md`, without
   credentials. An HTTP 200 alone does not
   prove the intended app or workflow works. Do not actively probe a project URL without confirming
   its ownership; do not bypass the CLI's confirmed-origin guard to make a skipped check run.
7. **Stop when there is no safe documented path.** If the required capability is unavailable,
   secret output cannot be avoided, permissions or cost remain unresolved, or a failed operation
   cannot be reconciled, state what blocks this step and the next human action. Preserve progress;
   do not invent a command, repeatedly try speculative alternatives or claim deployment succeeded.

## Keep secrets outside the agent context

- Before calling any tool, check whether its output can contain credentials. **Do not call MCP
  endpoints that return secret keys, connection strings or one-time credentials into the agent
  context.** Redacting after receiving a result is too late. Prefer metadata-only operations.
- Official API calls are acceptable only through a reviewed local path that loads credentials
  privately, transports them through stdin or HTTPS headers/body, and returns only allowlisted
  non-secret metadata. Apply the same rule to CLI output and errors. Never put secrets in argv,
  chat, logs, screenshots or a file the agent will read. If safe output cannot be guaranteed, use
  a human dashboard handoff instead.
- Prefer provider-to-provider integrations. When a value must be entered manually, the human
  enters it **directly into the destination dashboard** using their own browser. Do not inspect,
  capture or ask them to relay it. Resume agent inspection only after secret fields are closed.

**DNS records:** use the exact records supplied by the selected host/email provider, or by
`plan` / `handoff`. Approve their zone, type, name and content before editing. Follow the provider's
proxy guidance; merge SPF into the single existing `v=spf1` record instead of adding a second one.

## Keep CLI checks and external evidence distinct

After each piece, run `verify --only <check-id> --json` with an applicable id below (or from SKILL.md).
This creates a partial report for that invocation, not a cumulative acceptance report. A CLI check
counts as passed only when it actually **passes**; a `skip` is not a pass.

Record external evidence separately as **verified by the agent; not verified by the golive CLI**,
naming the tool or observation, scope and limitations. Human confirmation alone is
**human-confirmed; not independently verified**. Never rewrite `.golive/state.json`, generated
reports or handoff status to turn these into CLI passes. Run full CLI verification at the end and
summarize both sets of evidence without merging their claims.

`handoff --json` can retain a generic `guided:<axis>` item as `done: false` because it has no closing
check. Manual items and skipped checks stay `done: null`, including guided Auth settings or a guided
host's environment variables. Explain those open/unverified items even if separate observations
were recorded; do not claim the CLI has closed them.

**Guided host with automated Stripe.** golive can't store the webhook signing secret in a guided
host, and Stripe reveals it once, so a blocking `stripe:webhook-guided` handoff (closed by
`webhook-registered`) tells the human to create the endpoint in the Stripe dashboard and copy its
`whsec_…` straight into the host's **Production** env. The `env:<target>` handoffs are per target:
no webhook secret outside production, and Stripe keys are labelled with that target's mode (test in
preview, live in production by default).

## What golive can still check

| Check id | Works with a guided provider? |
|---|---|
| `accounts` | Covers only automated providers; guided entries are not authenticated or verified by this check. |
| `domain-live` | Partly: public DNS-over-HTTPS plus an HTTPS request. With a guided host (or no host) its evidence says the attachment is **not confirmed**: a pass doesn't prove the domain is attached to that host. |
| `email-dns` | Yes: SPF/DKIM/DMARC looked up in public DNS at the usual locations for the provider (see below). |
| `bundle-secrets`, `webhook-unsigned` | Only when the **hosting** provider is automated: they probe only the production URL the host confirms belongs to the project, so with a guided host they skip. |
| `rls-probe` | Only with `db=supabase`. |
| `db-connection` | Only with the implemented Neon database capability; not a generic guided DB test. |
| `env-parity`, `auth-redirects`, `auth-policy`, `auth-signup`, `auth-session`, `webhook-registered`, `email-verified` | No: they need the provider's API, so they skip for a guided provider on that axis. |

Every skipped check is something golive did not verify. Name them in your final summary.

**`email-dns` for guided email providers** (no record list from the provider API, so it uses each
provider's usual layout):
- **Postmark:** no SPF required; a `pm-bounces.<domain>` CNAME is accepted as the custom return path
  and is optional (a note). Its DKIM selector (`<timestamp>pm`) can't be found over DNS.
- **SES:** no SPF required (the default MAIL FROM is amazonses.com; a custom MAIL FROM isn't checked).
  Its Easy DKIM tokens can't be found over DNS.
- **SendGrid:** SPF is inferred from its automated-security `s1._domainkey` CNAME into sendgrid.net,
  otherwise a low warning.
- **Other providers:** a missing SPF warns (medium). Only Resend's `send.<domain>` layout fails on a
  missing SPF.
- For Postmark and SES a DKIM record not found is a **low warning**, not a failure: ask the human to
  confirm DKIM shows verified in the provider's dashboard, and name it as unverified by golive.

# Neon

Automated database provider with mock coverage and an approved Netlify + Neon throwaway live run
on 2026-09-23. New Free-project creation, connection transfer to both hosting environments and
read-only database/role verification passed after the `--data=-` parser fix. Separately approved
schema, two-session API and browser CRUD/refresh checks also passed. Exact-resource cleanup later
passed under its own approval using a supervised fixture helper (Neon projects remain a manual
handoff in `golive teardown`).
This validates the tested Free organization and app, not every account or workload. It supplies
server-only pooled `db.url` and direct `db.directUrl`. It does not supply Supabase keys or migrate a
Supabase SDK application, and it does not provision Neon Auth, Data API or application schemas.

1. Have the human install `npm install -g neon` and run `neon auth` in a **separate terminal**.
   golive reuses the official CLI's login without reading its credential cache. The CLI must support
   `neon api`. Alternatively use `NEON_API_KEY`: on macOS run
   `credentials --prompt NEON_API_KEY --json` for private native entry. Their own editor is the
   fallback if unavailable, unsupported, or preferred; follow
   [How the human connects accounts](../SKILL.md#how-the-human-connects-accounts) for fallback,
   replacement and cancellation. Never print or
   inspect credential contents, pass keys on argv, or ask for a chat paste. An explicit token wins
   over the CLI login; fix a rejected token instead of silently switching identities.
2. Choose the exact organization (`neon.organizationId`, or non-secret `NEON_ORG_ID`). New project
   creation requires its API-confirmed `free` plan; several Free organizations need a choice. No
   upgrades, purchases or alternate-organization fallback are automated. Free quotas remain Neon
   enforced. New projects use `aws-us-east-2` unless `neon.region` is set, with fixed
   main/neondb/neondb_owner and 0.25 CU compute defaults. Do not set branch/database/role overrides
   for a new project.
3. For an existing project set `projects.db` to its exact ID, plus `neon.branchId`, `neon.database`
   and `neon.role`. Ask which existing branch the human wants; never infer a production/default
   branch. Same-name adoption without selectors is refused. These non-secret selectors appear in
   env approval. Both deployment targets use this selected branch; per-target branches are not
   automatically created.
4. Show the plan's account, org/project/region and connection selectors, obtain explicit approval,
   then apply. golive keeps returned credentials inside Secrets and transfers them directly to the
   chosen hosting env store. Never run a raw connection-string command in agent-visible output.
   A failed, timed-out or malformed creation response may still mean the create succeeded:
   inspect the exact approved organization and re-plan before another create. Pending project
   and operation IDs are saved for recovery; no password resets or automatic remote rollback.
5. `db-connection` uses one fixed read-only SQL transaction against the API-verified endpoint,
   and checks the exact database and role. It runs only on verified Free organizations. A pass
   proves connectivity from golive, **not** deployed app queries, schema, migrations, RLS or user
   isolation. Approve schema work separately and test real application behavior. Unsupported
   Supabase-specific checks remain skips.

Doctor success proves authentication reads, not create permission or quota. CLI failures emit only
fixed diagnostic categories; `unknown` does not mean the user needs to log in again. CLI 5.0.1
handler-only stdin testing initially missed the argv bug; exact parser coverage now verifies the
equals-form marker. The body stays in Secret stdin. Argument errors require checking syntax,
not automatically asking the user to upgrade.
If diagnostics remain unknown on a separately approved retry, return only an in-memory allowlisted
HTTP status/category. Never expose or save raw provider/debug output, and never retry a create just
to inspect its error.

Neon's official [CLI](https://neon.com/docs/reference/neon-cli),
[API](https://neon.com/docs/reference/api) and [remote MCP](https://mcp.neon.tech/mcp) are available.
MCP is optional and is not this adapter's transport. `neon init` or MCP setup can mint credentials
and change agent config; do not run it as a read-only login check.

# Netlify

Automated hosting: exact site select/create, site environment writes, official CLI build/deploy, and provider-confirmed URLs. Custom domain attachment, DNS and project visibility remain guided. The approved Netlify + Neon throwaway run on 2026-09-23 passed creation, env writes and deployment. After separately approved visibility UI changes, anonymous access and bundle scanning passed; API and browser CRUD/refresh supplied separate application acceptance evidence.

Exact-site cleanup later passed under its own approval, including an absent site and anonymous default-origin 404. Account logins, credential configuration and local evidence were retained. That cleanup used a supervised fixture helper, predating the built-in `golive teardown` flow. The built-in flow's own Netlify removal has since passed a disposable run: it deleted only the project golive had created and deployed in that same run, the account's site list counted 0 before the run, 1 during it and 0 after, and a second `teardown` planned nothing. The live results cover the tested apps and account scope.

## Login and selection

Ask the user to run `netlify login` in their own terminal when needed. The adapter reuses that login through the documented private current-user OAuth store, entirely in-process, and verifies the HTTPS identity matches the CLI. Never read or display that file using agent tools. Do not request a token in chat. The optional golive private `NETLIFY_AUTH_TOKEN` fallback must match the CLI principal; it is not a required second login.

Only if that fallback is needed, use `credentials --prompt NETLIFY_AUTH_TOKEN --json` on macOS.
The human enters the value in the private native dialog, never in arguments or chat. Their own
editor remains available if native entry is unavailable, unsupported, or preferred; follow
[How the human connects accounts](../SKILL.md#how-the-human-connects-accounts) for fallback,
replacement and cancellation.

Choose the exact site and team. `NETLIFY_ACCOUNT_ID` disambiguates teams. Site creation requires a specific approved team ID, a verified current Free plan and available documented site capacity. Paid, legacy Starter, unknown plans or unknown/exhausted capacity stop the automated write. Never upgrade or buy credits. [Login guide](https://docs.netlify.com/api-and-cli-guides/cli-guides/get-started-with-cli/), [Free plan](https://docs.netlify.com/manage/accounts-and-billing/billing/billing-for-credit-based-plans/credit-based-pricing-plans/).

## Environment and build boundary

Preview values target `deploy-preview`; production values target `production`. Public values use omitted scopes/Free defaults. Sensitive values remain write-only secrets with `builds`, `functions`, `runtime` scopes. Netlify's official Terraform provider explicitly documents this Free-plan exception; general documentation about paid custom scopes does not invalidate it. [Official env resource documentation](https://github.com/netlify/terraform-provider-netlify/blob/main/docs/resources/environment_variable.md), [implementation](https://github.com/netlify/terraform-provider-netlify/blob/main/internal/provider/environment_variable_resource.go).

Existing values are updated per context. Do not replace all contexts, widen scopes or downgrade an existing secret. Do not use `netlify api --data`, `env:set` argv or env-import files for secret transport; the adapter uses HTTPS bodies and headers and suppresses raw provider output.

Local Netlify builds see masked non-development secret values. Runtime-only server credentials fit this flow. If the application needs raw secrets during its build, explain the boundary and prepare a separately reviewed remote-build workflow; do not change secrets to readable values to get a passing build. [Secrets Controller](https://docs.netlify.com/build/environment-variables/secrets-controller/).

## Verify and report

The official CLI builds by default. Deployment targets the exact selected site with an explicit context; production adds `--prod`. Verify ready state, owning site ID and published production ID before reporting a URL. Only observed HTTPS Netlify default origins count; configured custom domains and guessed preview patterns do not.

Netlify may create projects with private visibility. The separate `netlify-public-access` check sends an anonymous homepage request after confirming a ready published production deployment. HTTP 401/403 or a Netlify access-control redirect produces a blocking exact-project handoff. Redirects are not followed, and 2xx proves only anonymous homepage access, not backend or UI correctness. Keep a successful deploy recorded as successful; visibility remediation does not require redeploying.

Open the exact project's **Project configuration → General → Visitor access → Project visibility**, and confirm its ID. If Netlify visitor protection blocks the intended public homepage, prepare **Private → Applies to: Previews only** to expose production while preserving private previews; the documented **Make public** action also preserves private previews. Do not select blanket Public or change team defaults. Show the exact change and get explicit approval before Save. Do not weaken application authentication or override a team-enforced restriction. Run `golive verify` afterward; only the passing anonymous check closes the handoff. No supported API, CLI or MCP visibility mutation exists. [Visibility documentation](https://docs.netlify.com/manage/security/secure-access-to-sites/project-visibility/), [official access-control guidance](https://github.com/netlify/context-and-tools/blob/main/skills/netlify-access-control/SKILL.md).

The official Netlify MCP exists, but is not used by the standalone adapter. Keep agent/plugin availability separate from adapter capability. [Netlify Codex/MCP setup](https://docs.netlify.com/build/build-with-ai/agent-setup-guides/set-up-codex-for-netlify/).

Report mock tests, source research and live evidence separately. Any live account write needs the exact golive plan approval first.

# Detect, plan, apply, verify: details

Load this when you need to explain a detect finding, a plan step, a handoff, why a check skipped, or
what a `status` drift item means. Provider-specific notes live in the other references.

## 1. Detect

`detect --json` returns `detect` (framework, `providers`, `envRefs`, `webhooks`, `notes`, …),
`env.mapped` / `env.unmapped`, `findings` and `suggestedStack`. Exit code 2 = a critical finding.

**Browser-exposed names.** Besides framework prefixes (`NEXT_PUBLIC_`, `VITE_`, `PUBLIC_`, …), detect
reads the framework config. Names inlined by next.config `env: {}`, by Vite/Astro `define` or webpack
`DefinePlugin` (`process.env.X` / `import.meta.env.X` keys, and env reads inside define values), or
matching a custom Vite `envPrefix` or SvelteKit `kit.env.publicPrefix`, count as client-exposed. golive
refuses to write a server secret into them (`secret-in-client-env`) and adds a note naming them.

**`config-inlines-all-env` (critical).** Raised when the config defines or spreads the whole
`process.env` / `import.meta.env`, a whole `loadEnv(mode, dir, '')` object, computed
`process.env.${k}` keys, or uses an empty public prefix. Every web-side env name is then treated as
public, so no server secret is written to that app's host until the config is fixed. Names used
only by Supabase Edge Functions (`supabase/functions/`) are not host env vars and are unaffected.
This also covers a `define` / `env` / `DefinePlugin` value that isn't an object literal: an
identifier, a call, shorthand `{ define }`, a spread identifier, and later mutations of the object.
If such a value (or a `'process.env'` define) can't be resolved and doesn't inline the whole env, a
**note** says "<file> <via> is set from an expression golive cannot read; make sure it holds no server
secrets". Read the config and confirm.

**Other detect output.** `configs` lists config files found, including Prisma schemas
(`schema.prisma`, `prisma/schema.prisma`, the `prisma/schema` directory, `prisma.config.ts`, a custom
package.json `prisma.schema` path). A `@prisma/client` or `prisma` dependency adds the note
"Prisma detected".

**Webhooks.** Each `webhooks[]` entry has `provider`, `path`, `file`, `verifiesSignature` and `events`:
the Stripe event types the handler references as string literals (case labels, `===` comparisons,
arrays, handler maps), sorted. `init` subscribes the endpoint to exactly these unless you pass
`--events`. If `events` is `[]`, a note says so: read the handler and pass `--events a,b`. Check
detected events against the handler the same way you check the path.

## 2. Plan

`plan --json` → `planId`, `steps[]` (`id`, `title`, `kind`, `writes`, `needs`, `preview`,
`dependsOn`), `handoffs[]`, `unmappedEnv`, `warnings`, `findings`. `targets[]` lists only the steps
that carry a structured `destination` (the project steps), so a teardown plan's `targets` is empty:
read the destinations from `steps[].preview` (and the step's `needs` confirm flags) instead. Previews
are deterministic: the same state gives the same `planId`. `teardown --json` returns the same shape;
its steps carry `kind: 'destroy'` and `needs` includes `--confirm-destroy`.

**Step intent.** A step may also carry a secret-free `intent`: what it writes beyond its preview text
(source project ids, key fingerprints, endpoint ids, the hosting project, a previous attempt's time).
It is part of the step's hash and the `planId`. `apply` skips a completed step only when preview,
intent, risk, dependencies and kind are all unchanged, so a step with the same preview as last time
but a different intent runs again: a db project switch, a Stripe key rotation or a domain re-attach
really lands. The deploy step's intent includes the env writes it picks up.

**Teardown.** `teardown` enumerates only golive-created resources with their ownership proofs
(provider markers, state fingerprints, the host project's creation marker): DNS records golive owns,
recorded webhook endpoints, issued sending keys and the created host project. A removal re-checks
ownership before deleting, and every removal treats "already gone" as done. A delete is confirmed by
a provider read, never by the delete response alone: the zone is re-read for a DNS record, the
project for the host project, and the provider's own endpoint list for a webhook endpoint — a
resource the provider still lists fails the step, while a read it cannot answer (auth, network) warns
instead of passing. No read exists for an issued sending key (the provider offers issue and revoke
only), so a revoked key stays **unverified**: the step reports `warn` naming the provider dashboard,
never a pass. A removal the provider's answer says is gone also forgets that resource's recorded
baseline — the `dns:<zone>|<type>|<name>` entry for a record, the endpoint id for a webhook, the key
id for a sending key — and removing the host project forgets its deploy facts (the `deployed:…` time
marker, the recorded deployment identity and the completed deploy step), so a later `golive status`
does not report golive's own teardown as drift and a project created again in the same repo is
deployed again rather than inheriting "production was deployed". A resource the provider still lists
or refused to remove keeps its record. Resources it cannot remove — adopted projects, Supabase/Neon
projects, the Resend sending domain — appear as non-blocking `manual` handoffs, and so does anything
the inventory could not even read: a DNS zone whose provider golive cannot use, cannot tell
golive-owned records apart in, or cannot delete from, and a linked host project golive cannot reach or
whose host exposes no project deletion. Each such row names what remains (from state, never a guess),
why golive cannot remove it and the exact fix — reconnect the provider and run `golive teardown`
again, name that provider in `golive.yaml` again, or delete it in the provider's dashboard — so a
teardown never goes quiet about records or a project left behind. Records or endpoints a human created
are never deleted.

**Which project.** Every plan has a step `project:hosting` / `project:db` naming the provider,
project name (id), team/org if known, where the choice came from, and the logged-in account.
- Already linked: a zero-write pin. At apply time it refuses if the linked project changed since
  approval, then pins it in `.golive/state.json`. After a full apply, `plan` shows only these pins,
  and applying them is a no-op (`skipped`).
- `golive.yaml` `projects.<axis>` disagrees with the linked project: `plan` warns and uses the linked
  one.
- Nothing linked: a configured (`init --project`) or same-named project is selected; otherwise a
  **Create** step whose preview lists existing projects the human could use instead. Ask them, and
  use `init --project <axis>=<name>` to adopt one.

**Deploys.** Production is (re)deployed when this plan writes production env, when a production env
write is still waiting for a deploy, when the last deploy failed, or when golive has never deployed
production. Preview-only env changes don't trigger a production deploy. If production was never
deployed by golive, `deploy:production` runs **before** `domain:attach`, and
`deploy:production:final` redeploys after env writes that need the domain (the webhook secret). Once
deployed, attaching a domain neither waits for nor triggers a deploy. A production deploy planned
while state records no successful production deploy for that target carries `risk.live`, so `apply`
also needs `--confirm-live`: the plan approval covers what the deploy writes, and this flag is the
human's separate yes to writing production there for the first time — explain that when you present
the plan (`deploy:production`, and `deploy:production:final` when it runs as part of that first
deploy, both carry it, and each step's preview says so). A failed attempt records no deploy, so the
gate stays on the next plan; once a successful production deploy is recorded for the target, later
deploys carry `risk: { writes: true }` alone and need no extra flag.

A successful deploy records the deployment the provider reported: the `deployed:production` time
marker plus, when the provider gives one, its own identity under `deployed:production:id` as
`<provider>|<deployment id>|<url>|<time>` in `.golive/state.json` — the name a later promotion or
rollback of exactly that deployment would use. A provider that reports no identity records the
marker alone; golive never derives one from the URL.

**Preview deployments (`release: { preview: true }` in `golive.yaml`).** With the opt-in — and
`preview` in `targets` — `plan` adds two steps at the end (a stack without the opt-in is unchanged),
and `apply` needs `--confirm-live` too when a live-mode value fills a preview env name:

- `preview:deploy` is a **create** (`risk: { writes: true }`, never `replayable`): it deploys the
  current working tree — the preview names the branch when local `git` reports one, because both hosts
  build what is on disk, not a commit — to the host's preview target. It depends on `project:hosting`
  and `env:preview`, and records the provider's own identity for the deployment it made as
  `deployed:preview:id` (the same shape production records, so a promotion can name it). Its
  preview names the provider and project, the env target, the preview URL the provider reports per
  deployment, and whether the preview shares production's source project: golive fills preview env from
  the same db/auth project as production, so a preview reads and writes production's data. It is
  planned for the same reasons a production deploy is (no preview deployed yet, preview env changes in
  this plan, the last preview deploy failed) plus a failed release check — a re-planned preview deploy
  always makes a new deployment, so the gate never re-checks a bundle golive did not replace.
- `release:check` writes nothing (`risk: { writes: false }`) and declares `preview:deploy` as its
  prerequisite — a declared edge, not an ordering accident: the plan's dependency helper keeps only step
  ids already tracked, so a gate built before its deploy declares no prerequisite and `apply --only
  release:check` runs the check against a deployment the plan never made. With the edge, that `--only`
  call is refused while `preview:deploy` has no completed evidence for the plan. It runs two checks as
  its inline verification and **fails the step when one fails**, and the runner stops the plan there.
  What that stops turns on the plan, and the step's own text says which: in a **cut** plan the gate is
  the last step, so it stops nothing emitted before it — that plan's own production deploy included —
  and it gates the promotion, whose plan re-runs the check before writing; in the **release** plan the
  gate is `promote:production`'s prerequisite, and a red gate stops the re-point. Its intent is the
  deploy's intent plus the previous attempt, so a re-plan checks again (the `domain:verify` idiom). It
  has a second mode: as the promotion's prerequisite it depends only on `project:hosting` and re-reads
  the preview deployment golive already recorded — the exact deployment `promote:production` would make
  production.

Adding these step ids changes a plan's id, so an approval that was not applied must be re-planned.

**Promotion and rollback (`release: { preview: true, promote: true }`, or `release: { rollback: true }`).**
Two production re-points, both **implemented and mock-covered, not live-validated**, and both planned
only when the human opted in:

- `promote:production` (`kind: 'deploy'`, `risk: { writes: true }`, `dependsOn: ['release:check']`)
  re-points production at the preview deployment golive recorded and that check just re-read. Its
  preview names the provider's own deployment id and URL, when golive recorded it, the env target it
  was built for, what production serves before, the gate, and that production will change. There is
  **no extra confirmation flag**: the plan id, the named deployment and the fresh gate are the
  approval. Because the provider reports a deployment's id only once the deployment is made, the plan
  that can name it is a different plan from the one that deploys it — with the opt-in set, a plan is
  either **cut** (`preview:deploy` + `release:check` at the end of the plan) or **release**
  (`release:check` + `promote:production`), and its preview says which. A **cut** plan changes nothing
  about the rest of the plan: its other steps, a production deploy included, are emitted before the
  preview steps, so the gate stops nothing that came before it; the gate's grip is the promotion. While
  `release.promote` is set, every plan asks for a release; remove the flag to stop planning releases.
  `run` re-reads the target deployment and
  what production serves before writing, refuses when the provider cannot answer either read (or the
  deployment is gone/not ready), then re-reads production after the write and records nothing unless
  the provider confirms the switch. Production already serving the target is a no-op.
- `release:rollback` (`kind: 'deploy'`, `risk: { writes: true }`) re-points production at an earlier
  deployment from golive's own trail (`deployed:history`). Its target is never a deployment golive did
  not create: a dashboard, Git or PR-built one stays with that provider. While `release.rollback` is
  set, a plan contains the rollback and no preview steps, and it stops planning one once golive has
  rolled production back to that deployment. It is not a `destroy` step
  (nothing is deleted) and not `replayable` (a production re-point keeps the cross-release stop, so a
  rollback recorded under an older release is refused and reconciled instead of repeated). It is never
  automatic — a failed check never triggers one — and once golive has rolled production back, a later
  plan reports that instead of planning the same rollback again.
- Both hosts differ: **Netlify** re-reads `published_deploy` and can restore an earlier deploy, so both
  steps work there; **Vercel** has no production-deployment read and no promote/rollback call, so no
  promotion or rollback is planned and a warning names the missing capability.

**Production URL before the first deploy.** Without a custom domain, the host's production URL is used
for the webhook, the auth site URL and `SITE_URL`-style vars only after golive has deployed production
once. Until then those are left out with a warning; run `plan` again after the first deploy.

**Env steps.** Each env-writing step is verified by a step-scoped check `<step-id>:env-written` (only
the names that step wrote, on its target). Vars golive manages are rewritten when the provider, the
mode, the db/auth project behind them, or the payment account/key behind them changes.

**Domain.** `domain:attach` → `domain:dns` (DNS writes, `--confirm-dns`; verified against the zone's
records) → `domain:verify` (asks the host to verify ownership; on Vercel this can move the domain
from another account of the same host). `pending` there is not a failure: DNS is propagating, and
each new `plan` asks again (its preview shows `previous request: <time>`). While the domain isn't
live, each plan also re-sends `domain:attach` (idempotent). If at apply time the host requires
different records than the approved plan listed, `domain:dns` refuses and writes nothing: run
`plan` again and get re-approval with `--confirm-dns`. `domain-live` is left to `verify`. If the DNS zone lookup fails (token
permissions, rate limit, network), `plan` warns and plans no DNS step.

**Auth redirects.** Preview-deployment wildcards go into the (production) auth redirect allowlist only
with `auth.previewRedirects: true` in `golive.yaml`, and each such line is flagged as a risk.
Otherwise `plan` warns that sign-in on preview URLs won't work.

**Auth policy.** `auth:settings` writes only the values from `golive.yaml` `auth` that differ from
what the provider reports (`signup`, `requireEmailConfirm`, `passwordMinLength`), then re-reads them;
the step's own `auth:settings:applied` result and the `auth-policy` check carry that evidence. A
setting the provider does not report back shows as `not confirmed:` in the step's changes and does
not fail it; a value the provider keeps reporting differently fails the step. Changing a value in
`golive.yaml`, or changing it back in the provider dashboard, changes the step's intent, so it runs
again.

**Auth SMTP (`auth.smtp: resend`).** A separate step (`auth:smtp`, `risk: { writes }`, no new flag)
points the auth project's custom SMTP at Resend: `smtp.resend.com:465`, the user `resend`, the sender
`email.from` already uses, and an SMTP password that is a sending key — the one the email journey
issued in this run, otherwise one golive issues for SMTP alone (`golive-…-smtp`, state key
`<provider>.keyId@smtp`, so `teardown` can revoke it). The same write raises the project's **auth email
rate limit** (`rate_limit_email_sent`) to 30 per hour, or to `auth.emailRateLimitPerHour` from
`golive.yaml`: the provider keeps its own limit with custom SMTP in place and one run of the journeys
needs four accepted sends. Unlike an SMTP field, a limit the provider keeps at another value does not
fail the step — the provider's own setting, reported by `auth:smtp:applied:rate-limit` (medium) — and
one it never reports back is named as unconfirmed. Otherwise it writes only the fields that differ and
plans nothing once they hold; its own `auth:smtp:applied` result plus the `auth-policy` check carry the
evidence. The password is write-only (`smtp_pass` answers a hash, never the value), so what is
confirmed is the settings golive can read back and the write itself — a real auth email arriving is
the only full proof, and the journeys below run after this step so their sends are the one that
counts. Auth emails still going through the provider's built-in mailer warn (its limit can refuse the
sends a journey needs, HTTP 429, roughly one accepted send per window) unless `auth.smtp: provider`
accepts that deliberately.

**Auth signup journey (`auth.e2e: true`).** The `auth:test-user` step creates ONE real account in the
project through the provider's own signup endpoint (`risk: { writes, live }`, so it needs
`--confirm-live`) and records the user id and the address in `.golive/state.json`; the generated
password lives only in that run's memory. Its intent carries the previous attempt, so a fresh
`plan` + `apply` re-runs it — as a password rotation on the same account — which is how a later run
can prove login again. `auth:confirm-email` (non-blocking, verified by `auth-signup`) is the human's
click in the inbox. Both checks are opt-in:

- `auth-signup` signs up a fresh probe address (`auth.testEmail` plus a random `+gl-…` tag) and
  requires a confirmation email, requires an immediate login refusal (`email_not_confirmed`) and
  requires the seeded account to read back as `email_confirmed_at` after the click. Those three
  provider reads are the whole pass rule, so a `handoff` — or a `verify` outside the seeding apply —
  can report a complete handoff as done. The confirmed account's own sign-in is added as extra
  evidence when this run holds that account's password (the apply that seeded or rotated it); when it
  does not, an evidence line says so and names where the login is exercised instead of skipping.
  golive cannot read an inbox: delivery and the click stay human-confirmed, and the evidence says so.
- `auth-session` requires a session for the seeded account, requires `GET /auth/v1/user` to return
  the same user, requires an anonymous request to be 401, and — with `auth.protectedPath` — requires
  an anonymous GET of the host-confirmed production URL plus that path to redirect or answer
  401/403 (a 200 fails; a 404 warns). A 401/403 there is corroborated with one more anonymous GET of
  the production root: an edge wall (a WAF, edge rule, visitor access, a maintenance page) refuses
  the root too, so the leg reports **inconclusive** (warn, naming the wall) instead of protection
  whenever the public route is not readable. Its table probe uses the session token — anonymity
  stays `rls-probe`'s job — and names the schema-qualified tables it read per verdict (up to four
  names each, then `+N more`), so the count line can be audited back to a table.

Both checks write when they run (one throwaway account per run) and skip, never fail, without the
opt-in, without `auth.testEmail`, without a usable provider credential, or when a captcha blocks the
scripted signup. `auth-session` also skips when this run holds no password for the seeded account:
without one there is no session to inspect.

**Auth password recovery (`auth.recovery: true`).** `auth:recovery` sends a real recovery email for the
recorded test account, mints a recovery link through the provider's admin API (so golive never needs to
read the inbox), exchanges its token for a session and sets a new password with that session, then
keeps that password under the key `auth.e2e` uses — so `auth-signup`/`auth-session` keep working in the
same run. Its risk is `{ writes, live, replayable }`: `--confirm-live` is required, it re-reads the
recorded account and its provider state before acting (and waits at plan time until that account reads
back confirmed, warning instead of planning), and it only ever touches that one account.
`auth:recovery-email` (non-blocking, verified by `auth-recovery`) is the human's click. The check needs
what that step left in the run's memory — the spent token and the two passwords — so a `verify` outside
that run skips with `this run holds none of what the recovery check needs`; it asserts that an address
with no account is answered like a known one (a different answer is account enumeration and fails),
that the spent token is refused on replay, and that the new password signs in while the replaced one
does not. A 429 anywhere in it warns, never fails: the provider's mail throttle decides what a run can
prove.

**Auth account isolation (`auth.isolation: true`).** The second half of the journey: with TWO real
accounts, golive can ask whether one signed-in account can read the other's data through the app. The
`auth:isolation` step (risk `{ writes, live, replayable }`, so `--confirm-live`) seeds or rotates a
SECOND account beside the one `auth:test-user` seeds — the same provider signup, the address derived
from `auth.testEmail` (`you+gl-isolation@example.com`), the password again only in that run's memory —
and confirms it through the provider's **admin API**, re-reading it before the step reports done: a
second inbox click would spend the throttled mail budget on a journey whose subject is the app's data,
not delivery. The step reads the recorded account and its provider state before acting and only ever
touches accounts golive created and recorded. `auth.e2e: true` and `auth.testEmail` are prerequisites
(the first account's password comes from `auth:test-user` in the same run); a plan says so and waits
when the first account is missing or unconfirmed.

The app has to answer for itself: `auth.identityPath` and `auth.isolationPath` in `golive.yaml` name
two routes — one that returns the signed-in caller's OWN identity (its provider user id) as JSON, one
that returns ONLY the caller's own rows (a GET) and stores one row for the caller for a POST body
`{"marker": "…"}`. Both must refuse an anonymous request (401/403 or a redirect). `auth:isolation-routes`
(non-blocking, verified by `auth-isolation`) hands that app-code task to the agent or the human when
either route is not declared.

`auth-isolation` needs both accounts' passwords, so it only passes in the run that seeds or rotates
them; otherwise it skips with `blocked by: no password for … in this run`. With both sessions it reads
both routes anonymously (**a 200 is a critical finding**, whoever the caller is), then reads the
identity route as each account (each must answer with its own id, never the other's) and writes one
unique marker row per account **through the app's own rows route**, then reads it back as each: a
response carrying the other account's marker is a cross-account read and fails critically. It skips —
never passes — when the opt-in is off, either route is not declared, the app answers 404 (the app-code
task is named), the route refuses the session token it was given, the host cannot confirm the
production URL, or the provider or the app rate-limits a request. A route that answers without the
caller's own id or marker only warns: the absence of the other account's data is then not attributable.
It never probes a table anonymously — that stays `rls-probe`'s job.

**Email.** `email:verify` is re-sent on each plan while the domain is pending; its preview shows
`previous request: <time>`.

**Secrets exposed.** A critical detect finding (or a client-prefixed secret name) blocks secret writes
for the affected names: env, payments keys, email key, and the whole webhook step. A blocking
handoff `secrets:exposed` tells the human to fix the code first. It disappears once detect stops
reporting the finding.

**Webhook.** The preview names exactly the endpoint apply will adopt, including one the human created
at the same URL: whether its events are kept, whether it will be re-enabled, and whether the old
endpoint is deleted or left for the human to delete. Apply refuses without writing if the endpoint
changed since approval. When the production URL changed, it also says the golive-created endpoint for
the old URL is deleted once the new secret is stored. If the host would refuse the secret
(`EnvStore.canSet`), a blocking `<adapter>:webhook-env` handoff replaces the step and no endpoint is
created. With a guided host, a blocking `<adapter>:webhook-guided` handoff (verified by
`webhook-registered`) asks the human to create it. See `stripe.md`.

## 3. Handoffs

Each handoff has `id`, `why`, `action`, `blocking`, and optionally `verifiedBy` (a check id) or
`manual: true`. `handoff --json` adds `done` and `evidence`:
- `done: true`: its check passed. Only a passing check closes a handoff.
- `done: false`: open. Its check ran and did not pass, or it has no check and isn't `manual` (it is in
  the plan only because its condition still holds, e.g. `secrets:exposed`, `stripe:webhook-env`).
  Blocking ones count in `apply`'s open handoffs and the report's `blocking`.
- `done: null`: golive cannot verify it (a `manual` item, or its check skipped). Confirm it with the
  human and list it as **not verified by golive** in your summary. `unverified` lists them. When a
  check can only skip outside the run that did the work (e.g. `auth-recovery`, whose token and
  passwords live in that run's memory), its evidence leads with the recorded outcome of the plan step
  that check verifies — a step recorded `done` with its plan id and time, or a failed one with its
  recorded error — so a skip never reads as if the work never happened; the skip itself is still named.

Common ones: `login:<provider>`, `project:<axis>` (golive can't create it), `secrets:exposed`,
`db:password`, `stripe:activate`, `stripe:publishable-key:<mode>` (ask for the `pk_` key in chat,
then `init --stripe-publishable <mode>=pk_<mode>_…`; or the human adds it to the host dashboard),
`stripe:secret-key:<mode>` (the credentials-file instructions in its `action`; never chat),
`email:dns` / `domain:dns` / `domain:attach` (records or setup at a provider golive can't write),
`guided:<axis>`, `env:<target>` for a guided host (per target: the human sets the listed names in its
dashboard; `env-parity` can't read a guided host, so it stays `done: null`),
`stripe:webhook-env` / `stripe:webhook-guided` (see Webhook above), `auth:confirm-email` (non-blocking,
verified by `auth-signup`: the human clicks the confirmation link in their own inbox, which golive
cannot read), `auth:recovery-email` (non-blocking, verified by `auth-recovery`: the same for the
recovery link — golive requests it and mints its own copy, the human clicks theirs),
`auth:isolation-routes` (non-blocking, verified by `auth-isolation`: the app must expose the two
declared routes, which only the agent or the human can add — golive names exactly what they answer and
drops the handoff once both paths are declared), and
`auth:redirects` for a guided auth provider (manual, non-blocking: confirm it with
the human, name it as unverified).

**Ownership document.** `handoff --write --json` also writes `GOLIVE_HANDOVER.md` and
`.golive/handover.json` (paths are reported as `handoverPaths`; `--force` replaces a file golive did
not generate — a file without the "Generated by golive" marker is never overwritten, and a symlink is
never followed). It is built from recorded state, `golive.yaml`, the cheap provider reads
`doctor`/`verify` already make (`auth().via`, project scope and URLs) and the teardown inventory —
never from `state.secrets` or an `Outputs` value, never from a billing endpoint. Sections: accounts and
login route; resources created (id, public URL, ownership proof, created-by-golive vs adopted); costs
and recurrence (no figures at all: golive reads no plan, quota or usage data); what is manual (the open
handoffs plus recurring jobs — DMARC tightening, key rotation, backups, domain renewal); if it breaks
(per-subject `doctor` / `verify --only` commands, `plan` → `apply` → `verify`, and where evidence
lives); retirement (the teardown inventory with its `--confirm-destroy` / `--confirm-dns` gates); and a
provenance footer. Every row carries `[verified by golive]`, `[recorded <date>, not re-checked]`,
`[not verifiable by golive]` or `[unknown]`. Treat the last three as unverified: this document is not
drift detection. It holds no secret values, but it names accounts and resources — review it before
sharing it. Recommend adding `.golive/`, `GOLIVE_REPORT.md` and `GOLIVE_HANDOVER.md` to the app's own
`.gitignore`: state, report and handover carry resource ids and account names, while credential
values live outside the repo in the private credentials file.

## 4. Verify

`verify --json` runs every check. `--only id,id` writes a partial report containing only results
from this invocation; omitted checks are listed and previous results are not reused. Neither scope
establishes whole-app readiness: review pending plan steps and app functional acceptance. Verification
writes `.golive/report.json` and `GOLIVE_REPORT.md` (old `SHIP_REPORT.md` files are preserved).
Exit 2 when any check fails. `summary` counts
`pass`, `fail`, `warn`, `skip`, `blocking` (open blocking handoffs) and `manual` (blocking ones golive
can't verify).

**`skip` = blocked or not applicable, never passed.** Evidence `blocked by: <id>` names what's
missing: `login:<adapter>`, `project:hosting`, `project:db`, `deploy:production`, `email:domain`, or a
plain reason (e.g. `no publishable/anon key`, `the hosting token's role cannot read production env
vars`). Only `accounts` fails for login problems; fix it first, then re-run `verify`.

**Active probes** (`bundle-secrets`, `webhook-unsigned`, `auth-session`'s protected-path GET and the
public-root GET that corroborates it, `auth-isolation`'s route reads and its one marker row per test
account, and the key `rls-probe` takes from the bundle) only target the production URL the hosting
adapter reports
for the linked project, never `config.domain` directly. If the host can't confirm it, the check skips with `cannot confirm <url>
belongs to your project yet`. If the host reports another origin than `config.domain` (e.g. the domain
isn't verified at Vercel yet), `webhook-unsigned` probes the host's URL and says so. `domain-live`
does resolve and GET `config.domain`. `preview-bundle` is the one probe outside production: it scans
the preview URL the hosting adapter reports for the linked project — never a URL golive only has in
state — and a protected preview skips instead of being reported as scanned.

| id | passes when | skips when |
|---|---|---|
| `accounts` | every automated provider authenticates | nothing chosen |
| `env-parity` | every referenced name exists per target (names only; unmapped missing names only warn) | guided host; a source provider not logged in (`blocked by: login:<id> (NAME@target, …)`); the role can't read production env |
| `domain-live` | automated host reports the domain `ok` (`pending` warns), it resolves, HTTPS answers 2xx/3xx; guided/no host: DNS + HTTPS only, evidence says the attachment isn't confirmed | no domain; `blocked by: login:<host>` / `project:hosting`; the host's status lookup errors (`cannot confirm <d> is attached …`) |
| `bundle-secrets` | no known credential patterns in the complete bounded fetch set | production URL not confirmed; **warns** on asset fetch failures, scan limits or off-origin production redirects |
| `rls-probe` | tables in exposed schemas aren't readable with the publishable key; advisors clean | `blocked by: project:db`; no publishable/anon key |
| `db-connection` | the selected Neon compute accepts a fixed read-only query and returns the expected database and role; no schema/Auth/app-isolation claim | no connection-probe capability; `blocked by: login:<db>` / `project:db` |
| `auth-redirects` | site URL and allowlist point at production, no localhost | guided auth; `blocked by: deploy:production` |
| `auth-policy` | the reported signup/confirmation/password policy matches golive.yaml `auth` (below 12 characters, a built-in mailer, an unapplied `auth.smtp: resend` or an auth email rate limit below a run's four sends only warn); the mailer is reported as the provider's built-in one or as custom SMTP via Resend, and the SMTP password is never read back; evidence lists the effective values | guided auth; `blocked by: login:<id>` / `project:<axis>`; the provider reports no policy fields |
| `auth-signup` | a fresh probe address got a confirmation email, could not sign in before confirming, and the seeded account reads back confirmed (`email_confirmed_at`) — the confirmed account's own sign-in is extra evidence when this run holds its password (delivery stays human-confirmed) | `auth.e2e` off; no `auth.testEmail`; guided auth; `blocked by: login:<id>` / `auth:test-user`; a captcha blocks signup; **warns** on a 429 or while the account is still unconfirmed |
| `auth-session` | the seeded account's session is accepted for the same user, an anonymous request is 401, and a declared `auth.protectedPath` is refused while the production root still answers (each refusal is corroborated against that public route); the signed-in table probe names the tables it read per verdict | `auth.e2e` off; guided auth; `blocked by: login:<id>` / `auth:test-user` / `no password for the test account in this run`; **warns** on a 429, an unconfirmed account, every exposed table denying the signed-in user, or an inconclusive protected-path answer (the root is walled or unreadable too) |
| `auth-recovery` | the recorded account's recovery request is accepted for sending, an address with no account gets the same answer (no account enumeration), the token this run spent is refused on replay, the new password signs in and the replaced one is refused, and the token window is named from `otpExpirySeconds` when reported | `auth.recovery` off; guided auth; `blocked by: login:<id>` / `auth:test-user`; no rotation in this run (`this run holds none of what the recovery check needs`); a captcha blocks a scripted request; **warns** on a 429 for either request or a login leg, never fails |
| `auth-isolation` | two accounts golive seeded and recorded sign in, both declared routes refuse an anonymous request, each account's identity route answers with its own id (never the other's), and each account's rows route returns its own marker row and none of the other's | `auth.isolation` off; no `auth.identityPath`/`auth.isolationPath` declared; guided auth; `blocked by: login:<id>` / `auth:test-user` / `auth:isolation` / `no password for … in this run`; production URL not confirmed; a route answers 404 or refuses the session token (the app-code task is named); a route does not accept the marker write; a 429 from the provider or the app. **Fails critical** on an anonymous 200, a crossed id or another account's marker; **warns** while an account is unconfirmed, on an inconclusive status, or when nothing in the answer is attributable |
| `webhook-unsigned` | an unsigned POST gets 4xx from the handler (a non-HTML 401/403 only warns — ambiguous between a rejection and an auth wall) | production URL not confirmed |
| `webhook-registered` | an enabled endpoint for the production URL covers the configured events | guided payments; no production URL |
| `stripe-live-ready` | the account has `charges_enabled` | production isn't live mode |
| `email-dns` | the provider's listed records (or common locations) and DMARC are in public DNS | no sending domain |
| `email-verified` | the provider marks the domain verified **and** the records it lists for that domain resolve in public DNS (a provider that cannot list them, lists none, or a lookup that failed, warns or skips — never a pass) | guided email; `blocked by: email:domain`; the provider exposes no record list, or lists none golive can resolve |
| `preview-deploy` | the hosting provider's own read confirms the preview deployment golive recorded (`deployed:preview:id`) is ready, belongs to the project this repo links and is not the production deployment | no recorded preview deployment; the recording belongs to another provider; a guided or logged-out host; a host with no per-deployment preview read (Vercel). **Warns** when the host reports a different preview deployment than the recorded one; **fails** when the recorded "preview" is the production deployment |
| `preview-bundle` | the HTML/JavaScript served by the provider-confirmed preview URL is scanned completely and holds no known credential patterns | no provider-confirmed preview URL; **skips** a 401/403 protection wall (a private preview is normal and is never a pass); **warns** on an incomplete scan or a page that did not load; **fails critical** on a leaked pattern |
| `production-release` | the provider's own read of what production serves is the deployment golive promoted or rolled back to (`deployed:release`), with what production served before named. Runs while `release.promote`/`release.rollback` is set, and afterwards for as long as a release is recorded (the opt-in can be removed and the evidence stays readable) | no recorded release; a guided or logged-out host; a host with no read of what production serves (Vercel); the provider reports no production deployment; another provider's recording. **Warns** when the provider read fails, or when production serves a deployment golive never recorded (a dashboard/Git/PR-built one — a handoff for the human); **fails** when production serves another deployment golive recorded (something moved production after the release) |

Details that trip people up:
- `env-parity` doesn't require `STRIPE_WEBHOOK_SECRET` (or other webhook-secret names) outside
  production: the webhook is registered and its secret written for production only. It doesn't
  require site-URL vars for a target with no stable URL (Vercel preview; production before the first
  deploy without a domain). These show as `not required` evidence lines. If the app needs e.g.
  `NEXT_PUBLIC_SITE_URL` in preview, the human sets it.
- `domain-live` warns "not propagated yet" (instead of failing) only right after a `domain:dns` step.
- `email-dns` checks exactly the records the provider lists once a sending domain id is recorded; a
  missing provider DKIM record fails. A missing DMARC record only warns and suggests one; golive does
  not write DMARC. Without that list it uses each provider's usual layout: a missing SPF fails only
  for Resend's `send.<domain>`; Postmark / SES DKIM selectors can't be found over DNS, so not finding
  one is a low warning (confirm DKIM in the provider dashboard). Details in `guided.md`.
- `email-verified` corroborates the flag instead of trusting it: it resolves exactly the records the
  provider lists for the domain and **fails** when they are gone — a zone cleaned up, moved between
  accounts or restored from a backup leaves the domain reading `verified` while nothing in DNS
  carries its SPF/DKIM ([#52](https://github.com/mikehasa/golive-skill/issues/52)). It **warns** when
  a record golive wrote is still inside the 48 h propagation window (a cached answer or a zone
  wildcard can answer first) or when a lookup failed; it **skips** when the provider exposes no record
  list, lists none, or the read failed. A warn or a skip is never a pass. The email link keeps its DNS
  work for such a domain too: the `email:dns` step (or the blocking handoff when golive cannot write
  DNS) stays planned, and the step's intent carries the unresolved records, so `apply` writes them
  again rather than skipping a step it recorded done when they matched.

## 5. Status (drift): what changed behind golive's back

`status --json` is the only command that asks whether the world still matches what golive **recorded**
— which is why no check can answer it: a check's report is release evidence for this invocation, while
drift needs the recorded side (state resources and step evidence, or a marker the provider assigned).
Run it once the app is live, before a release and after a run that changed providers or settings. It
writes nothing: no report, no state change, no provider write, and exit `2` means at least one item has
an `action` other than `none`.

Each item pairs `expected (recorded by golive <time>)` with `observed (read now)` and says who can act:
`verify` (re-run the named `checkId`), `reconcile` (an approved `plan` → `apply` restores it; DNS steps
still need `--confirm-dns`) or `human` (only the human decides, e.g. the credential now reads a
different account, or a project cannot be read at all). Severity: `high` = the app is broken (a record
deleted, an endpoint gone, a domain detached, a project unreadable); `medium` = hygiene or teardown
safety, or a change that may be deliberate; `info` = nothing to act on. Subjects: DNS records golive
wrote (checked against the zone, and against public DNS only while the zone still matches the baseline
— a record written inside the propagation window may legitimately differ publicly and is `info`), public
name-server delegation, golive-managed env **names** (never values: hosts hide sensitive values and
golive stores fingerprints, so a rotated value is outside the comparison), the recorded webhook endpoint
(gone, disabled, or missing events; a replacement at the same URL names the now-stale signing secret),
the domain attachment plus the records the host now requires, the db project and its
branch/database/role selectors, the sending domain, issued sending keys (no provider read exists, so
they are reported as unverifiable rather than checked off), the payment account and mode behind the
app's keys (a 403 is unverifiable, never drift), the host project identity and its creation marker, and
unfinished release state (a production env write no deploy picked up, a failed step).

A failed step is compared with the plan this release would run now, because that decides what an
operator can do: when the recorded step belongs to another (or an unknown) release and declares
neither `destroy` nor `risk.replayable`, `apply` refuses to replay the write, so the item is `human`
and points at the reviewed reconciliation path in [updates](updates.md) instead of an impossible
`apply --plan <planId>`. A step this release recorded, or one that declares the exemption, keeps the
plain re-run advice.

A provider that cannot be read yields `unverifiable: true` with `action: 'none'` and appears in
`notChecked`: never drift, and never "clean". `verified` lists the subjects read and found unchanged —
the only thing a "nothing changed" statement may cover; `limits` names what this comparison can never
see. Drift is never a gate: `plan` and `apply` do not consult it, and nothing is re-baselined except by
an approved write.

# Porkbun DNS: agent notes

Use this when `dns=porkbun`. The adapter manages DNS only. It never buys/transfers/renews a domain
or changes nameservers. Every write needs the human's specific plan approval and `--confirm-dns`.

## Connect the account

1. The human opens <https://porkbun.com/account/api>, creates a dedicated API key pair, and
   restricts it to the intended test domain.
2. In Domain Management, they enable **API Access** for that domain.
3. On macOS run `credentials --prompt PORKBUN_API_KEY --json`, then
   `credentials --prompt PORKBUN_SECRET_API_KEY --json`; the human enters each value in its private
   native dialog. Their own editor is the fallback if unavailable, unsupported, or preferred; follow
   [How the human connects accounts](../SKILL.md#how-the-human-connects-accounts) for fallback,
   replacement and cancellation. Never put either value in arguments or chat, or inspect the file.
4. Run `doctor`. golive checks the pair without showing values. No CLI or MCP installation is
   required. The official [Porkbun MCP](https://porkbun.com/mcp) is optional and is not how this
   adapter executes writes.

## Choose the actual DNS provider

Buying a domain at Porkbun does not mean Porkbun serves its DNS. golive verifies account ownership,
API access, registry nameservers, and public nameservers. If Cloudflare, GoDaddy, or another
provider is authoritative, use that DNS adapter. Nameserver migration is a separate human task.
Delegated child zones are not written through the parent zone.

## What the plan can change

- Create missing records with `golive: managed` notes, adopt exact matches, or update one matching
  golive-owned record by ID. Unrelated records are preserved.
- Merge a new sender into one existing SPF record while retaining the owner's mail policy.
- Stop for foreign/ambiguous address, DKIM, return-path, CNAME, or ALIAS conflicts. The human
  reviews those records in the dashboard before re-planning.
- Use the hosting provider's A/AAAA record at the apex. golive does not convert apex CNAME to ALIAS.

After apply, run `verify`. DNS propagation and the host/email provider's verification may still
be pending even after the Porkbun API accepts a write. Re-plan if the API returns a warning or
an uncertain result; a write may have been stored already, and the next run re-lists first.

## Troubleshooting

- Missing/invalid pair: recreate it in the dashboard and update the private credentials file.
  `INVALID_API_KEYS_002` means the API key and secret do not match — re-enter the mistyped value
  with `credentials --prompt PORKBUN_SECRET_API_KEY --replace`.
- Domain/IP restriction: verify that the key covers this domain and this machine's network.
- API Access disabled: enable it for this one domain in Domain Management.
- Authority unconfirmed: inspect public/registry nameservers and delegated child zones; retry
  after propagation. Do not change nameservers as a workaround inside this task.
- Multiple SPF records: the human must merge them into one valid policy first.
- Sandbox key: sandbox DNS is simulated and cannot satisfy live DNS checks; the adapter refuses
  it. Live DNS acceptance needs a scoped real key, an existing throwaway domain, and approval.

Status: the Vercel-attached custom-domain journey (one approved CNAME write, ownership verification,
HTTPS serving) passed a disposable live run. Other host pairings and the mocked-only create-response
repair await their live exercises.

# Resend (email): agent notes

Load this when the plan uses `email=resend`.

Status: the disposable live run passed end to end — domain created through the CLI transport, records
written to an automated DNS provider, domain verified, sending-scoped keys issued into the app's env,
and a send using that environment key was delivered (spam folder; fresh subdomain, no DMARC). Auth
SMTP is wired from a sending key golive issues (`auth:smtp`, with `auth.smtp: resend`) and that write
is live-validated (2026-09-24: the settings and the raised auth email rate limit read back; the
password itself is write-only); bounce handling remains open. A sending domain's `verified` flag can
be stale — a zone cleaned up, moved or restored leaves it reading `verified` with its records gone
([#52](https://github.com/mikehasa/golive-skill/issues/52)) — so `email-verified` resolves the records
Resend itself lists before passing, and the plan keeps writing them when they are missing.

## 1. Logging in (least friction first)

1. **`resend login` (preferred).** Install (`npm i -g resend-cli` or `brew install resend/cli/resend`),
   then the human runs `resend login` in a **separate terminal window** (the Terminal app or their
   IDE's terminal; not Claude Code's `!` prefix, which has no TTY for its interactive picker) and
   picks **"Login with Resend (opens browser)"**. They click Authorize; nothing is copied. golive uses
   this login first, even if a `RESEND_API_KEY` is also around.
   - Never suggest `resend login --key …`: it puts the key on the command line.
2. **Full access API key (alternative).** Resend dashboard → API Keys → create a key with **Full
   access** (golive creates domains and keys, which sending-only keys can't). On macOS run
   `credentials --prompt RESEND_API_KEY --json` for private native entry. Their own editor is the
   fallback if unavailable, unsupported, or preferred; follow
   [How the human connects accounts](../SKILL.md#how-the-human-connects-accounts) for fallback,
   replacement and cancellation. Never put the value in chat or arguments; a key exported in their
   own terminal doesn't reach the agent's shell.
   - A **sending-only** key there (common from local app development) fails with
     `restricted_api_key`: replace it with a Full access key, or use `resend login`.

## 2. What golive does vs. what stays with the human

golive automates (after plan approval; DNS writes need `--confirm-dns`):
- `email:domain`: finds and **adopts** the sending domain in Resend, or adds it (in `email.region`
  from `golive.yaml` if set), with open/click tracking off. Its changes list the DNS records Resend
  asks for (they differ by domain age and region; never hard-code them).
- `email:dns`: writes exactly those records through an automated DNS provider (e.g.
  `cloudflare-dns`), or they become an `email:dns` handoff for a guided DNS host. Record names
  relative to the apex are resolved correctly, also under short-SLD ccTLDs (e.g. `send.notify.app`
  for `notify.app.hey.io` becomes `send.notify.app.hey.io`). golive does **not** add a DMARC record;
  `email-dns` warns when none exists and suggests one for the human to add.
- `email:verify`: asks Resend to verify (safe to retry); `pending` is not a failure.
- `email:key:<target>`: **mints a new sending-only key scoped to that domain, per environment**, and
  writes it straight into the host env name the code reads (usually `RESEND_API_KEY`). Resend shows a
  key once, so "adopt" means "issue a new one". Older golive keys are **left active**: the change log
  names them, and the human revokes them in Resend once nothing uses them.
- Verifies: `email-dns` (the exact records Resend lists for the domain, plus DMARC, in public DNS; a
  missing DKIM record fails) and `email-verified` (Resend marks the domain verified **and** the records
  it lists for that domain resolve in public DNS — a stale `verified` whose records are gone fails
  with the records named, #52).

Not automated yet: the from-address env var (the human sets it if the code reads one) and a test send.
Resend as Supabase Auth's SMTP server is written by the `auth:smtp` step when `auth.smtp: resend` is
set (host `smtp.resend.com`, port 465, user `resend`): it takes the SMTP password from the key the
email journey issued in the same run, or issues `golive-<app>-smtp` for that purpose alone and records
it like every other key, and it raises Supabase's own auth email rate limit to 30 per hour (or
`auth.emailRateLimitPerHour`) in the same write, since the provider keeps that limit with custom SMTP.
See `supabase.md` for the step's read-back limit (the provider never returns the password).

Stays with the human (and why):
- **A domain already registered by another Resend team.** Claiming it needs a TXT record and gives
  the domain new DKIM keys. Ask before starting a claim.
- **DNS at a provider golive doesn't automate.** The human adds the exact records from `plan`/`handoff`.
- Revoking old keys, plan upgrades (free plan: 100 emails/day, 3,000/month, 3 domains).

## 3. Explain these in plain words

- **Proxy off.** On Cloudflare, Resend's CNAME records must be "DNS only" (grey cloud). Proxied ones
  never verify.
- **One SPF record per name.** Resend usually puts SPF on a subdomain (`send.<domain>`), so the main
  domain's SPF often isn't touched. If a merge is needed, it's merged into the existing record, never
  added as a second one.
- **`send.` already in use?** A CNAME can't share a name with other records. golive stops with a
  conflict instead of overwriting. Resend supports a different custom return path (e.g. `bounce`),
  chosen when the domain is added; raise it with the human.
- **Recreated domain or changed region:** the DKIM key and return-path MX change. With Cloudflare,
  golive replaces the stale records it created; records someone else created stop it with a conflict.
- **Verification can take minutes up to 72 hours.** After 72 hours without records Resend marks the
  domain `failed`. `partially_verified` can send but has no fallback; finish the missing record.
- **Tracking off for auth emails.** Open/click tracking rewrites links and breaks Supabase magic
  links. Domains golive creates have it off.
- **`onboarding@resend.dev`** only sends to the account owner's own address. Production needs the
  verified domain.
- **Never expose the key to the browser.** `NEXT_PUBLIC_RESEND_API_KEY` (or any public prefix) is a
  leak; `detect` flags it and golive won't write the key there.

## 4. Troubleshooting

| Symptom | What to do |
|---|---|
| `doctor`: not authenticated | Human runs `resend login` in a real terminal window (not `!`), browser option. Never `--key`. |
| `401 restricted_api_key` on setup | A sending-only key is in use. Use `resend login` or a Full access key in the credentials file (§1). |
| `403 validation_error` "has been registered already" | Another Resend team owns the domain. Claim flow, with the human's OK. |
| Domain stuck `pending` / `failed` | Records missing, proxied, or entered with the domain twice (`send.example.com.example.com`). Compare with `verify`'s `email-dns` evidence. |
| Domain reads `verified` but mail fails SPF/DKIM | The flag is stale: the records Resend lists are not in DNS (a cleaned-up zone, a domain moved between teams or a restored backup). `email-verified` fails on exactly this, naming the records. Re-run `plan` + `apply --confirm-dns` to write them, or add them by hand at your DNS host; the verified flag itself stays as it is. |
| "multiple-regions" verification error | MX records on the `send` host point at different regions. Keep only the one Resend listed. |
| Cloudflare conflict at `send.<domain>` or a `_domainkey` name | Another record holds that name. Delete it if unused, or recreate the Resend domain with another return path. |
| `403` sending from `onboarding@resend.dev` | Only the owner's address works. Send from the verified domain. |
| `429 daily_quota_exceeded` / `monthly_quota_exceeded` | Plan quota hit. Wait for the reset or the human upgrades. |
| `429 rate_limit_exceeded` | 10 requests/second per team; retry after a moment. |
| Supabase auth emails not arriving | With `auth.smtp: resend`, check the `auth:smtp` step's changes and `auth-policy`'s `custom SMTP via Resend` evidence, that tracking is off, and the auth email rate limit (the step raises it to 30 per hour, or `auth.emailRateLimitPerHour`). Without that opt-in the project still uses Supabase's built-in mailer, which is rate-limited. |

## Unverified

- Exact names of the newer CNAME-style SPF records (seen as `send` / `rsend`); golive reads them from
  Resend's API rather than assuming.
- Supabase's email rate limit right after enabling custom SMTP (docs say 30/hour, Resend says 25).

# Stripe (payments): agent notes

Load this when the plan uses `payments=stripe`.

Status: a disposable test-mode run passed end to end — sandbox identity bound into approval (a
restricted operator key plus a standard app key), env wiring verified, webhook endpoint registered
and re-checked, the unsigned probe rejected with 400, and a real test-card payment delivered a
signature-verified event (HTTP 200). Live-mode payments, refunds, entitlements and subscriptions
remain open.

## 1. Giving golive Stripe keys

Stripe has **no API that creates or hands out account API keys**, and golive does **not** use the
Stripe CLI's login (`stripe login` credentials are short-lived and may lack live write access). So the
human provides a secret key once per mode in use through private credential entry:

- **How:** on macOS, run `credentials --prompt STRIPE_TEST_SECRET_KEY --json` for test mode,
  or `credentials --prompt STRIPE_LIVE_SECRET_KEY --json` only when live mode is needed. The human
  enters the value in the native dialog; golive saves it locally and returns metadata only. Their own
  editor is the fallback if unavailable, unsupported, or preferred; follow
  [How the human connects accounts](../SKILL.md#how-the-human-connects-accounts) for fallback,
  replacement and cancellation. Never put a value in chat or argv, or tell them to export it in an
  unrelated terminal (that shell is not the agent's). Use the exact variable name `doctor` identifies.
- **Which modes:** `payments.modes` in `golive.yaml`, default `{ preview: test, production: live }`, so
  by default both are needed:
  - `STRIPE_TEST_SECRET_KEY` (`sk_test_…` or `rk_test_…`)
  - `STRIPE_LIVE_SECRET_KEY` (`sk_live_…` or `rk_live_…`)
  - `STRIPE_SECRET_KEY` counts only for the mode its prefix matches, so one key never covers both.
- **No live key yet** (e.g. KYC not finished): set `payments.modes.production: test` in `golive.yaml`
  (the plan then warns that production takes no real charges), ship with test keys, and switch back
  to `live` later. While any needed key is missing, Stripe stays "not connected" and every Stripe
  step is left out of the plan.

### Operator key vs. app key

- The **operator key** (above) is what golive itself calls Stripe with. It may be a **restricted key**
  (`rk_…`) with **Webhook Endpoints: Write**, **Events: Read** and **Account: Read**.
- The **app key** is what golive writes into the app's `STRIPE_SECRET_KEY` on the host. It must be a
  standard `sk_<mode>_…` key. golive uses `STRIPE_APP_TEST_SECRET_KEY` / `STRIPE_APP_LIVE_SECRET_KEY`
  if set (an `rk_` or wrong-mode value there is rejected, with no fallback). Otherwise it uses the
  operator key, but **only if that is a standard `sk_` key**. A restricted operator key is never
  copied into the app. The app key is then a `stripe:secret-key:<mode>` handoff: the human adds it to
  the host themselves, or uses `credentials --prompt STRIPE_APP_TEST_SECRET_KEY --json` /
  `credentials --prompt STRIPE_APP_LIVE_SECRET_KEY --json` for the needed mode (same private-entry
  and editor-fallback rules).
- **Simplest path:** one standard `sk_` key per mode serves both golive and the app. A restricted
  operator key gives golive less power, but then the app key is a separate step.
- The operator key must successfully read the exact Stripe account. If Account: Read is denied
  or the account ID is missing, `doctor` blocks payments wiring even if webhook listing works.
  The approved account ID, mode and operator-key fingerprint bind each payment step. They are
  checked again before writes, and the step uses the captured credentials throughout.
- A separate app key must belong to the same approved Stripe account and mode. Account mismatch
  or unprovable identity stops before writing the key into hosting env. Changing accounts or
  rotating the planned credentials requires a new plan and approval.

## 2. What golive does vs. what stays with the human

golive automates (after plan approval; live-mode steps also need `--confirm-live`):
- **Keys per target** (`payments:keys:<target>`): writes the app key (§1) and the publishable key
  (from `payments.publishableKeys`, set with `init --stripe-publishable`) into the names the code
  reads, in each target's mode. A key rotation re-runs the step even though its preview text is the
  same (the key fingerprint is part of the step's intent).
- **The production webhook** (`payments:webhook:production`), for the production URL + webhook path
  with the events in `golive.yaml` (`init` defaults them to the events `detect` found in the handler;
  override with `--events a,b`). Endpoint choice, the same rule for `plan` and `apply`: one created by
  golive for this app, else any golive-tagged one (`metadata.managed_by=golive`), else any endpoint with
  the same URL (URL-normalised). An endpoint golive didn't create keeps its existing events (missing
  ones are added) and is never deleted. Drifted events or URL, or a disabled endpoint, are fixed in
  place.
- **In the same step**, writes the endpoint's signing secret (`whsec_…`) to the host's **Production**
  env only (usually `STRIPE_WEBHOOK_SECRET`). Stripe shows it only once, which is why it's one step.
  Preview gets no webhook and no signing secret (preview URLs change per deployment). golive records
  which endpoint the stored secret belongs to (its source includes the endpoint id). After a mode or
  URL round trip, the secret is replaced unless it provably belongs to the endpoint the URL resolves
  to now.
- **Before creating an endpoint** it asks the host whether it would accept the secret. If not (a var
  shared with other environments, an integration-owned var, production vars hidden from the login),
  the plan shows a blocking `stripe:webhook-env` handoff and creates nothing. If the write still fails
  after creating one, golive deletes the new endpoint and the error names it.
- **Production URL changed** (e.g. a custom domain added later): the endpoint golive created for the
  old URL is deleted after the new secret is stored (never one golive didn't create). The plan
  preview says so.
- **Guided host:** golive can't store the secret there, so a blocking `stripe:webhook-guided` handoff
  asks the human to create the endpoint in the dashboard and copy its `whsec_…` straight into the
  host's Production env (see `guided.md`).
- Verifies: `webhook-unsigned` (an unsigned POST gets 4xx; a non-HTML 401/403 only warns, since an auth
  wall looks the same as a handler rejecting the signature), `webhook-registered` (enabled endpoint,
  right URL, events covered), `stripe-live-ready` (the account can take live payments), and
  `env-parity` (key names present).

Stays with the human (and why):
- **Keys** (§1). Alternatives the `plan` handoff mentions: connect Vercel's Stripe integration (its
  vars are adopted, never overwritten), or the human pastes the key **directly into the host's
  dashboard**.
- **Publishable key.** Stripe's API can't hand it out either, so when the code reads one and
  `golive.yaml` has none for that mode, `plan` shows `stripe:publishable-key:<mode>`: ask the human
  for the `pk_test_…` / `pk_live_…` key. It is public (it ships in the browser bundle), so chat is
  fine for this one; never `sk_`, `rk_` or `whsec_`. Run `init --stripe-publishable <mode>=pk_<mode>_…` and `plan` again. Or the human adds it
  to the host dashboard.
- **Identity verification (KYC) for live payments** (`stripe:activate`). `stripe-live-ready` shows what
  Stripe still needs. Only the human can submit it; never try to fill it in.
- **Deleting old endpoints** golive didn't create, and cleanup at the 16-endpoints-per-mode limit.
- **Copying products to live.** "Copy to live mode" creates a new copy every time. Prefer prices with
  lookup keys in each mode.

## 3. Explain these in plain words

- **The signing secret is shown once.** If golive doesn't have it for an existing endpoint, the plan
  replaces the endpoint: create a new one with the same URL/events, write its secret, then delete the
  old one **only if golive created it**. An endpoint golive didn't create is left in place, and the
  change log says so; the human deletes it in the Webhooks tab in Workbench (until then Stripe
  also delivers to it, and those deliveries fail signature checks). The log says "old endpoint
  deleted" only when it was.
- **Test and live are separate worlds.** Same URL, different secrets. The secret from `stripe listen`
  on a laptop is different again. Mixing them gives "No signatures found matching the expected
  signature for payload".
- **One sandbox for everything.** Use a single sandbox (or the account's test mode) for keys,
  endpoints and event tests: golive cannot tell sandboxes apart, so a key from one sandbox and a
  signing secret from another silently disagree.
- **The handler must read the raw body.** Parsing JSON first breaks the signature. Next.js App Router:
  `await req.text()`. Express: `express.raw({type:'application/json'})` on the webhook route, mounted
  before `express.json()`.
- **Edge runtimes** (Vercel Edge, Cloudflare Workers, Deno, Supabase Edge Functions) must use
  `await stripe.webhooks.constructEventAsync(body, sig, secret, undefined,
  Stripe.createSubtleCryptoProvider())`. The non-async version throws there.
- **Supabase Edge Functions** reject Stripe by default (they expect a Supabase JWT). Set
  `verify_jwt = false` for that function; `detect` notes it. See `supabase.md`.
- **Vercel Deployment Protection** blocks Stripe on protected URLs. The webhook goes to the production
  domain or the project's public production alias.
- **Redirects count as failures.** Register the final URL (www vs. bare domain, trailing slash).
- **Middleware** (CSRF, auth) must skip the webhook route.
- A **static export** (e.g. Next.js `output: 'export'`) has no server, so it can't receive webhooks.

## 4. Troubleshooting

| Symptom | What to do |
|---|---|
| `doctor`: Stripe not connected, a key is missing | The human adds the per-mode key(s) `doctor` names to the credentials file (§1). `stripe login` doesn't help. No live key yet: `payments.modes.production: test`. |
| "`STRIPE_LIVE_SECRET_KEY` holds a test-mode key" (or similar) | Wrong key in that line; replace it with the right mode's key. |
| Stripe rejected the key (401) | Expired, revoked or mistyped. Copy a current key from the API keys page (dashboard.stripe.com/apikeys) into the credentials file. |
| Permission error (403) with a restricted key | Grant Webhook Endpoints: Write, Events: Read and Account: Read, or use the standard key. |
| `stripe:secret-key:<mode>` handoff with a restricted key | Expected: restricted keys are never given to the app. Set `STRIPE_APP_<MODE>_SECRET_KEY` (standard `sk_` key) or the human adds the app's key to the host. |
| "No signatures found matching the expected signature for payload" | Wrong secret (test vs. live, `stripe listen`, old endpoint), or the body was parsed before verifying. |
| `webhook-unsigned` gets 2xx | The handler doesn't verify signatures. Security fix in code, then re-run `verify`. |
| `webhook-unsigned` warns on a 401/403 | Either an auth wall in front of the route (Supabase `verify_jwt`, Deployment Protection) or a handler that returns 403 for bad signatures on purpose. Fix the wall, or accept the warning. |
| `webhook-unsigned` gets 404/405 | Wrong path. Fix the route, or `init --webhook-path <path>`. |
| `webhook-unsigned` gets 3xx | Register the canonical URL. |
| `webhook-registered` fails on events | `golive.yaml` events differ from the endpoint: `plan` + `apply` fixes it. If the handler needs more events, `init --events a,b` first. |
| "Use `await constructEventAsync(...)`" | Edge runtime; switch to the async form above. |
| `stripe-live-ready` fails (`charges_enabled` false) | KYC handoff. Show `requirements.currently_due` in plain words; the human completes it in the Dashboard. |
| Endpoint limit (16 per mode) | The human deletes unused endpoints in the Webhooks tab in Workbench (stale golive ones are tagged `managed_by=golive`), then re-run. |
| Apply says the webhook endpoints changed since approval | Someone changed endpoints meanwhile. Run `plan` again and get approval again. |
| `stripe:webhook-env` handoff (host would refuse the secret) | Fix the var at the host as its `action` says (e.g. split a multi-environment var per environment in the Vercel dashboard), then `plan` again. |

## Unverified

- Whether live webhook endpoints can be created before KYC is complete.
- The exact restricted-key toggle name for reading one's own account.
- Whether Stripe Projects can deliver the user's live key to a host.

# Supabase (database + auth): agent notes

Load this when the plan uses `db=supabase` or `auth=supabase`.

## 1. Logging in

**Preferred: one `supabase login` in the human's own terminal.** It needs a TTY, so use the Terminal
app or the IDE terminal, not the agent or Claude Code's `!` prefix. For a new account, the human
signs up and creates/selects a Free organization first; SDK imports do not prove a project exists.
Then golive checks the account and presents the exact project destination for approval.

On supported credential stores, golive reuses that browser login for the **complete flow**: creation,
API keys, pooled database URLs, Auth redirects, RLS queries and advisors. It captures the credential
internally as `Secret` and uses HTTPS; it never prints it or puts it on argv. A second manually
created Management API token is not required. Do not inspect or print the CLI token store yourself.

Supported credential stores (Supabase CLI v2.117.0 or later within v2):
- **macOS:** the official Keychain service/profile, with the documented private-file fallback when
  its items are absent. macOS may raise a **SecurityAgent dialog** asking whether the read-only
  `security` helper (golive's reader) may read the item "Supabase CLI" — the Supabase CLI itself is on
  the item's allow list, which is why its own commands never ask. golive only reads that item and
  never changes the Keychain. Tell the human which dialog is theirs to answer and that in it:
  **"Allow"** answers this read (the dialog returns on the next run) and **"Always Allow"** records the
  permission permanently for that item, so it stops asking. golive waits 15 s, then one longer
  attended window (120 s) while it says the dialog is coming; if it still goes unanswered, the
  reusable credential read fails closed with that same instruction, and the reads the CLI performs
  itself (project discovery, API keys, the RLS query) keep working through the CLI while anything that
  needs the Management API is handed over. A refused/locked read is never retried and never falls
  back to another account.
- **Linux/WSL:** the CLI's private token file with keyring disabled, or on WSL. On Linux use
  `SUPABASE_NO_KEYRING=1 supabase login --profile supabase` in the human's terminal and preserve
  `SUPABASE_NO_KEYRING=1` when running golive. This is still browser login, not manual PAT creation.
- **Windows/native Linux keyrings:** safe reuse is not implemented. Use the explicit-token fallback
  below. Unknown CLI major versions require review; update an older CLI before retrying.

Only the production **`supabase` profile** is supported. `SUPABASE_PROFILE` overrides the CLI's
persisted profile file; staging, local, Snap and custom API profiles are rejected. Use
`supabase login --profile supabase` to select the intended production account. Stores are read-only;
golive never migrates them or changes permissions. Wrong owners, unsafe permissions or redirected
paths fail closed. A native macOS read-only test on 2026-09-23 reused the existing login with the
explicit-token path disabled: profile/projects/organizations reads passed and the CLI/API project
inventories agreed. The later auth live run (2026-09-23) created one project and wrote its auth
policy through the same reused login, with no explicit token, no `SUPABASE_*` variable in the shell
and no Keychain prompt; the hosting E2E before it used an explicit token, and first-login UX is still
untested. Do not describe either run as a fresh login.

**Alternative: `SUPABASE_ACCESS_TOKEN` for CI or unsupported stores.** The human creates it at
https://supabase.com/dashboard/account/tokens with the permissions below. On macOS, run
`credentials --prompt SUPABASE_ACCESS_TOKEN --json` for private native entry. Their own editor is
the fallback if unavailable, unsupported, or preferred; follow
[How the human connects accounts](../SKILL.md#how-the-human-connects-accounts) for fallback,
replacement and cancellation. Never put the value in chat or command arguments; exporting it in an unrelated human
terminal does not reach the agent's shell. Never run `supabase login --token …`.

An explicit token takes precedence over CLI login for every call. If it is invalid, golive fails;
it never silently switches accounts. The human may replace it or remove that explicit setting to
use the CLI login. A rejected stored login is refreshed with browser login, without generating a PAT.

If using the **explicit-token alternative for an existing throwaway project**, choose only that project and a short expiry. Stage 1 permissions, using
the [current Supabase UI labels](https://supabase.com/docs/guides/platform/personal-access-tokens):

| Task | Permission / access |
|---|---|
| Project details + health | Project Settings: Read |
| Reveal API keys | API Keys + API Key Secrets: Read |
| Inspect auth (site URL, redirects, policy) | Auth Config: Read |
| Set site URL / redirects / policy | Auth Config + Project Settings: Read-write |
| Read Data API schemas | Data API Config: Read |
| RLS SQL check | Database: Read |
| Security advisors | Advisors: Read |
| DB URLs if requested | Connection Pooling: Read |
| Approved password recovery for an golive-created project only | Database Config: Read-write |

For **a new project**, the human signs up and creates/selects a Free organization first. If using the token alternative, the docs list Organizations
Read, Organization Settings Read, Projects (account-wide) Read and Organization Projects Read-write for the
account/org flow. If the user's scoped-token UI does not expose these, the account-management token was under
the experimental-token dropdown in Stage 1; that is an observed rollout detail, not a universal UI guarantee.
Alternatively the human creates the throwaway project first, then supplies a token scoped to that project.

`doctor` / `plan` report the reused CLI login and the API-confirmed account identity. A missing,
unsupported or unsafe store gives a blocking `login:supabase` handoff with a specific remedy. When
only the limited legacy CLI fallback is usable, it covers project discovery, keys and the RLS query
(those reads shell out to the CLI, which reads its own store without a prompt and never exposes the
credential); creation, the pooled database URL, auth settings and advisors use the Management API,
and stay blocked until the login can be reused or the human supplies the alternative. An unanswered
macOS Keychain dialog is exactly that case: the CLI-covered reads continue, the rest fails closed
with the dialog instruction, and the run warns once that the reusable credential could not be read.

A `/profile` 403 does not mean the token is invalid: project-scoped tokens can still access their selected project.
golive verifies an explicitly selected visible existing project (exact ref or unambiguous configured name). With no
selected project, it checks organization discovery/details for one eligible Free destination instead. That confirms
organization read access only; creation write permission remains unverified until the operation. An empty/denied
organization list blocks this path. API operations check permissions independently and plan/apply revalidates targets.

## 2. What golive does vs. what stays with the human

golive automates (after plan approval):
- **Picks the project** (`project:db`): the linked one (state → `projects.db` in `golive.yaml` →
  `supabase link` file), else a same-named one it may adopt (names compare case-insensitively), else
  a **Create** step. It adopts a
  same-named project automatically only if it is in this app's org (the account's only org, else its
  single free org) and not paused or failed. A same-named project in another org, a paused
  (`INACTIVE`) one, or several orgs with no single free one means no auto-adoption: create refuses (no
  duplicate is made) and names the ref, org or status. The human chooses with
  `init --project db=<ref>`, or restores a paused project in the dashboard. golive never restores one;
  selecting a paused project fails with restore instructions. A `COMING_UP` / `RESTORING` project is
  waited on until `ACTIVE_HEALTHY`.
- **Creating costs money:** free orgs allow 2 active projects; on paid orgs each extra project is about
  $10/month of compute. Confirm with the human, and offer the existing projects the Create step
  lists. The region comes from `supabase.region` in `golive.yaml` (else Supabase's default group).
- For a new project, golive generates the database password and sends it only inside the create
  request. That request is **never re-sent** (90s timeout, no retry). If the response is lost, golive
  lists projects again and adopts the one new project with that name in that org, keeping the
  password it sent. If none appears, it fails and asks you to check
  `https://supabase.com/dashboard/org/<org>` before re-running (a re-run adopts it by name once it
  appears). Then it waits until the project is healthy (usually 1–3 minutes, up to 15). On timeout
  it asks you to re-run later: golive picks the project up (and resets its password if needed, below).
- A project golive creates is recorded as `supabase.createdByGolive=<ref>` in `.golive/state.json`
  (not a secret). The generated password lives only in memory. If a later run has lost it and no DB
  URL from that project was ever written, and the app actually requests a database URL, `plan` warns and the env write step sets a **new generated
  password** for it (Supabase Management API, using the reused login or explicit token) instead of a `db:password` handoff.
  Never for an adopted project, without a reusable credential, or once a DB URL was written for any target.
  Apps needing only Supabase client URL/API keys do not collect database URLs or reset the database password.
- Writes the project URL and API keys to the host under **the names the code uses** (publishable key
  for the browser, secret key server-only).
- When it knows the password (projects it created) writes:
  - `DATABASE_URL` (and `POSTGRES_URL`, `POSTGRES_PRISMA_URL`, …): the shared Supavisor pooler in
    **transaction mode, port 6543** (uses the same login). Prisma repos get `?pgbouncer=true` (a
    `schema.prisma`, `prisma/schema.prisma` or `prisma/schema/` folder, a `prisma.config.*` or custom
    `prisma.schema` path, a Prisma dependency, or `POSTGRES_PRISMA_URL` referenced). Otherwise the
    log warns: postgres.js and Drizzle need `prepare: false`; node-postgres needs nothing.
  - `DIRECT_URL` (and `DATABASE_URL_UNPOOLED`, `POSTGRES_URL_NON_POOLING`, `DIRECT_DATABASE_URL`): the
    shared pooler in **session mode**, `postgres.<ref>@<region>.pooler.supabase.com:5432`. It is
    IPv4, so `prisma migrate deploy` works from Vercel. Without a reusable credential (or when Supabase lists no
    shared pooler) it falls back to `db.<ref>.supabase.co:5432` with a warning: that host is
    IPv6-only unless the project has the IPv4 add-on, so it won't work from most serverless hosts.
- Sets auth **Site URL** and the **redirect allowlist** to the production origin with a surgical API
  update (not `supabase config push`). Preview-deployment wildcards are added only with
  `auth.previewRedirects: true` in `golive.yaml` (flagged as a risk: it widens the production
  allowlist). Otherwise `plan` warns that sign-in on preview URLs won't work.
- Sets the auth **policy** from `auth` in `golive.yaml` — `signup`, `requireEmailConfirm`,
  `passwordMinLength` — in the separate `auth:settings` step (so a policy change doesn't re-run the
  redirect work). It writes only the values that differ, then re-reads them: the step's changes show
  `before → after`, the `auth:settings:applied` result confirms them, and anything the API does not
  report back appears as `not confirmed:` instead of a silent success. Only the settings this API is
  known to return are ever read or written; `smtp_pass` is write-only (the API answers a hash), so an
  SMTP write can never be confirmed from the read-back. The live run confirmed that the Management API
  does echo signup, email confirmation, the password minimum length, the SMTP-configured flag and the
  email rate limit back.
- Writes the **custom SMTP** in its own `auth:smtp` step when `auth.smtp: resend` is set: `smtp_host`
  (`smtp.resend.com`), `smtp_port` (465), `smtp_user` (`resend`), `smtp_admin_email` and
  `smtp_sender_name` from the sender `email.from` already uses, and the write-only `smtp_pass` from a
  sending key golive issued — the one the email journey issued in this run, otherwise one it issues for
  SMTP alone (`golive-…-smtp`, recorded as `<provider>.keyId@smtp` so teardown can revoke it); never a
  paste and never a chat prompt. Configuring the mailer is only half of it: Supabase keeps its **own
  auth-email rate limit** with custom SMTP in place (the live project's `rate_limit_email_sent: 2`
  refused a recovery request with HTTP 429 in the same run that wired the SMTP), and one run of the
  auth journeys needs four accepted sends, so the step writes `rate_limit_email_sent` too:
  **30 per hour**, or `auth.emailRateLimitPerHour` from `golive.yaml` when the human wants another
  value. The change is named in the plan and the step's changes
  (`auth email rate limit: 2 → 30 per hour`). Unlike an SMTP field, a rate limit the API keeps at
  another value does not fail the step — it is the provider's own setting — so it warns instead:
  `auth:smtp:applied:rate-limit` (medium) names the value that holds, and one the API never reports
  back is named as unconfirmed like any other field. `smtp_port` is the one field this API documents
  and validates as a string: golive sends `"465"`, because a number is the live 400
  `smtp_port: Invalid input: expected string, received number` (the port stays a number in the plan,
  the changes and everything golive reads back — the read accepts either type). The step re-reads the
  non-secret fields (`auth:smtp:applied`) and the `auth-policy` check reports
  `custom SMTP via Resend` instead of the built-in-mailer warning, and the journeys that send real
  mail run after it. The password is never compared, because the API never returns it: the read-back
  confirms the settings, and a real auth email arriving is the only full proof. Live-validated on
  2026-09-24 on a disposable project: the approved apply wrote the mailer and the rate limit in one
  request and read both back (`SMTP host: (not set) → smtp.resend.com`, `SMTP port: (not set) → 465`,
  `SMTP user: (not set) → resend`, `sender address: (not set) → auth@mail.trytofu.xyz`, `auth email
  rate limit: 2 → 30 per hour`), issuing one sending key for SMTP alone and recording it as
  `resend.keyId@smtp` (revoked in that run's teardown), and `auth-policy` then read `custom SMTP via
  Resend` with `rate limit: 30 auth emails/hour`. What that evidence is not: the password (write-only —
  reported `not confirmed`) and delivery, which needs an inbox golive cannot read.
- **Runs the signup journey** when the human opted in with `auth.e2e: true` (see below): the
  `auth:test-user` step seeds one test account through the project's own `/auth/v1` signup endpoint,
  `auth:confirm-email` hands the inbox click over, and the `auth-signup`/`auth-session` checks prove
  the rest.
- **Rotates that account's password through recovery** when the human also opted in with
  `auth.recovery: true` (see below): the `auth:recovery` step asks for a real recovery email, mints its
  own recovery link through the Auth admin API, exchanges the token for a session and sets the new
  password with that session. `auth-recovery-email` hands the inbox click over and `auth-recovery`
  proves the outcome.
- **Seeds a second account and reads the app's own routes** when the human opted in with
  `auth.isolation: true` (see below): the `auth:isolation` step signs up a second account
  (`testEmail` plus `+gl-isolation`) and confirms it through the Auth admin API, and `auth-isolation`
  signs in as both accounts and checks that neither can read the other's identity or rows through
  `auth.identityPath` / `auth.isolationPath`.
- Verifies: `rls-probe` (tables not readable with the public key, plus security advisors, read-only),
  `auth-redirects` (production URLs, no `localhost`), `auth-policy` (signup/confirmation/password
  policy and the mailer, with the effective values as evidence), `auth-signup`/`auth-session` (the
  journey above, when opted in), `auth-recovery` (the recovery journey above, when opted in),
  `auth-isolation` (the two-account journey above, when opted in), `env-parity` (names on the host).

Stays with the human (and why):
- **The database password of an existing project.** Supabase only reveals it at creation, so a
  `db:password` handoff appears: the human copies the connection string from the Supabase dashboard
  straight into the host's dashboard (never into chat), or resets the password in the Supabase
  dashboard (breaks anything else using the old one). Or the app skips a DB URL if it only uses the
  Supabase client.
- **Fixing RLS findings.** You (the agent) write the migration/policy change; the human approves it.
  golive never write-probes your application's data tables. With `auth.e2e: true` it does create auth
  **test users** (see below) — that opt-in is exactly what covers them; with `auth.recovery: true` it
  also sets a new password on that same recorded test account through the recovery path; with
  `auth.isolation: true` it creates a **second** test account, confirms it through the admin API, and
  the check stores one small marker row per test account through the app's own
  `auth.isolationPath` route.
- **The inbox click** for a confirmation or recovery email (see the journeys below): golive never
  reads an inbox, and with `auth.smtp: resend` that message comes from the app's own email provider
  instead of the built-in mailer.
- Restoring a paused project, plan upgrades, billing, creating OAuth apps (e.g. Google sign-in).

### The signup journey (`auth.e2e`)

Opt-in, three keys in `golive.yaml`:

```yaml
auth:
  e2e: true                      # accept that this journey writes real auth users
  testEmail: you+go-live@example.com   # the human's own inbox (plus-addressing is fine)
  protectedPath: /dashboard      # an app route that must require a session
```

What it proves, with the evidence to match:

- **Signup sends mail.** `auth-signup` signs up a fresh probe address (`testEmail` plus a random
  `+gl-…` tag, so it always reaches the same inbox) and requires a confirmation email.
- **Confirmation is enforced.** The check immediately tries a password login for that same
  unconfirmed address and requires `email_not_confirmed`. An account that can sign in before its
  address is confirmed is a failure, not a warning.
- **The human's click is visible.** After they click, the seeded account reads back with
  `email_confirmed_at` set through the admin API.
- **A session works.** `auth-session` signs in as the seeded account, requires
  `GET /auth/v1/user` to return that same user, requires an anonymous `GET /auth/v1/user` to be 401,
  and — only with `protectedPath` — requires an anonymous GET of the confirmed production URL plus
  that path to redirect to sign-in or answer 401/403. A 200 there is a failure; a 404 only warns
  (the path is probably wrong). A 401/403 is corroborated with one more anonymous GET of the
  production root: when that public route answers normally the whole origin is not walled, so the
  refusal is scoped to this path, and when the root is walled or unreadable too the leg is
  **inconclusive** (warn, naming the wall, not a pass) — a WAF, edge rule, visitor access or a
  maintenance page answers 401/403 without your app involved. Live-validated
  on 2026-09-24 against a deployed Vercel fixture: the declared route answered `401` anonymously
  (the pre-corroboration wording, `protected without a session`); the root comparison itself has
  mocked coverage only.
- **The app can read its own tables.** The checks probe the exposed tables AS the signed-in user
  (anonymity stays `rls-probe`'s job). Every table refusing the `authenticated` role warns: new
  projects no longer `GRANT` new tables automatically, so the app may be missing a migration.
  The probe names the tables it read, schema-qualified and grouped by verdict (`reachable:`,
  `denied:`, `undecided:`), up to four per line with `+N more` when a schema has more, so the
  count can be audited back to a table. Live-validated on 2026-09-24: the probe read the project's
  one exposed RLS-protected table (`1 reachable, 0 denied, 0 undecided`), which also live-exercises
  the `supabaseAuthedProbe` bearer fix; that run's line was a count without the table's name.

What stays human, and why the evidence says so:

- **Email delivery and the click.** golive cannot read an inbox. It never claims delivery: it reports
  the provider's own confirmation state. `auth:confirm-email` is closed only by `auth-signup` passing,
  and until then the report says the address is not confirmed yet.
- **The generated password.** `auth:test-user` generates one per run (32 random characters, carrying one
  character of every class a project's password policy can require, so a policy that demands a digit or a
  symbol never refuses it) and keeps it in that run's memory only — never in state, a report or evidence. A
  later run re-runs the step with a new password for the same account (recorded as `supabase.testUserId` +
  the address in `.golive/state.json`). A `verify`-only run holds no password, so `auth-session` skips with
  `blocked by: no password for the test account in this run`; `auth-signup` still passes on the
  provider reads alone (probe signup, its refused login, the account's `email_confirmed_at`, with an
  evidence line naming where the confirmed login itself is exercised), so `handoff` reports the
  confirmation handoff done without it. Run `plan` + `apply` after the human clicks, then re-run
  `verify`: the step rotates the password, and both checks run against the live account.

Caveats to pass on before enabling it:

- **It writes real users.** One test account per project, plus one throwaway probe account on every
  run of these two checks (every `verify` with `auth.e2e: true`, and the `apply` that carries the
  step). Both live in the project's user list until someone deletes them. `auth:test-user` carries
  `--confirm-live` for exactly this, and nothing here is a purchase. With `auth.isolation: true` there
  is a second seeded account (`+gl-isolation`) that `auth:isolation` creates and confirms the same way,
  and the `auth-isolation` check stores one small marker row per test account through the app's own
  `auth.isolationPath` route on every run — those two rows stay in the project's data too.
- **The auth email limit is the project's own, and the built-in mailer is rate-limited on top of it**
  (a handful of auth emails per hour; the live project's `rate_limit_email_sent: 2` behaved closer to
  one accepted send per window). Supabase then answers HTTP 429: `auth-signup` warns, `auth:test-user`
  fails with instructions, and one run of the journeys can exceed what that limit fits. The fix is the
  `auth:smtp` step (`auth.smtp: resend`), which now raises the limit to 30 per hour (or
  `auth.emailRateLimitPerHour`) as well as wiring the mailer — a limit that already spent its window
  still has to reset, so a run that hit 429 should wait before re-running. Check the spam folder — a
  project without DMARC often lands there.
- **A captcha on signup** (`hcaptcha`/`turnstile`) makes a scripted journey impossible: the step
  fails and `auth-signup` skips, never fails. Turn the auth captcha off for this project, or accept
  that the journey stays manual.
- **One account per address.** If the address already has a Supabase account, signup sends nothing
  and answers with an obfuscated user: the step adopts that account (rotating its password) and says
  so. Delete the test account in the dashboard to start over, or use another `auth.testEmail`.
- **Recovery spends auth emails too.** With `auth.recovery: true`, `auth:recovery` asks for one
  recovery email and `auth-recovery` asks for up to two more (the recorded address, then a fresh
  address with no account) every time it runs, against the same throttled mailer. A 429 warns instead
  of failing for exactly that reason.

### The password-recovery journey (`auth.recovery`)

A second opt-in, on top of the signup journey's confirmed account — the account the recovery rotation
touches is that same recorded test account, and no other:

```yaml
auth:
  recovery: true                # rotate the recorded test account's password through recovery
```

What the `auth:recovery` step (`--confirm-live`) does, in the app's own order:

- **Asks for the reset.** `POST /auth/v1/recover` for the recorded address, so a real recovery email
  lands in that inbox. An address with no account is answered the same way — Supabase refuses to
  reveal which addresses exist.
- **Mints its own link.** `POST /auth/v1/admin/generate_link` with `type: recovery` answers the token
  the email would have carried; it stays a `Secret` in that run's memory. That is what makes the
  journey provable without reading an inbox.
- **Exchanges it and sets the password.** `POST /auth/v1/verify` with `type: recovery` and the token
  returns a session, and `PUT /auth/v1/user` with that session sets the new password — exactly the
  calls a recovery page makes. Each of those requests carries `Bearer <token>`; a scheme-less header
  was a live-found defect (#25), and the adapter tests now assert the scheme on every one of them.
- **Keeps the rest of the run working.** The new password is stored under the key `auth:test-user`
  uses, so `auth-signup`/`auth-session` prove the same run with it; the replaced password and the spent
  token stay in that run's memory for the check to use.

What `auth-recovery` proves, and what stays human:

- **The request is accepted.** A 429 from the project's auth email limit warns, never fails: the mail
  throttle decides what a run can prove (roughly one accepted send per window on the built-in mailer).
- **No account enumeration.** The same request for an address with no account (a fresh
  `+gl-recovery-…` plus-tag) must get the same answer. A different status or acceptance is a finding:
  it answers "does this address have an account here?" for anyone who asks.
- **The token is one-time.** Replaying the token this run spent must be refused.
- **The password actually changed.** The new password signs in; the one it replaced is refused.
- **The window is named, not assumed.** When the project reports `mailer_otp_exp` (golive's
  `otpExpirySeconds`), the evidence says how long such a link stays usable; a project that does not
  report it is named as not reporting it.
- **The click stays human.** `auth:recovery-email` is non-blocking and closed by `auth-recovery`
  passing; golive never reads the inbox. A captcha on the project blocks the scripted request, so the
  check skips instead of claiming a pass.

Live-validated on 2026-09-24 on a disposable project, in one apply that also carried the SMTP write
above: the request was accepted for sending (HTTP 200), the admin-minted link was exchanged for a
session, the new password was set with it, and `auth-recovery` passed every leg — an address with no
account answered identically (HTTP 200 both, no enumeration), the spent token refused on replay (403
`otp_expired`), the new password signing in, the replaced one refused (`invalid_credentials`), and the
provider's 3600 s OTP window (`otpExpirySeconds`) named. The row recording it is in
`docs/VALIDATION.md`. What that run cannot show: the click in the inbox (golive never reads one), and
whether the message was ever delivered — its HTTP 200s are the provider accepting the send, and the
run's sending domain was the subject of [#52](https://github.com/mikehasa/golive-skill/issues/52).
A separate `verify` still skips the check, by design: the token and both passwords exist only in the
rotating run's memory.

### The account-isolation journey (`auth.isolation`)

The third opt-in, and the only one that answers a question about YOUR app rather than about Supabase:
can the account that just signed in read anything that belongs to another one? Supabase holds the two
accounts; your routes hold the answer.

```yaml
auth:
  isolation: true               # seed a second real account and read the app's own routes
  identityPath: /api/me         # GET: the signed-in caller's OWN id as JSON; 401/403 or a redirect without a session
  isolationPath: /api/notes     # GET: the caller's OWN rows; POST {"marker": "…"}: store one row for the caller; both refuse anonymous callers
```

`auth.e2e: true` and `auth.testEmail` are prerequisites: the first account is the one `auth:test-user`
seeds, and its password for this run comes from that same step. A plan warns and waits when the first
account is missing or not yet confirmed.

What the `auth:isolation` step (`--confirm-live`) does:

- **Seeds or rotates the second account** through the project's own `/auth/v1/signup` at
  `you+gl-isolation@example.com` (derived from `auth.testEmail`, so a later run finds the same
  account). Only the user id and the address are recorded (`supabase.isolationUserId` /
  `supabase.isolationUserEmail`); the generated password stays in that run's memory under the same
  per-user key `auth:test-user` uses — so `auth-signup`/`auth-session` keep working on the first
  account and `auth-isolation` can sign in as both.
- **Confirms it through the admin API.** `PUT /auth/v1/admin/users/{id}` with
  `{"email_confirm": true}`, re-read afterwards. This is deliberately not an inbox leg: the journey is
  about the app's data, and a second click would spend the project's throttled mail budget. The
  confirmation email the signup sends is a side effect, not a step.
- **Never touches an account golive did not seed.** It re-reads the recorded account first, refuses
  when it is gone, and its risk is `{ writes, live, replayable }` — the same discipline as its
  siblings, so a failed attempt from an older release may resume.

What `auth-isolation` proves, and what stays with the app:

- **Both routes refuse anonymous callers.** A 200 on either declared route is a **critical** finding.
- **Each account sees its own identity.** With each session, `identityPath` must answer with that
  account's own user id and never the other's (`user.id` from `/auth/v1/user` is what golive compares).
- **Each account reads only its own rows.** The check writes one unique marker row per account through
  `isolationPath` (**through the app, with that account's session**) and reads both routes back: a
  response carrying the other account's marker is a cross-account read and fails **critical**.
- **Sessions are real but not evidence of delivery.** Both accounts sign in with the passwords that
  run generated; nothing here is a claim about the inbox.
- **Skips, never passes:** the opt-in is off, either route is not declared (`auth:isolation-routes`
  carries the app-code task when they are missing), a route answers 404 or refuses the session token
  golive holds (the skip names the exact app-code task), the host cannot confirm the production URL,
  or the provider or the app rate-limits a request. A route that answers without the caller's own id
  or marker only **warns**: the absence of the other account's data is then not attributable.

The app-side contract, in one place: `identityPath` answers `GET` with the caller's own identity as
JSON and refuses (401/403 or a redirect) without a session; `isolationPath` answers `GET` with only
the caller's own rows and stores one row for the caller for a `POST` body `{"marker": "…"}`, refusing
both without a session. golive sends the account's session as an `Authorization: Bearer <token>`
header — the same token the app already gets from `supabase.auth.getSession()`. RLS with
`auth.uid() = user_id` is the usual way to satisfy the rows half; the identity half is a route the app
already has to have (or a two-line handler).

This is **implemented and mock-covered, not live-validated yet** on a real Supabase project: the live
run that exercises it (and the `docs/VALIDATION.md` row recording it) comes separately. Never present
account isolation as proven on a human's project until a live report says `pass` for `auth-isolation`.

## 3. Explain these in plain words

- **New API keys.** `sb_publishable_…` is meant for the browser and is safe *only* if row-level
  security (RLS) is on. `sb_secret_…` bypasses RLS and must stay on the server. The old `anon` /
  `service_role` keys don't exist on projects created after 2025-11-01 and are being removed in late
  2026. If the code reads `SUPABASE_ANON_KEY`, golive fills it with the publishable key; suggest a
  rename.
- **RLS in one sentence:** "the publishable key is public, so the database itself must decide who can
  read each row." A table readable with the public key is a real leak unless it's meant to be public.
- **Default grants changed.** New projects (since 2026-05-30) and all projects from 2026-10-30 no
  longer let the public roles reach new tables automatically. After a migration the app may get
  "permission denied" (`42501`) until the migration adds a `GRANT` plus RLS policies.
- **Edge Functions and `verify_jwt`.** By default functions demand a Supabase login token (JWT). Stripe
  webhooks don't send one, so they get 401. Set `verify_jwt = false` for that function in
  `supabase/config.toml` (`[functions.<name>]`) and verify the Stripe signature in code. `detect`
  notes this. Env names used only under `supabase/functions/` are Edge Function secrets, not host env
  vars; golive doesn't write them.
- **Don't push `supabase/config.toml` to production blindly.** It usually has
  `site_url = "http://127.0.0.1:3000"` and localhost redirects; pushing that breaks sign-in.
- **Transaction pooler (port 6543)** has no prepared statements: Prisma needs `?pgbouncer=true` (golive
  adds it when it detects Prisma), postgres.js / Drizzle need `prepare: false` in code.
- **Free projects pause** after about a week without activity. Probes fail until the human restores it.
- **Vercel Marketplace integration:** if installed, Supabase vars are already synced into Vercel.
  golive adopts them rather than writing duplicates.

## 4. Troubleshooting

| Symptom | What to do |
|---|---|
| "Cannot use automatic login flow inside non-TTY environments" | The human runs `supabase login` in a real terminal window (Terminal app / IDE terminal), not with `!`. Not `--token`: use the credentials file. |
| CLI credential cannot be reused | Follow the specific version/profile/store remedy in `doctor`; check §1 platform support. Do not print or copy the vendor store. A manual PAT is the alternative only for unsupported setups. |
| Keychain denied, locked or timed out | Nothing was clicked in time: re-run and answer the dialog macOS raises for the read-only `security` helper — **"Allow"** for this read, **"Always Allow"** to record it permanently for the item so it stops asking. golive never changes the Keychain and never falls back to another credential; a refusal or a locked Keychain is not retried. If the dialog cannot appear (CI, no desktop session), use the explicit-token alternative. Meanwhile the CLI-covered reads (project discovery, keys, the RLS query) still run through the CLI. |
| Credential invalid / expired (401) | If `via` is CLI login, refresh it with `supabase login --profile supabase`. If explicitly supplied, replace or remove that setting privately. No automatic account fallback. |
| `/profile` 403 but `/projects` succeeds | Project access can be valid. Explicitly select that existing project; creating needs organization/account management access. |
| 403 reading API keys | Check selected project, API Keys Read and API Key Secrets Read. A provider bug has also been reported; do not assume all scoped tokens fail or automatically broaden access. |
| Project paused (`INACTIVE`) | The human restores it in the dashboard (golive never does), waits until active, re-runs. |
| `INIT_FAILED` / `RESTORE_FAILED` | The human checks the project in the dashboard, or picks another with `init --project db=<ref>`. |
| Create refuses: same name in another org / several orgs | The human picks: `init --project db=<ref>` for an existing project, or creates it in the right org. |
| "no new project … is listed yet" after a create | Check the org's dashboard page; re-run apply once it appears (it's adopted by name). |
| Free-plan project limit on create | Human pauses/deletes an unused project or upgrades. Or adopt an existing project. |
| App gets `42501` / "permission denied" | Missing `GRANT` for the table (see default grants). Add grant + RLS policy in a migration. |
| `/rest/v1/` returns 403 "Access to schema is forbidden" | Expected since 2026: listing tables with the public key is blocked. `verify` uses the Management API / CLI instead. |
| Prepared-statement errors in production | Transaction pooler: Prisma `?pgbouncer=true`, postgres.js / Drizzle `prepare: false`. |
| Can't reach `db.<ref>.supabase.co` from the host | IPv6-only direct connection (fallback without a reusable credential). Repair the CLI login/store or use the explicit-token alternative and re-run so `DIRECT_URL` uses the session pooler; use `DATABASE_URL` at runtime. |
| Create timed out waiting for the project | Re-run `plan` + `apply` later; golive adopts the project it created and resets the password if it was lost. |
| Stripe webhook to an Edge Function returns 401 | `verify_jwt` is still on for that function. |
| Sign-in redirects to localhost or "redirect not allowed" | Auth Site URL / allowlist not updated. Re-run `plan` + `apply`, then `verify --only auth-redirects`. |
| Sign-in fails on preview URLs | Expected unless `auth.previewRedirects: true` (a risk) or a separate preview auth project. |
| `auth-policy` says signup is closed / confirmation off / password too short | Write the intended policy under `auth` in `golive.yaml` (`signup`, `requireEmailConfirm`, `passwordMinLength`), then `plan` + `apply` (the `auth:settings` step) and re-run verify. |
| `auth:settings` step fails with "is X after the write, not Y" | Supabase accepted the PATCH but reports another value: check Auth Config write permission for this token and the setting in the dashboard, then re-run `apply`. |
| `auth:settings` changes say `not confirmed: …` | Supabase does not return that setting through the API, so golive cannot confirm it. Confirm it in the dashboard; the rest of the write is unaffected. |
| `auth-policy` warns about the built-in mailer | Supabase's default SMTP is rate-limited; set `auth.smtp: resend` in `golive.yaml` and run `plan` + `apply` (the `auth:smtp` step writes the custom SMTP from a sending key golive issues, and raises the auth email rate limit), configure it by hand, or accept the built-in mailer with `auth.smtp: provider`. Turn off link tracking at the email provider. |
| `auth-policy` warns the rate limit is below a run's sends | The project's own auth email limit (`rate_limit_email_sent`) is under the four accepted sends one run of the journeys needs. Set `auth.emailRateLimitPerHour` (30 is Supabase's suggested starting point) or raise it in the dashboard, then `plan` + `apply` (the `auth:smtp` step writes it when `auth.smtp: resend`) and re-run verify. |
| `auth-policy` says `custom SMTP via Resend` but mail still fails | The read-back only proves the settings: `smtp_pass` is write-only, so a wrong or revoked key looks the same. Confirm the sender domain is verified (`email-verified`), the key exists at Resend, then re-run `plan` + `apply` (a fresh key) and send a real auth email. |
| Magic-link emails broken or slow | Supabase's default SMTP is rate-limited; the `auth:smtp` step replaces it with the app's own email provider (§2). Turn off link tracking at the email provider. |
| `auth.e2e` journey | Start with `auth.e2e: true`, `auth.testEmail` and `auth.protectedPath` in `golive.yaml`, then `plan` + `apply --confirm-live` (the `auth:test-user` step creates a real account). Click the link in that inbox, then `plan` + `apply` again and re-run `verify`. |
| `auth-signup` skips with `blocked by: auth:test-user` | No test account is seeded yet: run `plan` + `apply` with `auth.e2e: true` first. |
| `auth-session` reports `blocked by: no password for the test account in this run` | The generated password exists only in the run that seeded or rotated it, so a `verify`-only run cannot sign in. `auth-signup` still passes on the provider reads (`email_confirmed_at`) and closes the handoff; `auth-session` needs the password. Run `plan` + `apply` again (the step re-runs with a new password), then re-run `verify`. |
| `auth-signup` says the test account is not confirmed yet | The human has not clicked that link. golive cannot read an inbox; the `auth:confirm-email` handoff stays open until `auth-signup` passes. Check spam (the built-in mailer is rate-limited and new domains often land there). |
| `auth-signup` warns "rate-limited (HTTP 429)" | Supabase's built-in mailer limit (or a per-project email rate limit) refused the send. Wait for it to reset, then let the `auth:smtp` step configure custom SMTP and raise `rate_limit_email_sent` (`auth.emailRateLimitPerHour` overrides the 30 per hour it writes), or raise it in the dashboard, and re-run verify. |
| `auth:test-user` fails with "wants a captcha" | Auth captcha (hcaptcha/turnstile) is on for the project: turn it off for a test journey, or keep the journey manual. A scripted signup cannot pass a captcha. |
| `auth-signup` fails "accepted without sending a confirmation email" | `mailer_autoconfirm` is on (users are confirmed automatically): set `auth.requireEmailConfirm: true`, `plan` + `apply`, and re-run. If the address already had an account, that is why nothing was sent — see the next row. |
| `auth:test-user` says the address already has an account | Supabase answers a duplicate signup without sending mail. golive adopts that account and rotates its password; delete it in the dashboard (Authentication → Users) or set another `auth.testEmail` to start clean. |
| `auth-session` fails on the declared protected path (HTTP 200) | The route is served without a session. Make it redirect to sign-in or answer 401/403; if it renders a sign-in page with 200, choose a path that redirects in `auth.protectedPath`. A 404 there only warns: the path is probably wrong or not deployed. |
| `auth-session` warns the protected-path answer is inconclusive | The production root answered 401/403 (or something that is not a normal page) to the same anonymous request, so an edge rule, WAF, visitor access or maintenance page is refusing the whole origin: golive cannot tell that wall from your app's own refusal, and the leg is not a pass. Make the root publicly readable, keep the declared path refused, and re-run verify. |
| `auth-session` warns the signed-in user is denied by every table | The `authenticated` role has no `GRANT` (new projects stopped granting new tables automatically); the `denied:` evidence line names the tables. Add the grant plus RLS policies in a migration, then re-run verify. |
| `auth.recovery` check | Start with `auth.e2e: true`, `auth.testEmail` and `auth.recovery: true` in `golive.yaml`, seed and confirm the test account, then `plan` + `apply --confirm-live` (the `auth:recovery` step sends a real recovery email and rotates that account's password) and re-run `verify`. |
| `plan` warns `auth.recovery is on … no test account is recorded yet` | The recovery rotation only touches the account `auth:test-user` seeds. Apply the plan that seeds it (`auth.e2e: true`, `auth.testEmail`), click the confirmation link, then run `plan` again. |
| `plan` warns the test account `is not confirmed yet` (with `auth.recovery`) | A recovery of an unconfirmed address sends a confirmation, not a recovery link, so the rotation waits. Click the confirmation link in that inbox, then run `plan` again. |
| `auth-recovery` skips with `this run holds none of what the recovery check needs` | The new password and the spent token exist only in the run that carries the `auth:recovery` step. Run `plan` + `apply --confirm-live`, then re-run verify: a plain `verify` cannot prove a rotation it did not perform. |
| `auth-recovery` skips with `blocked by: auth:test-user` | No test account is recorded yet: run `plan` + `apply` with `auth.e2e: true` first, then the recovery journey. |
| `auth-recovery` fails: an address with no account was answered differently | Something in front of `/auth/v1/recover` (a proxy, WAF, edge function or cached response) is leaking whether an address has an account. Answer an unknown address exactly like a known one. |
| `auth-recovery` fails: the spent token resolved again | The verification endpoint accepted a one-time token twice. Check for anything answering `/auth/v1/verify` ahead of the project, then re-run verify. |
| `auth-recovery` fails: the password set through recovery cannot sign in | The project's password policy may reject the generated password, or the account changed during the run. Check the user in the dashboard, then run `plan` + `apply` again (a fresh rotation) and re-run verify. |
| `auth:recovery` or `auth-recovery` warns/errors with HTTP 429 | The project's auth email limit refused the send. Wait for the window to reset, then configure custom SMTP (§2) — the `auth:smtp` step also raises `rate_limit_email_sent` (30 per hour, or `auth.emailRateLimitPerHour`) — and re-run. |
| `auth.isolation` journey | Start with `auth.e2e: true`, `auth.testEmail`, `auth.isolation: true`, `auth.identityPath` and `auth.isolationPath` in `golive.yaml`, have the app expose both routes (the `auth:isolation-routes` handoff holds the contract), then `plan` + `apply --confirm-live` (the `auth:isolation` step creates and confirms the second account) and re-run `verify`. |
| `plan` warns `the FIRST account comes from auth.e2e …` | `auth.isolation` needs the first test account too: set `auth.e2e: true` and `auth.testEmail`, then run `plan` again. |
| `plan` warns the test account `is not confirmed yet` (with `auth.isolation`) | The isolation check signs in as both accounts, so the first one has to be confirmed: click its confirmation link, then run `plan` again. |
| `auth-isolation` skips with `no app route is declared` | `auth.identityPath` / `auth.isolationPath` are not set. Get the app's code changed (the `auth:isolation-routes` handoff), name both routes in `golive.yaml`, then re-run `verify`. |
| `auth-isolation` skips with `no password for … in this run` | Both passwords exist only in the run that seeds or rotates them. Run `plan` + `apply --confirm-live`, then re-run `verify`. |
| `auth-isolation` skips with `HTTP 404: the app does not implement the declared … route` | The route is not deployed (or the path is wrong). Deploy it as the skip's app-code task describes, then re-run `verify`. |
| `auth-isolation` skips with `the route refused the session token golive holds` | The app is not reading the caller's session from `Authorization: Bearer <token>` (a cookie-only route, or a proxy in front). Fix the route or accept that golive cannot exercise isolation there. |
| `auth-isolation` fails `the declared … route is served without a session` | That route answers anonymous callers: make it 401/403 or redirect to sign-in when there is no session. |
| `auth-isolation` fails `carried the OTHER account's id` / `carried …'s row` | A cross-account read: the route answered with another account's data. Scope it to the caller (RLS `auth.uid() = user_id`, or the same filter in the route) and check anything that widens it (shared cache, service-role client, join), then re-run verify. |
| `auth-isolation` warns `was not in its own rows` | The route said 200 but did not return the row golive just wrote for that caller, so the read-back proves nothing either way. Return the caller's own rows from `auth.isolationPath` and re-run verify. |

## Unverified

- Whether publishable keys are blocked from `/rest/v1/` exactly like anon keys (assumed yes).
- The exact enforcement date for removing legacy keys ("late 2026", not final).
- Custom SMTP writes: **live-validated on 2026-09-24** — the accepted write and its read-back are
  observed (`smtp.resend.com`, port 465, user `resend`, sender `auth@mail.trytofu.xyz`) together with
  the auth email rate limit raised in the same request (`auth email rate limit: 2 → 30 per hour`,
  `rate_limit_email_sent`), after an earlier run's 400 on the port (`smtp_port: Invalid input: expected
  string, received number`) was fixed by sending the string. What remains unverified: `smtp_pass` is
  write-only (the API answers
  a hash), so the read-back
  confirms only host/port/user/sender and the limit — never that the key in effect is the recorded one,
  or that mail leaves the project; the rate limit is still the one setting whose refusal golive only
  warns about (the provider is free to keep its own value); and the auth email throttle's exact
  behaviour is also unconfirmed — this run's project accepted every send it made at 30/hour, while an
  earlier project's `rate_limit_email_sent: 2` accepted one send and refused the next 25 seconds later
  rather than allowing a clean two per window.
- GoTrue answer shapes still modelled from its documented behaviour: an obfuscated duplicate signup
  and a captcha refusal. The disposable live run (2026-09-23) exercised an accepted signup, the
  confirmation email request, the `email_not_confirmed` login refusal and the 429 rate-limit refusal.
- What the 2026-09-24 app-side evidence shows, and what has changed since: that run's signed-in probe
  read the project's one table as a count, and any 401/403 on the declared `auth.protectedPath` read
  as protection — a WAF, edge rule or maintenance page would have read the same. Both were evidence
  limits, not wrong results; the change tracked as #30 fixed the text (the probe names the tables per
  verdict, and a refused path is corroborated against the public root, so an origin-wide wall makes
  the leg inconclusive). Neither fix has been live-exercised yet: they are mock-covered. Inbox
  delivery and the human's click stay human-confirmed by design, and the confirmations in both runs
  were applied through the Auth Admin API (`PUT /auth/v1/admin/users/<id>` with `email_confirm:
  true`) rather than by clicking the seeded account's own email.

# Fix a setup failure and return to the deployment

Use this reference when a command fails during the skill's normal flow. Preserve the user's app,
provider choices, exact project scope, current plan and completed step records. A troubleshooting
detour ends with a passing check or a scoped external observation establishing the repair, plus a
clear continuation point. For guided providers, record external evidence separately; CLI checks
that lack provider coverage remain skipped.

## Installed, but command not found

First distinguish a missing installation from a shell lookup problem. On macOS/Linux, narrow
diagnostics include `command -v node`, `command -v npm`, `command -v <vendor-cli>` and
`npm prefix -g`. For an npm-installed CLI, check whether its declared executable exists under that
prefix's `bin` directory and run that exact executable with `--version`. Use the actual package's
binary name; package names and commands do not always match. On Windows, use the shell's command
lookup and npm's platform-specific executable location instead of assuming a `bin` subdirectory.

The human's separate Terminal and the agent may use different Node installations or PATH values.
Verify both contexts when necessary. An export in the human's terminal does not alter the already
running agent. A new terminal or `hash -r` can refresh shell lookup, but neither adds a missing
directory to PATH.

If the binary exists and works, correct the confirmed PATH/executable lookup with the smallest
appropriate change. Explain any persistent shell configuration edit; preserve existing entries
and executable links. Use a temporary PATH adjustment for a diagnostic when sufficient. Do not
hard-code a previous user's home directory, overwrite another CLI, switch Node installations,
repeatedly reinstall, or introduce `sudo` merely because command lookup failed. If the binary is
absent, follow the selected provider's supported installation method, then recheck discovery.

Only request non-secret diagnostic output from the human if the agent cannot inspect the relevant
terminal context. Never request a whole environment dump, npm config, shell startup file, auth
file or command history: those can contain credentials.

## Login or provider operation failed

Once the executable works, run the skill's `doctor` for the selected stack. If login is genuinely
missing/expired, have the human complete the provider's browser login in their separate terminal,
then rerun the account check. A login failure does not imply they need a second manual API token;
follow the adapter's supported path and describe any actual limitation.

A successful login followed by a failed create/deploy may indicate input shape, permissions,
Free quota, rate limits or a provider/CLI change. Do not prescribe reinstalling or generating a
new token without evidence. Use bundled provider references first; consult current official docs
for a concrete unresolved mismatch. Keep raw provider errors out of chat when they may carry
credentials; inspect only safe status codes, field names and projected resource metadata.

After an ambiguous write failure, inspect the exact approved scope and resource identity read-only
before retrying. A missing local step record does not prove the provider made no resource. Never
create a second project as a retry, adopt a same-named project without approval, weaken credential
handling, or bypass a plan guard to get past the error.

## Native credential entry needs attention

Read only the command's status metadata; never the saved file or raw dialog output. `cancelled`
means the human stopped: wait rather than reopening it. `unsupported-platform` or
`dialog-unavailable` can use the private-file editor fallback. A timeout needs the human to be
ready before another attempt. An invalid value was not saved; explain the supported single-line
input without quoting what they entered. `already-exists` needs an intentional replacement choice.

For `unsafe-path`, `concurrent-change` or `write-failed`, inspect ownership, permissions, link and
lock metadata, resolve that specific problem and preserve existing contents. Do not bypass the
checks with another writer or repeatedly request a new key. A `saved` result with `cleanupRequired`
means the key was saved but local staging/lock cleanup needs attention; do not ask for it again.
If `envOverride` is true, the existing process environment still wins: resolve which credential
source the human intends without reading back either value. Then resume the provider check.

## Resume the current stage

Read the current config, non-secret state and latest plan/result. Preserve completed steps and
recheck only the prerequisite affected by the repair. Re-plan if required; present any changed
scope or writes and obtain the required approval before apply. A prior approval remains useful
context but is not permission for new resources or changed destinations. Respect any stricter
per-apply approval rule set by the user.

Tell the human what the repair verified, what is already complete, and what deployment step comes
next. Continue within the existing authorization instead of making them repeat signup, provider
selection or successful logins. Keep unresolved checks open; a suggested fix alone is not success.

# Release integrity, installation ownership and updates

Run `node <this-skill-dir>/scripts/golive.mjs version --json` when starting a new deployment run.
It verifies the complete skill against `release.json`, including instructions, references and
runtime. A missing/mixed/corrupt bundle stops before account access. Repair it using the same
installation manager; do not download just a replacement script.

Then run `node <this-skill-dir>/scripts/golive.mjs update-check --json`. This reads only public
release metadata, uses a 24-hour cache and a bounded timeout, and never reads project credentials.
An unavailable/offline result does not block deployment commands. Set `GOLIVE_UPDATE_CHECK=0` or
pass `--offline` to skip the network check. Explain current/latest versions only when useful;
do not repeatedly announce an unchanged result.

## One manager per installed copy

- Skills CLI owns installations it made. Use `npx skills update golive -p` for project scope or
  `-g` for global scope, between runs. A pinned source stays pinned until explicitly changed.
- Plugins use their plugin manager. Never edit plugin caches or lockfiles directly.
- Manual copies are replaced as a complete verified bundle by the user.
- The optional own installer manages only its own receipt-backed copies. Run
  `node <this-skill-dir>/scripts/install-cli.mjs install-status --json` to inspect one. It reports
  duplicates without deleting them. An external copy is never adopted or overwritten implicitly.

## Own installer commands

At a new run boundary, an owned installation can explicitly update to an immutable public tag:

```bash
node <this-skill-dir>/scripts/install-cli.mjs update --between-runs --ref v<version> --json
node <this-skill-dir>/scripts/install-cli.mjs rollback --json
node <this-skill-dir>/scripts/install-cli.mjs update-policy --auto on --json
node <this-skill-dir>/scripts/install-cli.mjs update-policy --auto off --json
```

Automatic replacement is off by default. Only after the user opts in, when `update-check` reports
`manager: owned`, `automaticInstall: true`, `status: available` and a valid `latest.source.ref`,
the agent may invoke `update --auto --between-runs --ref <that-exact-tag> --json` at the start of a
new run. Reload the entire skill and verify its new version afterward. This is startup-driven
automation, not a background daemon. Pinned copies never auto-update.

Updates stage the complete bundle, verify every file and run offline smoke checks — `help` and
`menu --json` under a guard that denies the common network and subprocess entry points, including
socket prototypes, DNS, dgram, HTTP/2, worker threads and cluster forks — before switching the active
pointer. That guard is a sanity check for a broken or careless release, **not a sandbox**: it does not
contain a deliberately hostile bundle, and the gate that matters is the human approving one explicit
update to an immutable public tag. The previous version is retained for local rollback. A
failed/stopped update keeps the prior active version; a stale lock requires the explicit
`recover-lock` command after confirming the original process has stopped. Never remove installation
metadata by hand to bypass a refusal. These operations do not change app config/state, credentials or
cloud resources.
Rolling back the skill does not roll back a deployment or database.

## Approval and resume boundary

Never install an update between `plan` → human approval → `apply`. Plans bind the verified release
and schema versions. After any bundle change, discard the old approval, re-observe with `plan`,
show the new plan and obtain a fresh approval. No old runtime is fetched to make approval pass.

Compatible state keeps resource IDs, fingerprints and evidence. Identical completed operations
remain completed. Changed, failed or ambiguous historical writes may require reconciliation;
do not delete state or force replays to get past that guard. Two exemptions resume by themselves,
because the step declares it: teardown's destruction steps (a deletion re-checks ownership and is
idempotent) and any step whose risk declares `risk.replayable` (an idempotent write that re-observes
the provider and golive's own recorded resource before acting, e.g. the auth test account's password
rotation). Everything else stays blocked. Incompatible schemas stop safely.
There is no general reconciliation command yet. Explain the blocked operation and prepare a
separately reviewed recovery after inspecting the provider; do not promise automatic recovery.
`golive status` states the same boundary: a step that failed under another (or an unknown) release
appears as `release:step:<id>` with `action: human` when it declares neither exemption, and the item
says there that re-running `apply` cannot succeed until that reconciliation has happened — including
when the current plan no longer carries the step at all. A step this release recorded, or one that
declares the exemption, keeps the plain re-run advice.
Existing private golive deployments are not automatically migrated to a differently named product.

# Vercel (hosting): agent notes

Load this when the plan uses `hosting=vercel`. Read it before explaining `doctor`, `plan`, or `verify`
output for Vercel. (Vercel DNS is not
automated: `dns=vercel-dns` is a guided provider, see `guided.md`.)

## 1. Logging in (least friction first)

**Install the Vercel CLI either way** (`npm i -g vercel`; `! npm i -g vercel` is fine in Claude
Code). golive always deploys through the `vercel` binary; a token doesn't replace the CLI.

1. **`vercel login` (preferred).** The human runs it in a **separate terminal window** (the Terminal
   app or their IDE's terminal). It is a browser device-code flow: it shows a code, they approve in the
   browser, and the CLI stores the login where golive can use it. Nothing gets copied. Whether it works
   through Claude Code's `!` prefix (no TTY, output shown only at the end) is unverified, so don't
   suggest `!` for it.
   - CLI old: `npm i -g vercel@latest` first. The old `--github` / `--gitlab` / email logins were
     removed in 2026; use plain `vercel login`.
   - `doctor`'s `via` shows the account and team (`vercel CLI (logged in as alice, team acme)`). Check
     it's the team they expect. `plan.targets` shows the effective team/account of the project;
     an explicit `VERCEL_ORG_ID` can differ from the CLI's default team. Before approval, show
     the frontend destination's display name, project, and new/existing status in chat. The
     approved scope is bound to the plan; changing it requires a new plan and explicit approval.
2. **Token (alternative to `vercel login`, not to the CLI).** The human creates a **team-scoped token with an expiry** at
   https://vercel.com/account/tokens. On macOS, run `credentials --prompt VERCEL_TOKEN --json` so
   they enter it in the private native dialog. Use their own editor only if unavailable, unsupported,
   or preferred; follow [How the human connects accounts](../SKILL.md#how-the-human-connects-accounts)
   for fallback, replacement and cancellation. Never put the value in chat or arguments. A token exported in their own terminal
   doesn't reach the agent's shell. `doctor` then shows `via: VERCEL_TOKEN (user …)`, but reports
   Vercel as not ready ("install it: npm i -g vercel") while the CLI is missing. golive hands the token
   to `vercel deploy` through the child's `VERCEL_TOKEN` env var, never `--token` (argv shows up in
   process lists). Never suggest `--token` to the human either.

## 2. What golive does vs. what stays with the human

golive automates (after plan approval):
- **Picks the project** (`project:hosting`): the linked one, else `projects.hosting` from `golive.yaml`,
  else a same-named one, else a Create step that lists existing projects the human could use instead
  (`init --project hosting=<name>`).
- Writes env vars **by name** for Production and Preview separately: secrets as Vercel's **Sensitive**
  type (write-only), public values as Encrypted. Local development is left to `.env.local`. It checks
  every target before writing any, so a refusal (hidden production env, a Marketplace-owned var, or
  one var shared with other environments) never leaves a var half-written.
- Deploys production with the CLI when needed (see `plan-and-verify.md`: production env changed, a
  pending or failed deploy, or never deployed by golive).
- Finds the **public production URL**: the verified custom domain, else the alias Vercel actually
  assigned (exact `<project>.vercel.app`, then a custom domain, then the shortest non-branch
  `*.vercel.app` alias). Before the first successful production deploy there is no URL, and golive
  never guesses `https://<project>.vercel.app` (that name may belong to someone else).
- **Custom domain:** `domain:attach`, then the **project-specific** DNS records Vercel wants go to an
  automated DNS provider (`--confirm-dns`) or into a handoff, then `domain:verify` asks Vercel to verify
  ownership (`POST /v9/projects/{id}/domains/{domain}/verify`). That call is a write, because success
  moves the domain away from another Vercel account/team, so it runs only as an approved step and
  never re-verifies a verified domain. A missing or mismatched TXT record gives `pending` (DNS
  propagating: re-run `plan` / `apply` later). While the domain isn't live, each plan re-sends
  `domain:attach` (idempotent), so a hosting-project switch or a domain removed in the dashboard is
  re-attached.
- Verifies: `env-parity` (names per environment, never values), `bundle-secrets`, `webhook-unsigned`,
  `domain-live` (passes only when Vercel reports the domain `ok`; `pending` warns).

Stays with the human (and why):
- **Deployment Protection settings.** golive doesn't switch protection off: it's a security downgrade.
  Its probes go to the public production URL, which Standard Protection leaves public. If
  `bundle-secrets` warns that production redirects to `vercel.com/sso-api`, "All Deployments"
  protection is on; the human decides whether to make production public.
- **Env vars owned by a Marketplace integration** (e.g. Supabase or Stripe installed through Vercel).
  golive adopts them and never overwrites them. If the code expects a different name, change the code.
- **Values golive can't source** (`unmappedEnv`, e.g. `OPENAI_API_KEY`). The human types them straight
  into the Vercel dashboard (Project → Settings → Environment Variables). Never through chat.
- **Team roles.** If the login's role can't see some production vars, golive can't verify or write
  production env (§4).
- Buying a domain, upgrading plans, adding payment methods.

## 3. Explain these in plain words

- **"Your deployment link asks for a Vercel login."** New projects start with Standard Protection. It
  protects every generated URL, *including the long unique URL a production deploy prints*
  (`<project>-<hash>-<team>.vercel.app`). The public addresses are the production alias and custom
  domains. Share those, and point webhooks at those.
- **Webhooks to preview deployments fail.** Stripe can't log in to Vercel. golive registers webhooks for
  production only.
- **Env changes need a redeploy.** Existing deployments keep the old values. golive redeploys production
  after it writes production env; preview-only changes apply on the next preview deploy. After a
  dashboard edit, the human redeploys.
- **Secret vars can't be read back**, even in the dashboard. That's intended. `verify` checks names
  only.
- **Browser-visible names** (`NEXT_PUBLIC_`, `VITE_`, names inlined by the framework config, …) ship to
  every visitor. golive won't write a server secret into them; `detect` flags it as critical.
- **DNS values are per project.** Blog posts say `76.76.21.21` or `cname.vercel-dns.com`; don't use
  those. Use exactly the records `plan` prints. On a project never deployed by golive, the first
  production deploy runs before the domain is attached.
- **Auth redirect URLs for previews:** preview hostnames are unpredictable. golive adds preview
  wildcards to the (production) auth allowlist only with `auth.previewRedirects: true`.
- The Vercel CLI sometimes suggests `--value "<value>"` in its hints. **Don't follow that for
  secrets**: it puts the value on the command line.

## 4. Troubleshooting

| Symptom | What to do |
|---|---|
| `doctor`: not logged in | Human runs `vercel login` in a real terminal window (not `!`), then re-run `doctor`. |
| `doctor`: "install it: npm i -g vercel" (even with `VERCEL_TOKEN`) | The CLI is missing; deploys need it. Install, re-run `doctor`. Plans stay blocked on `login:vercel` until then. |
| Deploy fails with code `cli_missing` | Same: install the CLI and re-run `apply`. |
| Login fails or asks for a removed method | `npm i -g vercel@latest`, then plain `vercel login`. |
| "VERCEL_TOKEN is set but Vercel rejected it" | Remove that line from the credentials file (or the agent's env) and use `vercel login`, or replace it with a new token. |
| `vercel api` not found / unknown command | CLI too old (`vercel api` is beta). Update the CLI (`npm i -g vercel@latest`), or add a `VERCEL_TOKEN` to the credentials file (API calls then skip `vercel api`; deploys still use the CLI). |
| A var is refused: "split per environment in the Vercel dashboard" | One Vercel var row covers environments golive wasn't asked to write. The human splits it into one per environment (Project → Settings → Environment Variables), then `plan` again. For the webhook secret this shows as a blocking `stripe:webhook-env` handoff and no endpoint is created. |
| `cannot verify production env: N … hidden from this Vercel login's role` (code `hidden_env`) | The role can't see some production vars, so golive won't report them missing and refuses to write production env. Have a team Owner run golive, or grant a role that can read production env. |
| `bundle-secrets` warns the page redirects to `vercel.com/sso-api` or a login | Production is behind protection or an auth wall; its scripts weren't scanned. Make production public, re-run `verify`. |
| A check says `cannot confirm … belongs to your project yet` | No confirmed production URL yet (never deployed, or domain not verified at Vercel). Apply the deploy / domain steps, then re-run. |
| App says a var is undefined after wiring | Redeploy. Check the var targets the right environment. Client-side vars need the framework prefix. |
| `production_secret_must_be_separate` | Team policy: one Secret can't span production and preview. golive already writes them separately. |
| Env var skipped as "managed by a Vercel Marketplace integration" | Adopt it; rename in code if needed. |
| Adding the domain returns 400 about the latest production deployment | Fix the failing deploy first, then re-run `apply`. |
| Domain already assigned to another project / account | The human removes it there (Vercel dashboard → Domains), or adds the TXT record from `plan` so `domain:verify` can move it. |
| "Vercel is already verifying <domain> for another project" | The human removes the domain from that project in the Vercel dashboard, then re-run `apply`. |
| `domain:verify` pending | TXT record not visible yet. Wait for DNS, run `plan` / `apply` again. |
| Domain `misconfigured` | DNS record not created yet, still propagating, or proxied (Cloudflare orange cloud). See `cloudflare-dns.md`. |
| Deploy output isn't a URL | Normal in agent mode: the CLI prints JSON. golive parses both shapes. |

## Unverified

- Whether `vercel login` (device-code flow) completes under Claude Code's `!` prefix, which has no
  TTY. That path is unverified, so these notes always say "separate terminal".
- Whether the production alias stays public under Standard Protection in every case (docs imply yes).
- Exactly how env "upsert" behaves when an existing var has different targets or type. golive lists
  first and plans explicitly instead of relying on it.