@rtrentjones/greenlight 0.4.1 → 0.5.0

package/assets/skills/provider-cloudflare/SKILL.md

@@ -1,45 +1,46 @@
 ---
 name: provider-cloudflare
-description: How Cloudflare works in a Greenlight setup — the zone/DNS provider for every tool, Workers as the keepalive/blog target, token scoping (Workers Scripts:Edit + Zone DNS:Edit), and the Cloudflare MCP. Use when wiring DNS, the keepalive worker, a workers-target tool, or debugging a Cloudflare apply/token.
+description: Cloudflare in a Greenlight setup — the always-on DNS/zone provider, the keepalive Worker host, the workers runtime. Use when wiring DNS, the keepalive Worker, a workers-target tool, or debugging a Cloudflare apply or token scope.
 ---
 
 # provider-cloudflare
 
-Cloudflare is the **always-on** provider in Greenlight: it owns the DNS zone for the
-domain (every tool's `<name>.<domain>` CNAME), hosts the **keepalive** Worker (a Cron
-Trigger, immune to repo-inactivity disable), and is the `target: workers` runtime for the
-blog and throwaway MCP dev targets.
+Cloudflare is the **always-on** provider: it owns the DNS zone for the domain (every tool's
+`<name>.<domain>` CNAME), hosts the **keepalive** Worker (a Cron Trigger, immune to
+repo-inactivity disable), and is the `target: workers` runtime for the blog and throwaway MCP
+dev targets.
 
 ## Token — `CLOUDFLARE_API_TOKEN`
 
