vybekiit 0.7.28 → 0.7.32

package/dist/global-skills/sign-in-with-phone/SKILL.md

@@ -5,6 +5,12 @@ metadata:
   vybekiit-generated: buyer-skill-stub
 ---
 
+Prefer the current project instructions and matching project skill when inside a kit app.
+Outside a kit app, resolve guidance relative to this skill directory: ../vybekiitReferences/web/.
+That folder contains language.md, AGENTS.md, CODE-STYLE.md, agent/ and platform-skills/.
+Bare wrapper filenames refer to platform-skills/ there. Do not assume project code or recipe files exist globally.
+Inspect an existing app before changing it. Scaffold a new kit app only when the builder asked for a new app.
+
 <!-- vybekiit:generated:buyer-skill-stub -->
 
 # Skill: sign-in-with-phone
@@ -19,15 +25,13 @@ metadata:
 ## Steps
 
 <!-- vybekiit:page-recipe-install -->
-0. **Install / extend the auth page recipe first (catalog SSOT — Option C).**
-   Copy or extend `apps/componentLibrary/src/pageRecipes/AuthPage.tsx` export `AuthPage` at route `/login`
-   with phone + code UI. Recipe id: `auth`. Preset: auth-bridge.
-   Keep every `TODO:` in the recipe and wire each one after the route renders.
-   Also reference `packages/agentKit` `getPageRecipeInstall('sign-in-with-phone')` / page-recipe-manifest.json.
-   **Verify:** `/login` shows practice phone sign-in UI before provider wiring.
+0. **Add the ready-made sign-in page first.** Run `vybekiit add page-recipe auth`. It adds the page
+   at `/login` (if the app already has a sign-in page, it is kept). Then add a phone number and code form to it.
+   Keep every `TODO:` in the page and fill each one in as you connect the real service.
+   **Verify:** `/login` opens and shows a phone number and code form with practice content.
 
 1. **Run `setup-sms` first** if Twilio secret settings are not filled in.
-   **Verify:** `NOTIFICATIONS_PROVIDER=twilio` and Twilio keys in `.env`.
+   **Verify:** `NOTIFICATIONS_PROVIDER=twilio` in `settings.env` and `TWILIO_AUTH_TOKEN` in `.env`.
 
 2. **Add phone + code UI** on login → send code, then verify.
    **Verify:** practice mode accepts code `000000` with empty Twilio settings.

package/dist/global-skills/stripe-best-practices/SKILL.md

@@ -14,9 +14,10 @@ description: >-
   processing payments, setting up subscriptions, collecting sales tax, VAT, or
   GST, creating connected accounts, or implementing secure key handling.
 
+disable-model-invocation: true
 ---
 
