env-vars / knowledge-update skills: document Marketplace Sensitive flag and run-inside-Vercel implication

[sakdbag]

Plugin and version

vercel plugin (filed against vercel:env-vars and vercel:knowledge-update skills).

Observed behaviour

Vercel Marketplace integrations (Supabase, Blob, Resend, similar) write env vars into the project with the Sensitive flag set by default. The flag has three consequences that aren't covered by either skill:

1. vercel env pull cannot retrieve a Sensitive-flagged value. The pulled .env.local ends up with the key but a placeholder value.
2. The Vercel dashboard hides the value behind a passkey re-auth that an agent cannot complete.
3. API/CLI reads return the placeholder, not the real value.

Practical implication: any script that uses a Marketplace-managed secret must run inside Vercel (admin route gated by Bearer auth, a build-time script, or a cron). It cannot run from the operator's laptop with a locally-populated .env.local. A team that doesn't know this writes a local script first, sees the Sensitive flag, then has to refactor the script into an admin route. The refactor adds auth-gating, a Server Action shape, and a deploy round-trip.

Expected behaviour

Both vercel:env-vars and vercel:knowledge-update should mention the Sensitive flag and its run-inside-Vercel implication. A worked example showing the admin-route shape (Bearer + CRON_SECRET, returns JSON, idempotent) would prevent the laptop-script-first detour entirely.

Steps to reproduce

1. Create a Vercel project, install any Marketplace integration that writes env vars (e.g. Supabase).
2. vercel env pull --environment=production .env.production against the project.
3. Inspect the pulled file: the Marketplace-injected secrets show placeholder values, not real ones.
4. Try to read the value via vercel env API: same placeholder.
5. Try to write a Node script using the real secret from .env.local: fails to authenticate against the underlying service.
6. The only viable path is to run the script inside Vercel's runtime where the real secret is injected.

Workaround

Skip the local-script step entirely on any task that touches Marketplace-managed secrets. Write the admin route first, deploy, invoke via cron or a one-shot POST with Bearer.

Context

Surfaced during a third-party-API end-to-end buildout that initially used a local launch script. Local script failed because it needed a Marketplace-injected secret. Refactored into a gated admin route in the same session.