-One token, these scopes (a missing scope took down a live apply more than once):
-- **Account · Workers Scripts · Edit** — deploy the keepalive worker / workers-target tools.
-- **Zone · DNS · Edit** — the subdomain CNAMEs.
-- **Account · Account Settings · Read** — read account id.
-- **Account · Cloudflare Tunnel · Edit** — only if a tool uses `target: oci` (the cloudflared
-  tunnel). Without it, the tunnel resource fails with **403 Forbidden** on `cfd_tunnel` at apply.
-
-Create at dash → My Profile → API Tokens → Custom Token. Push it straight to GitHub Actions
-with `greenlight secrets gather` (or `gh secret set CLOUDFLARE_API_TOKEN`) — Greenlight keeps
-no local secret file. `greenlight add` verifies it against `/user/tokens/verify` (status must
-be `active`) before you commit.
+Scopes, creation, and the verify command live in
+[tokens-reference.md](https://github.com/RTrentJones/greenlight/blob/main/docs/tokens-reference.md).
+The short of it: **Account · Workers Scripts:Edit + Zone · DNS:Edit + Account · Account
+Settings:Read** (+ **Account · Cloudflare Tunnel:Edit** only if any tool is `target: oci`).
+Single store: **GitHub Actions secrets** (no local secret file). `greenlight add` fails fast on a
+mis-scoped token — beyond `status: active` it probes `/accounts`, so a Zone-DNS-only token (which
+can't see the account it needs) is rejected before you commit.
 
 ## Terraform modules
 
-- `infra/modules/tool` — the subdomain DNS record. `proxied = target != "vercel"` (Vercel
-  needs an unproxied CNAME to `cname.vercel-dns.com`; everything else is proxied).
+- `infra/modules/tool` — the subdomain DNS record. `proxied = target != "vercel"` (Vercel needs an
+  unproxied CNAME to `cname.vercel-dns.com`; everything else is proxied).
 - `infra/modules/keepalive` — `cloudflare_workers_script` + `cloudflare_workers_cron_trigger`,
-  self-contained (ships its own bundled `worker.js`). One worker aggregates all targets via
-  `targets_json`; do **not** emit a worker per tool. Needs a workers.dev subdomain registered
-  on the account once (error 10063 if missing).
+  self-contained (bundled `worker.js`). **One** worker aggregates all targets via `targets_json`;
+  do not emit a worker per tool.
 
 ## MCP
 
 `.mcp.json` wires `cloudflare` (Workers/DNS/R2/KV/D1/builds/observability) + `cloudflare-docs`.
-Run `/mcp` to authenticate. For richer help: the `cloudflare@cloudflare` plugin skill.
+Run `/mcp` to authenticate.
 
 ## Gotchas
-- A DNS record for the apex managed by **wrangler** (Workers custom domain) collides with a
-  Terraform `cloudflare_dns_record` for the same name — pick one owner per record.
-- The `observability` block on `cloudflare_workers_script` has a provider bug
-  (propagation_policy conversion error) — leave it off.
+- **Account id from a scoped token (`/memberships` 403).** A scoped API token can't call
+  `/memberships` to discover the account id, so Workers/wrangler deploys that need it fail. Resolve
+  the account id **from the zone** in CI (the agent-lane deploy workflow does exactly this) or write
+  it into `wrangler.toml` at `add` time — never rely on `/memberships`.
+- **workers.dev subdomain (error 10063).** A first Workers deploy needs a workers.dev subdomain
+  registered on the account once.
+- **Wrangler vs Terraform DNS ownership.** A record managed by wrangler (a Workers custom domain)
+  collides with a Terraform `cloudflare_dns_record` of the same name — one owner per record.
+- **`observability` block on `cloudflare_workers_script`** trips a provider bug (propagation_policy
+  conversion error) — leave it off.

package/assets/skills/provider-gemini/SKILL.md

@@ -1,78 +1,64 @@
 ---
 name: provider-gemini
-description: How the `agent` lane works in Greenlight — an autonomous cron-triggered Cloudflare Worker backed by Google Gemini (free tier). Covers the GEMINI_API_KEY (Google AI Studio, no billing), the gemini-2.5-flash generateContent call, the wrangler deploy (cron + KV + secret + custom_domain), the /, /status, /run surface, api-mode verify, and the free-tier safety envelope. Use when building, deploying, or verifying an agent tool.
+description: The `agent` lane in Greenlight — an autonomous cron-triggered Cloudflare Worker backed by Google Gemini (free tier). Use when building, deploying, or verifying an agent tool, or debugging its KV / account-id / seed wiring.
 ---
 
 # provider-gemini
 
 The `agent` lane is an **autonomous tool**: a Cloudflare Worker that wakes on a **cron trigger**,
-calls **Gemini** (Google's LLM, free tier), does low-stakes work, stores the result in KV, and
-exposes a tiny HTTP surface. It's the keepalive Worker pattern promoted to a user tool — free,
-always-available, immune to repo-inactivity, no OCI box, no new paid account.
-
-`agent` → target **workers**, data **none | kv** (kv holds the last output + run metadata).
+calls **Gemini** (free tier), does low-stakes work, stores the result in KV, and exposes a tiny
+HTTP surface. It's the keepalive-Worker pattern promoted to a user tool — free, always-available,
+immune to repo-inactivity, no OCI box, no paid account. `agent` → target **workers**, data
+**none | kv** (kv holds the last output + run metadata).
 
 ## Token — `GEMINI_API_KEY`
 
-Create it at **Google AI Studio** (https://aistudio.google.com/apikey) — **free tier, no billing,
-no card**. `greenlight add` verifies it against `…/v1beta/models?key=…` (HTTP 200). One key serves
-every agent (shared, not per-tool). It is a **Cloudflare Worker secret** (`wrangler secret put
-GEMINI_API_KEY`) — never in the repo.
+Creation + verify live in
+[tokens-reference.md](https://github.com/RTrentJones/greenlight/blob/main/docs/tokens-reference.md).
+**Free tier, no billing / no card** (Google AI Studio). One key serves every agent (shared, not
+per-tool); stored as a **Cloudflare Worker secret** (`wrangler secret put`), never in the repo.
+`RUN_TOKEN` (bearer-gates `POST /run`) is the second Worker secret.
 
 ## The model + call
 
-`gemini-2.5-flash` (fast; generous free limits — ~15 RPM / 1500 req/day, so a daily cron is ~1/day).
+`gemini-2.5-flash` (fast; ~15 RPM / 1500 req/day free, so a daily cron is ~1/day).
 
 ```
 POST https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=${GEMINI_API_KEY}
-{ "contents": [{ "parts": [{ "text": "<prompt>" }] }] }
-→ candidates[0].content.parts[0].text
+{ "contents": [{ "parts": [{ "text": "<prompt>" }] }] }   → candidates[0].content.parts[0].text
 ```
 
 ## Deploy — emitted CI (push to main)
 
-`greenlight add` resolves the Cloudflare **account id** into `wrangler.toml` (so wrangler skips the
-`/memberships` call a scoped token can't do) and emits **`.github/workflows/deploy-<name>.yml`**. On
-a push to main that touches `tools/<name>`, that workflow: **creates the KV namespace** (find-or-create
-in-CI — no manual step, the id stays a placeholder), deploys the Worker (cron + `custom_domain` from
-`wrangler.toml`), sets the `GEMINI_API_KEY` + `RUN_TOKEN` **Worker secrets** from GitHub secrets, seeds
-the first run, and verifies. So the only setup is **adding those two GitHub secrets**. (Local instead:
-`pnpm exec wrangler deploy --env prod`.)
-
-`wrangler.toml` carries the cron + KV binding + the per-env `custom_domain` route; no Terraform.
+`greenlight add` emits `.github/workflows/deploy-<name>.yml`. On a push to main that touches
+`tools/<name>` it: creates the KV namespace (find-or-create in CI), deploys the Worker (cron +
+`custom_domain`), sets `GEMINI_API_KEY` + `RUN_TOKEN` Worker secrets from GitHub secrets, seeds the
+first run, and verifies. The only manual setup is **adding those two GitHub secrets**. `wrangler.toml`
+carries the cron + KV binding + per-env `custom_domain`; no Terraform. (Local: `wrangler deploy --env prod`.)
 
-```toml
-[triggers]
-crons = ["0 13 * * *"]            # daily; stays far under the free-tier quota
-[[kv_namespaces]]
-binding = "STATE"
-[[routes]]
-pattern = "<name>.<domain>"
-custom_domain = true
-```
-
-## Surface
+## Surface + verify
 
 | route | purpose |
 |---|---|
 | `scheduled()` | the cron: prompt Gemini → `STATE.put(today, text + metadata)` |
-| `GET /` | the latest output (public, read-only) |
+| `GET /` | latest output (public, read-only) |
 | `GET /status` | `{ ok, lastRun, model, preview }` — the **api-mode verify** target |
-| `POST /run` | force a run — **bearer-gated** (a `RUN_TOKEN` secret) so randoms can't burn the Gemini quota; lets deploy/verify seed the first output |
-
-## Verify — `api` mode on `/status`
-
-`verify.config.ts` hits `/status` and asserts `ok: true` + a recent run. (Output *quality* is a
-future `eval` mode — LLM-judged.) Because the first cron may not have fired at deploy time, the
-deploy step `POST /run`s once to seed, then verifies.
+| `POST /run` | force a run — **bearer-gated** (`RUN_TOKEN`); lets deploy/verify seed the first output |
+
+`verify.config.ts` hits `/status` and asserts `ok` + a recent run. (Output *quality* is a future
+`eval` mode — LLM-judged.)
+
+## Gotchas
+- **KV namespace as code (no manual id).** The deploy workflow does a **find-or-create** on the KV
+  namespace in CI and binds it — the `wrangler.toml` id stays a placeholder, never hand-filled.
+- **Account id from a scoped token.** `add` resolves the Cloudflare account id into `wrangler.toml`
+  so wrangler skips the `/memberships` call a scoped token can't make (see provider-cloudflare).
+- **Seed before verify.** The first cron may not have fired at deploy time, so `/status` would
+  (correctly) report no run — the deploy step `POST /run`s once to seed *before* verifying. Don't
+  reorder these.
+- **No keepalive.** The cron *is* the heartbeat and the edge Worker is always-available — never add
+  an agent to `module.keepalive.targets_json`.
 
 ## Safety envelope
-
-- **Low-stakes / read-only** first agents (generate → store → serve; no destructive external actions).
-- **Bearer on `/run`**; the cron frequency stays far under the free-tier daily limit.
-- Key is **secret-only** (a Worker secret), never committed or echoed.
-
-## No keepalive
-
-An agent needs no keepalive — the cron *is* its heartbeat and the Worker is always-available
-(Cloudflare's edge, not a reclaimable box). Don't add it to `module.keepalive.targets_json`.
+Low-stakes / read-only first agents (generate → store → serve, no destructive external actions);
+bearer on `/run`; cron frequency far under the free-tier daily limit; key secret-only, never echoed.

package/assets/skills/provider-github/SKILL.md

@@ -1,43 +1,42 @@
 ---
 name: provider-github
-description: How GitHub works in a Greenlight setup — the single secret store (Actions secrets/environments), the repo/branch/protection Terraform module, the develop→main flow, and OIDC-over-PAT preference. Use when setting tokens, wiring branch protection/environments, or debugging gh/secrets/CI auth.
+description: GitHub in a Greenlight setup — the single secret store (Actions secrets/environments), the repo/branch/protection module, the develop→main flow, OIDC-over-PAT. Use when setting tokens, wiring branch protection/environments, or debugging gh / secrets / CI auth.
 ---
 
 # provider-github
 
-GitHub is the **always-on** control plane: it holds the Actions **secrets** (provider tokens),
-the **environments** (beta/prod), branch protection, and runs the deploy/promote/infra
-workflows. The `develop → main` flow is standardized (PR → preview, `develop` → beta, `main`
-→ prod; promote is a gated fast-forward).
+GitHub is the **always-on** control plane: it holds the Actions **secrets** (provider tokens), the
+**environments** (beta/prod), branch protection, and runs the deploy/promote/infra workflows. The
+`develop → main` flow is standardized (PR → preview, `develop` → beta, `main` → prod; promote is a
+gated fast-forward).
 
-## Token — `GITHUB_TOKEN` (usually you don't set one)
+## Token — `GITHUB_TOKEN` (you usually don't set one)
 
-- In **CI**, Actions provides `github.token` automatically — the infra.yml maps it to the
-  `github` provider. No PAT needed for single-repo infra.
-- For **cross-repo** ops (managing another repo's settings, syncing secrets to a tool repo),
-  use a fine-grained **PAT** with the minimal scopes (e.g. `Secrets: write`, `Administration`
-  for protection). Prefer **GitHub OIDC → cloud** over long-lived cloud tokens where supported.
+In **CI**, Actions provides `github.token` automatically — `infra.yml` maps it to the `github`
+provider; no PAT for single-repo infra. For **cross-repo** ops, use a fine-grained PAT with minimal
+scopes; prefer **GitHub OIDC → cloud** over long-lived cloud tokens where supported. Full token table:
+[tokens-reference.md](https://github.com/RTrentJones/greenlight/blob/main/docs/tokens-reference.md).
 
 ### Poly-repo deploy loop — the two option-B PATs
 
 An adopted tool (submodule) and its wrapper hand off via two fine-grained PATs (`secrets gather`
-pushes each to the right repo; see docs/provider-tokens.md):
-
-- **`GREENLIGHT_DISPATCH_TOKEN`** — on the **tool** repo, scoped **Contents: write** on the
+pushes each to the right repo):
+- **`GREENLIGHT_DISPATCH_TOKEN`** — on the **tool** repo, scoped **Contents:write** on the
   **wrapper** → the tool's build fires `repository_dispatch` so the wrapper deploys.
-- **`GREENLIGHT_STATUS_TOKEN_<TOOL>`** — on the **wrapper** repo, scoped **Commit statuses: write**
-  on the **tool** → the wrapper posts deploy/verify status back to the tool's commit. **Per-tool
-  suffix** (e.g. `…_BAMCP`) because it lives on the shared wrapper alongside other tools' tokens.
+- **`GREENLIGHT_STATUS_TOKEN_<TOOL>`** — on the **wrapper** repo, scoped **Commit statuses:write** on
+  the **tool** → the wrapper posts deploy/verify status back. **Per-tool suffix** (it lives on the
+  shared wrapper alongside other tools' tokens).
 
 Provider creds (OCI/Cloudflare/…) live **only in the wrapper**; the tool repo holds just the
-dispatch PAT (its build pushes to GHCR with the built-in `github.token`).
+dispatch PAT (its build pushes to GHCR with the built-in `github.token`). Optimal end state: a tool
+repo holds **only** `GREENLIGHT_DISPATCH_TOKEN`.
 
 ## Setting secrets
 
-GitHub Actions secrets are the **single** secret store — Greenlight keeps no local secret file.
-`greenlight secrets gather <tool> [--repo o/r] [--env <env>]` prompts the tool's tokens (and the
-always-on base tokens) with hidden input and pipes them straight to `gh secret set` (never on
-disk, never in argv or logs). Run `gh auth login` first. `gh secret set` is the manual alternative.
+GitHub Actions secrets are the **single** store (no local secret file). `greenlight secrets gather
+<tool> [--repo o/r] [--env <env>]` prompts with hidden input and pipes straight to `gh secret set`
+(never on disk, in argv, or logs); `greenlight secrets check [<tool>]` lists the secrets a tool's
+deploy needs and flags missing ones. Run `gh auth login` first.
 
 ## Terraform module — `infra/modules/repo`
 
@@ -45,6 +44,8 @@ Branches + protection + required checks (+ optional environments via the `tool`
 `manage_github_environments`). For an **external** tool (code in its own repo), set
 `manage_github_environments = false` so the wrapper's CI stays single-repo (no PAT needed).
 
-## Gotcha
-Direct pushes/merges to a protected `main` are blocked — use `gh pr create` + merge, or the
-gated `greenlight promote` fast-forward. Keep to `develop` (not `development`) for the branch.
+## Gotchas
+- **IDs are repo variables, not secrets.** Enumerable IDs (`CLOUDFLARE_ZONE_ID`, account ids) carry
+  no authority — store them as `vars.*` (referenced `${{ vars.X }}`), not secrets.
+- **Protected `main`** blocks direct pushes/merges — use `gh pr create` + merge, or the gated
+  `greenlight promote` fast-forward. Keep to `develop` (not `development`) for the branch.

package/assets/skills/provider-hcp/SKILL.md

@@ -1,25 +1,25 @@
 ---
 name: provider-hcp
-description: How HCP Terraform works in a Greenlight setup — the remote-state backend (free tier, no credit card), local execution mode (HCP stores state + locks; runs use local/CI creds), the cloud{} block, and TF_API_TOKEN auth. Use when setting up remote state, debugging a backend/init/locking issue, or CI apply-on-push.
+description: HCP Terraform in a Greenlight setup — the remote-state backend (free tier, no card) in Local execution mode (HCP stores state + locks; runs use CI creds). Use when setting up remote state, debugging a backend/init/locking issue, or CI apply-on-push.
 ---
 
 # provider-hcp
 
-HCP Terraform (app.terraform.io) is the **remote-state backend** for the wrapper's infra —
-free tier, **no credit card**. It replaces local state so CI can `terraform apply` on push
-with state locking (no two applies racing).
+HCP Terraform (app.terraform.io) is the **remote-state backend** for the wrapper's infra — free
+tier, **no credit card**. It replaces local state so CI can `terraform apply` on push with state
+locking (no two applies racing).
 
 ## Execution mode — **Local**, deliberately
 
 The workspace is set to **Local execution mode**: HCP **stores state + does locking only**;
-`terraform` runs here / in CI with **our own provider creds** (Cloudflare/Vercel/Supabase
-tokens from GitHub Actions secrets). This avoids uploading every provider token to HCP.
+`terraform` runs here / in CI with **our own provider creds** (from GitHub Actions secrets). This
+avoids uploading every provider token to HCP.
 
 ## Token — `TF_API_TOKEN`
 
-HCP → Account Settings → Tokens (a **user** API token). In CI it maps to the backend-auth env
-var **`TF_TOKEN_app_terraform_io`** (the infra.yml does this mapping). `greenlight add`
-verifies it against `/api/v2/organizations` (HTTP 200).
+A **user** API token (HCP → Account Settings → Tokens). Verify command + table:
+[tokens-reference.md](https://github.com/RTrentJones/greenlight/blob/main/docs/tokens-reference.md).
+In CI it maps to the backend-auth env var **`TF_TOKEN_app_terraform_io`** (`infra.yml` does this).
 
 ## The `cloud{}` block
 
@@ -32,15 +32,14 @@ terraform {
 }
 ```
 
-Migrate local → HCP with a plain `terraform init` (answer `yes` to copy state). The
-`-migrate-state` / `-force-copy` flags are **rejected** for the cloud backend — don't pass them.
-
 ## CI apply-on-push
 
-`infra.yml` (on push to `main`, paths `infra/**`): map GH secrets → `TF_TOKEN_app_terraform_io`
-+ the provider tokens + `TF_VAR_*`, then setup-terraform (`terraform_wrapper: false`) → init →
-plan -out → apply. This is the deploy half — the CLI only edits the `.tf`; CI applies.
+`infra.yml` (on push to `main`, paths `infra/**`): map GH secrets → `TF_TOKEN_app_terraform_io` + the
+provider tokens + `TF_VAR_*`, then setup-terraform (`terraform_wrapper: false`) → init → plan -out →
+apply. The CLI only edits the `.tf`; CI applies.
 
-## Alternatives
-See `docs/terraform-state.md` for the full backend chooser (HCP no-CC · OCI S3-compat ·
-R2 card-required · AWS · local).
+## Gotchas
+- **Migrate local → HCP** with a plain `terraform init` (answer `yes` to copy state). The
+  `-migrate-state` / `-force-copy` flags are **rejected** for the cloud backend — don't pass them.
+- **Alternatives:** `docs/terraform-state.md` has the full backend chooser (HCP no-CC · OCI
+  S3-compat · R2 card-required · AWS · local).

package/assets/skills/provider-neon/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: provider-neon
-description: How Neon works in a Greenlight setup — the `data: neon` store (serverless Postgres), git-style branch-per-env, scale-to-zero + auto-resume (so NO keepalive, unlike Supabase), pooled vs direct connection strings, the NEON_API_KEY, and migrations on a branch. Use when wiring a tool's database, choosing Neon vs Supabase, or a Neon apply.
+description: Neon in a Greenlight setup — the `data: neon` store (serverless Postgres, branch-per-env, auto-resume → no keepalive). Use when wiring a tool's database, choosing Neon vs Supabase, or debugging a Neon apply or connection string.
 ---
 
 # provider-neon
@@ -9,15 +9,16 @@ description: How Neon works in a Greenlight setup — the `data: neon` store (se
 bundled. One Neon **project** per tool, **a branch per env** (git-style copy-on-write): `prod` is
 the project's default branch; `beta` is a child branch (separate data, instant to create). Compute
 **autosuspends and auto-resumes on the next connection**, so a Neon tool needs **no keepalive** —
-that's the whole reason Neon is preferred over Supabase, which pauses for 7 days and needs a manual
-unpause. Choose `supabase` only when you need bundled auth + storage + realtime together.
+that's the whole reason Neon is preferred over Supabase (which pauses for 7 days and needs a manual
+unpause). Choose `supabase` only when you need bundled auth + storage + realtime together.
 
 ## Token — `NEON_API_KEY`
 
-Console → Account settings → API keys. Account-level (configures the `neon` provider for every Neon
-tool, like `CLOUDFLARE_API_TOKEN`) — **not** per-tool. `greenlight add` verifies it against
-`/api/v2/projects` (HTTP 200). There is **no per-tool secret**: the role/password/connection strings
-are module OUTPUTS, not inputs.
+Creation + verify live in
+[tokens-reference.md](https://github.com/RTrentJones/greenlight/blob/main/docs/tokens-reference.md).
+Account-level (configures the `neon` provider for every Neon tool, like `CLOUDFLARE_API_TOKEN`) —
+**not** per-tool, and there is **no per-tool secret**: the role/password/connection strings are
+module OUTPUTS, not inputs.
 
 ## Terraform module — `infra/modules/neon`
 
@@ -29,37 +30,32 @@ which is ephemeral/per-PR — created by CI, not Terraform). Outputs two per-env
 The emitted `<name>.tf` wires `database_url["prod"]`/`["beta"]` into the Vercel env per target, so
 prod and beta hit **different branches**. Pin the provider `kislerdm/neon ~> 0.13`.
 
-## No keepalive
-
-Do **not** add a Neon tool to `module.keepalive.targets_json`. Neon resumes on connect — a request
-just wakes it. (`doctor` does not flag `data: neon` for keepalive; that exemption is intentional.)
-
 ## Schema as code / migrations
 
-**Greenlight does NOT run migrations — by design.** The split:
-- **Schema** lives in the tool (an ORM — Drizzle/Prisma — or plain `.sql` migrations).
-- **Branch-per-env**: the TF module owns stable `prod`/`beta`; the **native Neon↔Vercel integration**
-  owns ephemeral per-PR preview branches (+ auto-injects `DATABASE_URL`). Don't put ephemeral branches
-  in Terraform.
-- **Execution**: the app's own build runs its migrate (`drizzle-kit migrate` / `prisma migrate deploy`)
-  against the wired **`DIRECT_URL`** — prod build → prod branch, preview build → preview branch. A
-  failed migrate fails the build = a natural gate.
-- **Greenlight's role**: the **dangerous-SQL gate**. Run `greenlight migrations scan` (no `<dir>` →
-  it auto-detects `supabase/migrations | migrations | drizzle/migrations | …`) in CI before the migrate.
-
-See [docs/migrations.md](../../../docs/migrations.md).
+**Greenlight does NOT run migrations — by design.** Schema lives in the tool (Drizzle/Prisma or
+plain `.sql`); the app's own build runs its migrate against the wired **`DIRECT_URL`** (prod build →
+prod branch, preview build → preview branch; a failed migrate fails the build = a natural gate). The
+**native Neon↔Vercel integration** owns ephemeral per-PR preview branches (don't put those in
+Terraform). Greenlight's only role is the **dangerous-SQL gate**: run `greenlight migrations scan`
+(auto-detects `supabase/migrations | migrations | drizzle/migrations | …`) in CI before the migrate.
+See [migrations.md](https://github.com/RTrentJones/greenlight/blob/main/docs/migrations.md).
 
 ## Sharing one DB + multi-account
-
-- **One DB, many services**: a second tool sets `dataShareWith: '<owner>'` (or `add … --share <owner>`)
+- **One DB, many services:** a second tool sets `dataShareWith: '<owner>'` (or `add … --share <owner>`)
   — it creates no project and wires the owner's connection strings.
-- **A second Neon account**: `tokenOverrides: { NEON_API_KEY: 'NEON_API_KEY_X' }` → an aliased `neon`
-  provider authenticates that account. (A sharer can't also override — it uses the owner's account.)
+- **A second Neon account:** `tokenOverrides: { NEON_API_KEY: 'NEON_API_KEY_X' }` → an aliased `neon`
+  provider authenticates that account. (A sharer can't also override.)
 
 ## MCP
-
 `.mcp.json` wires `neon` (hosted) with `Authorization: Bearer ${NEON_API_KEY}`. Run `/mcp` to auth.
 
-## Rule
-The **blog must never use a database** that can pause — but Neon's auto-resume makes it safe for
-*tools*; still, the apex blog stays `data: none` (D1/KV/external only). Neon is per-tool Postgres.
+## Gotchas
+- **Free-tier `history_retention_seconds` cap (21600).** Neon's free plan caps history retention at
+  **21600s (6h)** — the module must not request more or the apply 400s. Point-in-time restore is
+  bounded to that window on free.
+- **`pooler_enabled` is a non-issue.** Both connection strings are module outputs regardless — wire
+  `database_url` (pooled) to the app and `direct_url` to migrations; there's no pooler flag to toggle.
+- **No keepalive.** Don't add a Neon tool to `module.keepalive.targets_json` — it resumes on connect,
+  and `doctor` intentionally does not flag `data: neon` for keepalive.
+- **The blog stays `data: none`.** Neon's auto-resume makes it safe for *tools*, but the apex blog
+  uses D1/KV/external only (it must never depend on a store that can pause or error).

package/assets/skills/provider-oci/SKILL.md

@@ -1,74 +1,63 @@
 ---
 name: provider-oci
-description: How Oracle Cloud (OCI) works in a Greenlight setup — the `target: oci` runtime for stateful MCP servers (BAMCP) on a free-tier Ampere A1 Container Instance, the provider-agnostic build-via-GitHub→GHCR model, Greenlight-owned compute + tunnel Terraform, the OCI token CLI, deploy = restart, and staying on the free tier (no PAYG; recover-on-alert). Use when wiring/debugging an oci-target tool.
+description: Oracle Cloud (OCI) in a Greenlight setup — the `target: oci` runtime for stateful MCP servers on a free-tier Ampere A1 Container Instance (build-via-GitHub→GHCR; Greenlight-owned compute + tunnel). Use when wiring or debugging an oci-target tool.
 ---
 
 # provider-oci
 
 OCI is the `target: oci` runtime for **stateful** services that don't fit serverless — the
-canonical case is **BAMCP** (a stateful MCP server). The split: **the tool is provider-agnostic
-and just builds a container via GitHub; Greenlight owns the OCI infra** (compute + tunnel + DNS),
+canonical case is **BAMCP** (a stateful MCP server). The split: **the tool is provider-agnostic and
+just builds a container via GitHub; Greenlight owns the OCI infra** (compute + tunnel + DNS),
 configured in the wrapper.
 
 ## Free tier — A1 Container Instance + GHCR
 
-The Always-Free path is an **OCI Container Instance** on **Ampere A1** (the A1 allotment — 2 OCPU
-/ 12 GB as of 2026-06-15 — is shared across VM / Bare-Metal / Container-Instances). No VM to
-provision, no cloud-init, no SSH. The image comes from **GHCR** (free); **OCI's own registry
-(OCIR) is paid** — that was the trap in the old BAMCP pipeline. The container instance runs the
-tool container + a **cloudflared sidecar** (shared netns → localhost), exposed at `<name>.<domain>`.
-
-## Provider-agnostic tool → GHCR
-
-The tool repo (BAMCP) has ONE job: a GitHub Actions workflow that **builds + pushes the container
-to GHCR**. No OCI, no SSH, no deploy logic — portable to any provider's infra.
+The Always-Free path is an **OCI Container Instance** on **Ampere A1** (2 OCPU / 12 GB, shared
+across VM / Bare-Metal / Container-Instances). No VM, no cloud-init, no SSH. The image comes from
+**GHCR** (free); **OCI's own registry (OCIR) is paid** — that was the old-pipeline trap. The
+instance runs the tool container + a **cloudflared sidecar** (shared netns → localhost), exposed at
+`<name>.<domain>`. The tool repo's only job: a GitHub Actions workflow that builds + pushes to GHCR.
 
 ## Greenlight OCI infra (Terraform, in the wrapper)
 
 `greenlight add/adopt` emits, per oci tool:
-- **`oci-container-instance`** module — the container instance (tool image from GHCR + cloudflared
-  sidecar with the tunnel token), `CI.Standard.A1.Flex` within the free allotment, restart ALWAYS.
-- **`tunnel`** module — cloudflared tunnel + ingress `<name>.<domain> → http://localhost:8000` + token.
-- **`tool`** DNS module — CNAME → the tunnel.
-The `oci` provider (auth below) is added to `infra/main.tf`.
-
-## OCI token CLI
-
-`greenlight secrets gather <tool> --repo <o/r>` pushes the OCI creds straight to GitHub secrets
-(hidden prompts, no disk/logs). **The only manual OCI inputs are the API-key auth values** —
-`TF_VAR_OCI_TENANCY_OCID`, `TF_VAR_OCI_USER_OCID`, `TF_VAR_OCI_FINGERPRINT`, `TF_VAR_OCI_PRIVATE_KEY`
-(PEM), `TF_VAR_OCI_REGION`. `TF_VAR_OCI_COMPARTMENT_ID` is **optional** (blank → the tenancy/root
-compartment). Auth is API-key request signing — no bearer, so no fetch-verify. The container
-instance OCID is **not** a manual input — the deploy workflow resolves it at deploy time from OCI
-by the instance's display name (= the tool name), so it's abstracted from the developer.
-
-**The VCN, subnet, and availability domain are NOT manual** — they're Terraform: the `oci-network`
-module creates the VCN + a public (egress-only) subnet, and the container-instance module looks the
-AD up via an `oci_identity_availability_domains` data source. So the bootstrap is just "create one
-API key" — Terraform can't create the credential it needs to authenticate, but it owns everything
-after that. (Out-of-A1-capacity in one AD? set `availability_domain` on the instance module to pin
-another — the only time you touch it.)
-
-**Shortcut — feed the API-key config preview directly.** After *Add API key*, OCI shows a
-"Configuration file preview" (the `[DEFAULT]` block) and you download the `.pem`. Pass both:
-`greenlight secrets gather <tool> --repo <o/r> --oci-config ~/path/config [--oci-key ~/path/key.pem]`
-— it auto-fills the 5 auth secrets (incl. the multi-line PEM, read from the file so it's never
-pasted) and only prompts for the 3 placement values + the option-B deploy PATs.
+- **`oci-container-instance`** — the container instance (tool image from GHCR + cloudflared sidecar
+  with the tunnel token), `CI.Standard.A1.Flex` within the free allotment, restart ALWAYS.
+- **`tunnel`** — cloudflared tunnel + ingress `<name>.<domain> → http://localhost:8000` + token.
+- **`tool`** DNS — CNAME → the tunnel.
+- The `oci-network` module owns the VCN + public subnet; the instance module looks the AD up via a
+  data source. The `oci` provider is added to `infra/main.tf`.
+
+## Token — OCI API-key auth
+
+Auth values + the gather flow live in
+[tokens-reference.md](https://github.com/RTrentJones/greenlight/blob/main/docs/tokens-reference.md).
+The **only manual OCI inputs are the API-key auth values** (`TF_VAR_OCI_TENANCY_OCID`,
+`TF_VAR_OCI_USER_OCID`, `TF_VAR_OCI_FINGERPRINT`, `TF_VAR_OCI_PRIVATE_KEY` PEM, `TF_VAR_OCI_REGION`;
+`TF_VAR_OCI_COMPARTMENT_ID` optional → root). Auth is API-key request signing (no bearer → no
+fetch-verify). **Shortcut:** `greenlight secrets gather <tool> --repo <o/r> --oci-config ~/config
+[--oci-key ~/key.pem]` auto-fills the 5 auth secrets from OCI's "Configuration file preview" + the
+`.pem` (the multi-line key is read from the file, never pasted).
 
 ## Deploy = restart (re-pull)
 
-`greenlight deploy <tool>` (oci) just runs `oci container-instances container-instance restart
---container-instance-id <OCID>` — the instance re-pulls the latest GHCR image. The tool's CI
-builds; an event trigger (the chosen deploy option) fires the restart. The adapter does NOT build.
-
-## Idle-reclaim — stay free, recover on alert
-
-OCI Always-Free can reclaim idle compute. We **stay on the free tier** and accept that: the
-instance runs restart-policy ALWAYS, keepalive health-checks it, and if it's ever stopped/reclaimed
-the alert fires and a **re-apply / redeploy** restores it. **PAYG is NOT used** — it's an optional
-last resort (see `docs/oci-payg-runbook.md`) only if reclaim ever becomes a recurring problem.
+`greenlight deploy <tool>` (oci) runs `oci container-instances container-instance restart
+--container-instance-id <OCID>` — the instance re-pulls the latest GHCR image. The tool's CI builds;
+the deploy event fires the restart. The adapter does **not** build. The instance OCID is **not** a
+manual input — the deploy workflow resolves it from OCI by display name (= the tool name).
 
 ## Verify
 The tool is typically an **MCP server**: verify with `mode: mcp`, connect at `<name>.<domain>/mcp`
-(FastMCP's `streamable_http_app()` serves `/mcp` by default — the convention). If auth gates
-`initialize`, supply a token or use an `api`-mode 401 check. Keepalive health-checks `target: oci`.
+(FastMCP's `streamable_http_app()` serves `/mcp` by default). If auth gates `initialize`, supply a
+token or use an `api`-mode 401 check. Keepalive health-checks `target: oci`.
+
+## Gotchas
+- **OCIR is paid — use GHCR.** Pulling from OCI's own registry bills; the free path is GHCR.
+- **Idle-reclaim → stay free, recover on alert.** Always-Free can reclaim idle compute. We **stay on
+  the free tier**: restart-policy ALWAYS + keepalive health-check + alert → re-apply/redeploy
+  restores it. **PAYG is NOT used** (optional last resort; see `docs/oci-payg-runbook.md`). Never
+  imply the harness *prevents* reclaim — it only nags and recovers.
+- **Out-of-A1-capacity in one AD** → set `availability_domain` on the instance module to pin another
+  AD (the only time you touch it).
+- **Rotation.** The API signing key is the one long-lived credential — rotate it on a schedule (see
+  docs/security.md); nothing automated rotates it.

package/assets/skills/provider-supabase/SKILL.md

@@ -1,28 +1,29 @@
 ---
 name: provider-supabase
-description: How Supabase works in a Greenlight setup — the `data: supabase` store (Postgres + auth + storage + realtime), single-project-schema-per-env model, the pause trap solved by keepalive, Management API token, and the read-only Supabase MCP. Use when wiring a tool's database, debugging a paused project, or a Supabase apply.
+description: Supabase in a Greenlight setup — the `data: supabase` store (Postgres + auth + storage + realtime), schema-per-env, the 7-day pause trap solved by keepalive. Use when wiring a tool's database, debugging a paused project, or a Supabase apply.
 ---
 
 # provider-supabase
 
 `data: supabase` is for tools that need bundled **auth + storage + realtime** together
-(HeistMind). One Supabase **project**, **schema-per-env** (beta/prod share the project —
-NOT project-per-env; branching is paid). The project is **imported** (not recreated):
-name/region are replace-forcing, so the module sets `ignore_changes` to protect the live DB.
+(HeistMind). One Supabase **project**, **schema-per-env** (beta/prod share the project — NOT
+project-per-env; branching is paid). The project is **imported**, not recreated: name/region are
+replace-forcing, so the module sets `ignore_changes` to protect the live DB.
 
 ## Token — `SUPABASE_ACCESS_TOKEN`
 
-Dashboard → Account → Access Tokens (Management API). Push it straight to GitHub Actions with
-`greenlight secrets gather` (or `gh secret set`) — Greenlight keeps no local secret file.
-`greenlight add` verifies it against `/v1/projects` (HTTP 200). The DB password
-(`TF_VAR_supabase_database_password`) is only used if the project is recreated — ignored on
-import, so `import-placeholder` is fine for an existing project.
+Creation + verify live in
+[tokens-reference.md](https://github.com/RTrentJones/greenlight/blob/main/docs/tokens-reference.md).
+Management API PAT, **account-scoped** (it manages every project in the account — keep it tight).
+Single store: GitHub Actions secrets. The DB password (`TF_VAR_supabase_database_password`) is only
+used if the project is *recreated* — ignored on import, so `import-placeholder` is fine for an
+existing project.
 
 ## Terraform module — `infra/modules/supabase`
 
-Single project, import-safe. Outputs `url`, `anon_key`, `service_role_key`, `project_ref` —
-feed these straight into the consumer (e.g. the Vercel env block). To re-apply from fresh
-state, import first: `terraform import module.<name>_supabase.supabase_project.this <ref>`.
+Single project, import-safe. Outputs `url`, `anon_key`, `service_role_key`, `project_ref` — feed
+these straight into the consumer (e.g. the Vercel env block). To re-apply from fresh state, import
+first: `terraform import module.<name>_supabase.supabase_project.this <ref>`.
 
 ## Keepalive — non-negotiable
 
@@ -32,10 +33,14 @@ Supabase **pauses a free project after ~7 days idle** — this is what takes too
 The ping counts any HTTP response (even 401 on `/rest/v1/`) as alive.
 
 ## MCP
-
 `.mcp.json` wires `supabase` (hosted, **read-only**): needs `SUPABASE_ACCESS_TOKEN` +
 `SUPABASE_PROJECT_REF` in the env (Claude Code expands `${VAR}` in the url/header). Run `/mcp`.
 
-## Rule
-The **blog must never use Supabase** for state (it must stay up unattended) — use D1/KV or
-external services. Supabase is per-tool, only when the bundled features are needed together.
+## Gotchas
+- **The blog must never use Supabase** for state (it must stay up unattended) — use D1/KV or
+  external services. Supabase is per-tool, only when the bundled features are needed together.
+- **Migrations gate.** A supabase tool that owns `supabase/migrations` must run `greenlight
+  migrations scan` in the CI that applies them (before `supabase db push`) — `doctor` flags a
+  migrations dir whose workflows don't.
+- **Forgetting keepalive** is the #1 silent-death cause for a supabase tool — `doctor` does not yet
+  assert it, so wire `targets_json` when you add the tool.