-Latest Stripe API version: **2026-08-26.dahlia**. Always use the latest API version and SDK unless the user specifies otherwise.
+Latest Stripe API version: **2026-09-30.endive**. Always use the latest API version and SDK unless the user specifies otherwise.
 
 Development and testing environment default: For new integration development, use separate [sandboxes](https://docs.stripe.com/sandboxes.md) instead of the account’s shared test mode sandbox. Sandboxes isolate settings and test data from live mode. Use separate sandboxes for local development and CI. When stronger isolation is useful, dedicate sandboxes to development teams or testing scenarios. Use the shared test mode sandbox only for an existing integration that depends on it or when a required feature doesn’t support general sandboxes.
 

package/dist/global-skills/stripe-best-practices/references/billing.md

@@ -55,6 +55,8 @@ For a flat or per-seat fee plus usage, keep the fee on the existing Stripe Subsc
 ## Traps to avoid
 
 - Don’t call a subscription integration complete without a webhook handler for the subscription lifecycle events (`customer.subscription.*`, `invoice.paid`, `invoice.payment_failed`). Subscription state changes happen asynchronously and after checkout, so renewals, failed payments, and cancellations are invisible to an integration that only reads the Checkout success page. Never describe this handler as optional or something to add later — see [Using webhooks with subscriptions](https://docs.stripe.com/billing/subscriptions/webhooks.md).
+- Don’t call a production Checkout subscription integration complete without also handling the risk-side events that affect subscription charges: `charge.dispute.created`, `charge.refunded`, and `radar.early_fraud_warning.created`. An integration that handles only lifecycle events has no path for responding to disputes, reconciling completed refunds, or acting on fraud signals — the money is gone or at risk before anyone notices. Subscribe to these events and use the version-appropriate object graph to resolve the affected Subscription; see [Handle refund, dispute, and early fraud warning events](https://docs.stripe.com/billing/subscriptions/webhooks.md#refund-events). Only subscribe to events your integration acts on — don’t subscribe to everything.
+- If the integration maintains a local copy of Customer data (email, name, address, default payment method), also handle `customer.updated` so local records stay in sync. For Accounts v2 integrations, the equivalents are `v2.core.account[configuration.customer].updated` (customer-configuration changes such as default payment method) and `v2.core.account[identity].updated` (billing address and identity fields). See [Accounts v2 webhooks](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md#accounts-v2-webhooks). Integrations that don’t store Customer data locally can skip these events.
 - Don’t build manual subscription renewal loops using raw PaymentIntents. Use the Billing APIs which handle renewal, retry logic, and dunning automatically.
 - Don’t use the deprecated `plan` object. Use [Prices](https://docs.stripe.com/api/prices.md) instead.
 - Don’t put prices for different tiers or plans on a single product. Instead, create one Product for each plan a customer can choose. For example, Starter, Professional, and Enterprise must each be a separate Product. Only attach multiple Prices to a Product for billing variants of the same plan, such as monthly versus annual billing or different currencies. Avoid placing Prices for different tiers on a single Product. Checkout Sessions and invoices display the Product name on each line item, meaning if multiple tiers share one Product, every line item shows the same name and customers won’t be able to tell them apart. For more information, see [Model your product catalog](https://docs.stripe.com/products-prices/how-products-and-prices-work.md#model-your-catalog).

package/dist/global-skills/stripe-best-practices/references/payments.md

@@ -50,7 +50,7 @@ Handle both `checkout.session.completed` and `checkout.session.async_payment_suc
 
 Webhooks are **required**, not optional, for:
 
-- Subscriptions and any recurring billing, where most state changes (renewals, payment failures, cancellations) happen after checkout. Read the Billing skill reference for the lifecycle events to handle.
+- Subscriptions and any recurring billing, where renewals, payment failures, cancellations, and risk events such as disputes, refunds, and fraud signals happen asynchronously after checkout. Read the Billing skill reference for the full set of events to handle, including risk-side events.
 - Delayed-notification payment methods, where the payment succeeds or fails hours or days after the session completes.
 - Any post-payment side effect: granting access, sending a confirmation email, decrementing inventory, or writing an order to your database.
 

package/dist/global-skills/stripe-best-practices/references/tax.md

@@ -20,7 +20,7 @@
 
 ## What Stripe Tax does and doesn’t do
 
-**What Stripe Tax does:** tax calculation, nexus threshold monitoring (Dashboard → Tax → Locations → “Needs attention” and email alerts), registration on the user’s behalf for eligible US remote sellers (“Register for me”; see [Registration safety](https://docs.stripe.com/undefined.md#registration-safety)), and filing through [TaxJar](https://docs.stripe.com/tax/file-with-stripe.md) or [a filing partner](https://docs.stripe.com/tax/filing.md), where available.
+**What Stripe Tax does:** tax calculation, nexus threshold monitoring (Dashboard → Tax → Locations → “Needs attention” and email alerts), registration on the user’s behalf for eligible US remote sellers (“Register for me”; see Registration safety), and filing through [TaxJar](https://docs.stripe.com/tax/file-with-stripe.md) or [a filing partner](https://docs.stripe.com/tax/filing.md), where available.
 
 **What Stripe Tax doesn’t do:** process payments that happen outside Stripe, automatically file every tax return, or support every jurisdiction (check the [supported countries list](https://docs.stripe.com/tax/supported-countries.md) for current coverage). For off-Stripe payments, the [standalone Tax APIs](https://docs.stripe.com/tax/off-stripe.md) can calculate tax and record transactions for reporting and filing.
 
@@ -127,7 +127,7 @@ Threshold monitoring only processes live-mode transactions, not sandbox payments
 
 Guide, don’t advise. Never tell a user where they must register or whether they’re legally obligated. Recommend they consult their tax advisor to determine their obligations.
 
-- The [Tax Registrations API](https://docs.stripe.com/api/tax/registrations.md) can list, create, update, and expire registrations (set `expires_at` to expire; there’s no delete). A scheduled expiry can be changed, but an expiration that has taken effect is permanent (to collect again, the user adds a new registration), and there’s no pause. A head office address is required before adding a registration.
+- The [Tax Registrations API](https://docs.stripe.com/api/tax/registrations.md) can list, create, update, and expire registrations (set `expires_at` to expire; there’s no delete). A scheduled expiration can be changed, but an expiration that has taken effect is permanent (to collect again, the user adds a new registration), and there’s no pause. A head office address is required before adding a registration.
 - Adding a registration in Stripe records where the user is *already* registered. It doesn’t register them with the tax authority.
 - Creating or expiring a registration changes whether Stripe collects tax in that jurisdiction, but it doesn’t register or deregister the user with the tax authority. The user must do that separately. Prepare the change and have the user confirm it; never create or expire a registration automatically.
 

package/dist/global-skills/supabase/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.1.9](https://github.com/supabase/agent-skills/compare/v0.1.8...supabase-v0.1.9) (2026-09-28)
+
+
+### Bug Fixes
+
+* **supabase:** recommend scoped personal access tokens for the Management API, CLI, and MCP ([#604](https://github.com/supabase/agent-skills/issues/604)) ([551274e](https://github.com/supabase/agent-skills/commit/551274ed2fe97c8fea1325f7ceb05803a542f8df))
+
+## [0.1.8](https://github.com/supabase/agent-skills/compare/v0.1.7...supabase-v0.1.8) (2026-09-24)
+
+
+### Features
+
+* **supabase:** add debugging workflows to the supabase skill ([#112](https://github.com/supabase/agent-skills/issues/112)) ([3a4f0ce](https://github.com/supabase/agent-skills/commit/3a4f0ce0782e0cbdcf187c362e8d15d9e324462b))
+
+
+### Bug Fixes
+
+* **supabase:** recommend scoped personal access tokens for the Management API, CLI, and MCP ([#604](https://github.com/supabase/agent-skills/issues/604)) ([551274e](https://github.com/supabase/agent-skills/commit/551274ed2fe97c8fea1325f7ceb05803a542f8df))
+
 ## [0.1.7](https://github.com/supabase/agent-skills/compare/v0.1.6...supabase-v0.1.7) (2026-08-12)
 
 

package/dist/global-skills/supabase/SKILL.md

@@ -4,6 +4,7 @@ description: "Use when doing ANY task involving Supabase. Triggers: Supabase pro
 metadata:
   author: supabase
   version: "0.1.2"
+disable-model-invocation: true
 ---
 
 # Supabase

package/dist/global-skills/supabase-postgres-best-practices/SKILL.md

@@ -8,6 +8,7 @@ metadata:
   organization: Supabase
   date: January 2026
   abstract: Comprehensive Postgres performance optimization guide for developers using Supabase and Postgres. Contains performance rules across 8 categories, prioritized by impact from critical (query performance, connection management) to incremental (advanced features). Each rule includes detailed explanations, incorrect vs. correct SQL examples, query plan analysis, and specific performance metrics to guide automated optimization and code generation.
+disable-model-invocation: true
 ---
 
 # Supabase Postgres Best Practices

package/dist/global-skills/track-errors/SKILL.md

@@ -5,6 +5,12 @@ metadata:
   vybekiit-generated: buyer-skill-stub
 ---
 
+Prefer the current project instructions and matching project skill when inside a kit app.
+Outside a kit app, resolve guidance relative to this skill directory: ../vybekiitReferences/web/.
+That folder contains language.md, AGENTS.md, CODE-STYLE.md, agent/ and platform-skills/.
+Bare wrapper filenames refer to platform-skills/ there. Do not assume project code or recipe files exist globally.
+Inspect an existing app before changing it. Scaffold a new kit app only when the builder asked for a new app.
+
 <!-- vybekiit:generated:buyer-skill-stub -->
 
 # Skill: track-errors
@@ -21,23 +27,22 @@ translate every error · celebrate. You set up alerts; the builder only pastes o
 ## Steps
 
 <!-- vybekiit:page-recipe-install -->
-0. **Install the page recipe first (catalog SSOT — Option C).**
-   Copy `apps/componentLibrary/src/pageRecipes/SystemHealthPage.tsx` export `SystemHealthPage` into the buyer app at route `/admin/health`.
-   Recipe id: `system-health`. Presets: none.
-   Keep every `TODO:` in the recipe and wire each one after the route renders.
-   Also reference `packages/agentKit` `getPageRecipeInstall('track-errors')` / page-recipe-manifest.json.
-   **Verify:** route builds and shows practice UI before provider wiring.
-
+0. **Add the ready-made page first.** Run `vybekiit add page-recipe system-health`. It adds the page
+   at `/admin/health` and lists any data setup to run next. Keep every `TODO:` in the page and fill
+   each one in as you connect the real service.
+   **Verify:** `/admin/health` opens and shows practice content.
 
 1. **Explain in one line.** *"I'm going to set up alerts so you know when something breaks in your live app."*
 
-2. **Create or open the alert project.** Sign in to the error-tracking dashboard (Sentry free tier) and
-   create a project for this app. Copy the **DSN** (connection string) from project settings.
-   **Verify:** you have a DSN ready — do not paste it in chat.
+2. **Create or open the alert project.** Ask the builder to run `vybekiit-automate sentry setup` in
+   their own terminal. It asks for a Sentry auth token with hidden typing, checks it, and saves
+   `SENTRY_AUTH_TOKEN` to `.env`. With that token, create a project for this app through the Sentry
+   API (free tier) and read its **DSN** (connection string).
+   **Verify:** you have a DSN ready. Never paste it in chat.
 
-3. **Wire it in.** Set in `.env`:
+3. **Wire it in.** Set in `settings.env`:
    - `OBSERVABILITY_PROVIDER="sentry"`
-   - `SENTRY_DSN="<paste from dashboard>"`
+   - `SENTRY_DSN="<DSN from step 2>"`
    Confirm `instrumentation.ts` and `src/lib/observability.ts` exist and import `@vybekiit/observability`.
    **Verify:** app builds; provider resolves without error.
 
@@ -53,7 +58,7 @@ translate every error · celebrate. You set up alerts; the builder only pastes o
 
 ## If anything breaks
 
-Run `doctor`. Most failures are a missing or wrong DSN — re-copy from the dashboard into `.env` only
+Run `doctor`. Most failures are a missing or wrong DSN — re-copy from the dashboard into `settings.env` only
 (never chat). If MCP fails once, run `vybekiit doc-fallback sentry`.
 
 ## Definition of done

package/dist/global-skills/update-kit/SKILL.md

@@ -5,6 +5,12 @@ metadata:
   vybekiit-generated: buyer-skill-stub
 ---
 
+Prefer the current project instructions and matching project skill when inside a kit app.
+Outside a kit app, resolve guidance relative to this skill directory: ../vybekiitReferences/web/.
+That folder contains language.md, AGENTS.md, CODE-STYLE.md, agent/ and platform-skills/.
+Bare wrapper filenames refer to platform-skills/ there. Do not assume project code or recipe files exist globally.
+Inspect an existing app before changing it. Scaffold a new kit app only when the builder asked for a new app.
+
 <!-- vybekiit:generated:buyer-skill-stub -->
 
 # Skill: update-kit
@@ -17,7 +23,7 @@ translate every error · celebrate. You do the whole update; the builder just wa
 > (Under the hood — agent-only) Updates run through **three channels** inside this one skill:
 > npm package bumps (`@vybekiit/*`), agent-layer refresh from the template mirror, and platform
 > instruction files pinned in `.agents/skills/`. The builder's own app code is never touched — only
-> maintained kit files listed in ADR-0007. Use `planKitUpdate()` from `@vybekiit/agent-kit` for
+> maintained kit files. Use `planKitUpdate()` from `@vybekiit/agent-kit` for
 > channel 1; `vybekiit sync-agent-layer` for channel 2; `npx skills update -y` for channel 3 when
 > `skills-lock.json` exists.
 

package/dist/global-skills/upgrading-expo/SKILL.md

@@ -3,6 +3,7 @@ name: upgrading-expo
 description: Guidelines for upgrading Expo SDK versions and fixing dependency issues
 version: 1.0.0
 license: MIT
+disable-model-invocation: true
 ---
 
 ## References

package/dist/global-skills/use-dom/SKILL.md

@@ -3,6 +3,7 @@ name: use-dom
 description: Use Expo DOM components to run web code in a webview on native and as-is on web. Migrate web code to native incrementally.
 version: 1.0.0
 license: MIT
+disable-model-invocation: true
 ---
 
 ## What are DOM Components?

package/dist/global-skills/use-railway/SKILL.md

@@ -18,6 +18,7 @@ description: >
   `railway up` flow (deploys + signs up on the fly) or `railway login`
   (which creates new accounts on the fly).
 allowed-tools: Bash(railway:*), Bash(which:*), Bash(command:*), Bash(npm:*), Bash(npx:*), Bash(curl:*), Bash(python3:*)
+disable-model-invocation: true
 ---
 
 # Use Railway
@@ -104,7 +105,7 @@ Before any mutation, verify the tool path and context:
 
 ```bash
 command -v railway                # CLI installed
-RAILWAY_CALLER="skill:use-railway@1.5.5" RAILWAY_AGENT_SESSION="railway-skill-$(date +%s)-$$" railway whoami --json
+RAILWAY_CALLER="skill:use-railway@1.6.1" RAILWAY_AGENT_SESSION="railway-skill-$(date +%s)-$$" railway whoami --json
 railway --version                 # check CLI version
 ```
 
@@ -128,7 +129,7 @@ Check once per session and don't re-run it after acting; the restart prompt to t
 
 When Railway MCP is available and the job is a platform-state read, use the matching MCP read instead of shelling out. If using the CLI path, run the CLI checks above.
 
-For Railway CLI calls made while this skill is active, prefix the command with `RAILWAY_CALLER=skill:use-railway@1.5.5` and a stable `RAILWAY_AGENT_SESSION` reused for the current user request. Generate the session id once per user request, then reuse that exact value for later Railway CLI calls in the same workflow. Do not run a separate `export` preflight solely for telemetry; inline env prefixes keep the shell output concise and avoid leaking setup steps into every response.
+For Railway CLI calls made while this skill is active, prefix the command with `RAILWAY_CALLER=skill:use-railway@1.6.1` and a stable `RAILWAY_AGENT_SESSION` reused for the current user request. Generate the session id once per user request, then reuse that exact value for later Railway CLI calls in the same workflow. Do not run a separate `export` preflight solely for telemetry; inline env prefixes keep the shell output concise and avoid leaking setup steps into every response.
 
 **Context resolution - URL IDs always win:**
 - If the user provides a Railway URL, extract IDs from it. Do NOT run `railway status --json`; it returns the locally linked project, which is usually unrelated.
@@ -294,14 +295,14 @@ For anything beyond quick operations, load the references needed for the user's
 | **Analyze a database** ("analyze \<url\>", "analyze db", "analyze database", "analyze service", "introspect", "check my postgres/redis/mysql/mongo") | [analyze-db.md](references/analyze-db.md) | Database introspection and performance analysis. analyze-db.md directs you to the DB-specific reference. **This takes priority over the status/operate routes when a Railway URL to a database service is provided alongside "analyze".** |
 | Create or connect resources | [setup.md](references/setup.md) | Projects, services, databases, buckets, templates, workspaces |
 | Ship code or manage releases | [deploy.md](references/deploy.md) | Deploy, redeploy, restart, build config, monorepo, Dockerfile |
-| Change configuration | [configure.md](references/configure.md) | Environments, variables, config patches, domains, networking |
+| Change configuration ("webhook", "notify on deploy", "custom header", "Slack/Discord notifications") | [configure.md](references/configure.md) | Environments, variables, config patches, domains, networking, project webhooks with the `list-webhooks` / `create-webhook` / `update-webhook` / `test-webhook` / `delete-webhook` MCP tools and their custom headers |
 | Manage feature flags | [feature-flags.md](references/feature-flags.md) | MCP registry operations; CLI targeting rules and rollouts; SDK runtime reads |
 | Define configuration in source control ("IaC", "infrastructure as code", "config as code", `.railway/railway.ts`, `.railway/railway.py`, `.railway/railway.go`, "config migrate/plan/apply/pull") | [iac.md](references/iac.md) | Author/import IaC, migrate legacy JSON/TOML, save and apply reviewed plans, check drift |
 | Manage databases ("PITR", "restore", "backup", "HA", "failover", "switchover", "PgBouncer", "connection pooling") | [databases.md](references/databases.md) | Postgres recovery, HA and pooling; MySQL/Redis HA; use analysis references for performance investigations |
 | Inspect costs or manage spending limits | [usage.md](references/usage.md) | Workspace/project/service usage, billing periods, workspace and Railway Agent limits |
 | Run a coding agent on Railway ("cloud agent", "railway ca", "railway code", "desktop SSH") | [cloud-agents.md](references/cloud-agents.md) | Provision, connect, wake, sleep, delete, or configure desktop access to cloud agent VMs |
 | Check health or debug failures | [operate.md](references/operate.md) | Status, logs, metrics, build/runtime triage, recovery |
-| Trace requests across services ("tracing", "traces", "trace ID", "spans", "OpenTelemetry", "OTel", "OTLP", "instrument my app", "instrument my function", "Bun function", "auto-instrumentation") | [tracing.md](references/tracing.md) | Enable tracing per project or service with the `get-tracing` / `set-service-tracing` / `set-project-tracing` MCP tools or `railway trace enable`, SDK instrumentation (preferred) vs automatic (eBPF), what to instrument, instrumenting a Function (Bun), the provided `OTEL_*` variables, sampling, reading traces with the `list-traces` / `get-trace` MCP tools or `railway trace list` / `get`, the Traces tab |
+| Trace requests across services ("tracing", "traces", "trace ID", "spans", "OpenTelemetry", "OTel", "OTLP", "instrument my app", "instrument my function", "Bun function", "auto-instrumentation") | [tracing.md](references/tracing.md) | Enable tracing per service and environment with the `get-tracing` / `set-service-tracing` MCP tools or `railway trace enable`, the IaC `tracing` block and its current SDK limitation, SDK instrumentation (preferred) vs automatic (eBPF), what to instrument, instrumenting a Function (Bun), the provided `OTEL_*` variables, sampling, reading traces with the `list-traces` / `get-trace` MCP tools or `railway trace list` / `get`, checking what a service's instrumentation covers with `get-tracing-coverage`, the Traces tab |
 | Use a sandbox or build remotely ("sandbox", "scratch environment", "ephemeral box", "build remotely", "remote build", "run this remotely", "checkpoint", "snapshot/save/restore sandbox state") | [sandbox.md](references/sandbox.md) | Create/fork sandboxes, run commands remotely, remote template builds, checkpoints (save/restore sandbox state), port forwarding, teardown. Requires Sandboxes enabled in Priority Boarding — if unavailable, prompt the user to enable it. |
 | Request from API, docs, or community | [request.md](references/request.md) | Railway GraphQL API queries/mutations, metrics queries, Central Station, official docs |
 
@@ -346,7 +347,7 @@ Multi-step workflows follow natural chains:
 - **First deploy**: setup (create project + service), configure (set variables and source), deploy, operate (verify healthy)
 - **Fix a failure**: operate (triage logs), configure (fix config/variables), deploy (redeploy), operate (verify recovery)
 - **Add a domain**: configure (add domain + set port), operate (verify DNS and service health)
-- **Add tracing**: tracing (enable for the project or service with `set-project-tracing` / `set-service-tracing` or `railway trace enable`, prefer SDK instrumentation over automatic, add spans around inbound work, I/O and logical units; for a Function, edit its file with `get-function-source-code` / `update-function-source-code`), configure (set `OTEL_METRICS_EXPORTER`/`OTEL_LOGS_EXPORTER`, start command), deploy (redeploy so the `OTEL_*` variables land), tracing (verify with `x-railway-trace-id` and `get-trace` or `railway trace get`)
+- **Add tracing**: tracing (enable for the service in the right environment with `set-service-tracing` or `railway trace enable`, prefer SDK instrumentation over automatic, add spans around inbound work, I/O and logical units; for a Function, edit its file with `get-function-source-code` / `update-function-source-code`), configure (set `OTEL_METRICS_EXPORTER`/`OTEL_LOGS_EXPORTER`, start command), deploy (redeploy so the `OTEL_*` variables land), tracing (verify with `x-railway-trace-id` and `get-trace` or `railway trace get`, then `get-tracing-coverage` for the database and client spans)
 - **Docs to action**: request (fetch docs answer), route to the relevant operational reference
 
 When composing, return one unified response covering all steps. Don't ask the user to invoke each step separately.

package/dist/global-skills/use-railway/references/configure.md

@@ -278,6 +278,36 @@ railway domain delete example.com --service <service> --yes --json
 
 Domain deletion is destructive. Confirm the domain and service before running it.
 
+## Webhooks
+
+Project webhooks POST a JSON payload to a URL whenever a chosen deployment, monitor, or volume-alert event happens anywhere in the project. They are project-scoped, not per service or environment, and are managed with five MCP tools. There is no `railway webhook` CLI command. Resolve the project ID from `railway status --json` or `list-projects` first.
+
+| Tool | Purpose |
+|---|---|
+| `list-webhooks` | Every webhook in the project: URL, `eventTypes`, `includePreviewEnvironments`, the names of its custom headers (`headerNames`), and the `id` the other tools take |
+| `create-webhook` | `url` plus optional `eventTypes` (defaults to `Deployment.failed`, `Deployment.crashed`, `Deployment.oom_killed`), `includePreviewEnvironments` (defaults to `true`), and `headers` |
+| `update-webhook` | `webhookId` plus any of `url`, `eventTypes`, `includePreviewEnvironments`, `headers`. Only the fields passed change; `eventTypes` and `headers` each replace the whole set |
+| `test-webhook` | POST a sample event and report the HTTP status. Pass `url` (and optional `headers`) to try a new endpoint, or `webhookId` to send to an existing webhook with its stored URL and headers. Nothing is stored |
+| `delete-webhook` | Remove a webhook by `webhookId`. Destructive; confirm the URL with the user first |
+
+Discord and Slack incoming-webhook URLs are detected and receive a formatted message instead of the raw JSON. Run `test-webhook` before `create-webhook`: Railway treats anything outside `2xx`/`3xx` as a failed delivery, and a dead endpoint is paused for 24 hours after repeated failures.
+
+```text
+Create webhook for project <project-id>: url https://hooks.example.com/railway, eventTypes Deployment.failed Deployment.crashed, headers { "Authorization": "Bearer <token>" }
+```
+
+### Custom headers
+
+A webhook can carry up to 20 custom HTTP headers, sent with every delivery and with `test-webhook`. Use them for whatever the receiver needs to trust or route the request: an `Authorization` bearer token, an API key, a shared secret the receiver compares, a routing header. This replaces the old advice of hiding a secret in the URL, which still works but leaks into logs more easily.
+
+- **Values are write-only.** They are encrypted at rest and never returned: `list-webhooks` and every other tool's output carry `headerNames` only. Keep the value in the user's secret store; Railway cannot show it again.
+- **`create-webhook` and `test-webhook`** take `headers` as a name-to-value map.
+- **`update-webhook` replaces the whole set.** Every header not listed is removed and `{}` clears them all. A `null` value keeps the stored value for that name, so a secret survives a change without being resent: `{ "Authorization": null, "X-Env": "prod" }` keeps the token and sets `X-Env`. A URL-only update carries the stored headers forward automatically.
+- **`test-webhook` with `webhookId`** sends the stored headers; any `headers` passed alongside override the stored one of the same name and the rest are still sent. Headers are validated before the request goes out, so a bad name gets a clear error instead of a `0` status.
+- **Name rules.** RFC 9110 token characters, up to 128 characters; values up to 4096 characters with no CR or LF. `Host`, `Content-Type`, `Content-Length` and the hop-by-hop headers (`Transfer-Encoding`, `Connection`, `Keep-Alive`, `Upgrade`, `TE`, `Trailer`, `Expect`) are refused, as is any name starting with `proxy-` or `x-railway-`. Two names differing only by case count as a duplicate. The dashboard form applies the same rules inline and disables Save until a bad row is fixed.
+
+Without MCP, the same fields are on the GraphQL API: `headers` inside the webhook channel config of `notificationRuleCreate` / `notificationRuleUpdate` (a `null` value keeps the stored one there too), and `webhookTest(url, payload, headers: [WebhookHeaderInput!], notificationRuleId)`. Inspect them with `railway api describe`.
+
 ## Networking commands
 
 ### Private networking
@@ -365,10 +395,13 @@ While active, browser visitors must pass a check. Non-browser API clients and we
 - **Outbound allowlist still sees old IPs**: redeploy after enabling/disabling Static Outbound IPs
 - **IPv6 still disabled**: commit the staged environment change and wait for redeploy
 - **CDN appears ineffective**: check `x-cache`, `age`, cache headers, `Set-Cookie`, `Authorization`, method, and response size
+- **Webhook header rejected**: the name is reserved (`Host`, `Content-Type`, `Content-Length`, hop-by-hop), starts with `proxy-` or `x-railway-`, duplicates another name ignoring case, or the value has a newline; rename it or drop it, and stay under 20 headers
+- **Webhook headers disappeared after an update**: `update-webhook` replaces the whole `headers` set, so a map without a name removes it; pass `null` for names to keep, or omit `headers` entirely
 - **WAF breaks API clients**: Under Attack Mode blocks non-browser traffic; disable it or scope protection to browser-facing services
 - **Multi-region patch ignored**: verify region names match the exact identifiers (`us-west2`, `us-east4-eqdc4a`, `europe-west4-drams3a`, `asia-southeast1-eqsg3a`)
 
 ## Validated against
 
-- Docs: [environment.md](https://docs.railway.com/cli/environment), [variable.md](https://docs.railway.com/cli/variable), [domain.md](https://docs.railway.com/cli/domain), [tcp-proxy.md](https://docs.railway.com/cli/tcp-proxy), [private-network.md](https://docs.railway.com/cli/private-network), [outbound-network.md](https://docs.railway.com/cli/outbound-network), [cdn.md](https://docs.railway.com/cli/cdn), [waf.md](https://docs.railway.com/cli/waf)
+- Docs: [environment.md](https://docs.railway.com/cli/environment), [variable.md](https://docs.railway.com/cli/variable), [domain.md](https://docs.railway.com/cli/domain), [tcp-proxy.md](https://docs.railway.com/cli/tcp-proxy), [private-network.md](https://docs.railway.com/cli/private-network), [outbound-network.md](https://docs.railway.com/cli/outbound-network), [cdn.md](https://docs.railway.com/cli/cdn), [waf.md](https://docs.railway.com/cli/waf), [webhooks.md](https://docs.railway.com/observability/webhooks)
+- Platform source (railwayapp/mono): `packages/backboard/src/handlers/http/routes/mcp/tools/webhooks.ts` (webhook MCP tools), `packages/backboard/src/controllers/notifications/validation.ts` (`validateWebhookHeaders`), `packages/backboard/src/graphql/v2/schema/schema.graphql` (`webhookTest`, `WebhookHeaderInput`)
 - CLI source: [environment/mod.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/environment/mod.rs), [environment/edit.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/environment/edit.rs), [variable.rs](https://github.com/railwayapp/cli/blob/v5.49.1/src/commands/variable.rs), [domain.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/domain.rs), [tcp_proxy.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/tcp_proxy.rs), [private_network.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/private_network.rs), [outbound_networking.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/outbound_networking.rs), [cdn.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/cdn.rs), [waf.rs](https://github.com/railwayapp/cli/blob/v5.23.3/src/commands/waf.rs)

package/dist/global-skills/use-railway/references/iac.md

@@ -113,6 +113,8 @@ const media = bucket("media", { region: "iad" });
 const backend = group("Backend", [api, worker, db]);
 ```
 
+A traced service also carries `tracing: { enabled: true, autoInstrumentation: true }`, which `config pull` renders but the `service()` helper does not pass through yet; see [Infrastructure as code in tracing.md](tracing.md#infrastructure-as-code) before applying a plan that touches `tracing`.
+
 Advanced placement can map regions to replica counts:
 
 ```ts