@sentry/junior-vercel 0.222.0 → 0.224.0

package/README.md

@@ -1,6 +1,6 @@
 # @sentry/junior-vercel
 
-`@sentry/junior-vercel` adds read-only Vercel deployment and log investigation workflows through the Vercel CLI. Signed Vercel webhooks can also notify an existing Junior conversation when a deployment succeeds, fails, or is canceled.
+`@sentry/junior-vercel` adds Vercel deployment and alias tools, plus CLI workflows for deployment and log investigation. Signed Vercel webhooks can also notify an existing Junior conversation when a deployment succeeds, fails, or is canceled.
 
 ## Install
 
@@ -31,7 +31,7 @@ Set a Vercel token in the Junior deployment environment:
 JUNIOR_VERCEL_TOKEN=...
 ```
 
-Use a Vercel service account or token with the smallest project/team access that covers the deployments users need to inspect.
+Use a Vercel service account or token with access to the required projects and actions. The same token handles reads and writes.
 
 ## Optional deployment webhooks
 
@@ -71,15 +71,36 @@ jr-rpc config set vercel.team sentry
 
 These defaults are optional fallbacks. If a user names a different project, team, deployment, or URL in a request, Junior should follow the explicit request instead.
 
-## Read-only scope
+## Deployment and alias tools
 
-The bundled skill limits Junior to:
+`vercelPlugin()` registers:
 
-- `vercel logs`
-- `vercel inspect`
-- `vercel list` / `vercel ls`
-- Vercel CLI help commands
+- `vercel_deploymentCreate`: deploy a branch, tag, or commit from an existing
+  project's linked GitHub repository. Preview is the default; Production is an
+  explicit target. An optional full commit SHA pins the source while preserving
+  branch context for Vercel integrations.
+- `vercel_deploymentInspect`: inspect an ID or hostname and return deployment
+  identity, state, environment, and source when available.
+- `vercel_aliasAssign`: assign a hostname to an exact deployment ID and read
+  back the alias. `matches` is false if it no longer points at that deployment.
+- `vercel_aliasInspect`: return the alias's deployment ID or redirect.
+- `vercel_deploymentDelete`: delete an exact deployment ID when requested.
 
-It is intended for deployment status, build-log, runtime-log, and failed-deployment investigations. It is not for deploys, rollbacks, env vars, domains, caches, storage, aliases, or other Vercel mutations.
+Tools use the host-managed token and normal Guardian review. Vercel permissions
+still apply.
+
+Tools return selected fields, not full deployment records that may contain
+secrets. Creates start a build; inspect readiness before using the deployment.
+Check provider state before retrying a write whose response was lost.
+
+Use the Vercel CLI for logs, local source uploads, and other operations not
+covered by the tools.
+
+## Limits
+
+Alias checks are not locks. Moving an alias does not stop older workers or
+identify which build handled a delayed event. Builds inherit project settings
+and credentials and may run migrations. The plugin does not isolate databases
+or other state. Preview deployments do not run Vercel Cron.
 
 Full setup guide: https://junior.sentry.dev/extend/vercel-plugin/

package/dist/index.js

@@ -10,6 +10,267 @@ import {
 import {
   defineJuniorPlugin
 } from "@sentry/junior-plugin-api";
+
+// src/tools/actions.ts
+import {
+  definePluginTool,
+  PluginToolInputError,
+  pluginToolOutputSchema
+} from "@sentry/junior-plugin-api";
+import { z } from "zod";
+var text = z.string().trim().min(1);
+var team = text.describe(
+  "Vercel team slug or team_ ID. Omit for the token's default account."
+).optional();
+var deploymentId = z.string().regex(/^dpl_[a-zA-Z0-9]+$/).describe("Exact Vercel deployment ID, not an alias.");
+var aliasName = z.string().regex(/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?\.[a-z]{2,}$/).describe("Alias hostname without a scheme or path.");
+var deploymentSchema = z.object({
+  id: text,
+  url: text,
+  readyState: text,
+  target: z.string().nullable().optional(),
+  projectId: text.optional(),
+  gitSource: z.object({ sha: text.optional(), ref: text.optional() }).nullable().optional()
+});
+var deploymentOutput = pluginToolOutputSchema.extend({
+  target: z.literal("deployment"),
+  deploymentId: text,
+  url: text,
+  state: text,
+  deploymentTarget: z.string().nullable(),
+  projectId: text.nullable(),
+  commitSha: text.nullable(),
+  ref: text.nullable()
+});
+var aliasSchema = z.object({
+  alias: text,
+  deploymentId: text.nullable(),
+  redirect: text.nullable().optional()
+});
+var aliasOutput = pluginToolOutputSchema.extend({
+  target: z.literal("alias"),
+  alias: text,
+  deploymentId: text.nullable(),
+  redirect: text.nullable()
+});
+function deploymentResult(data) {
+  const value = deploymentSchema.parse(data);
+  return {
+    target: "deployment",
+    deploymentId: value.id,
+    url: `https://${value.url}`,
+    state: value.readyState,
+    deploymentTarget: value.target ?? null,
+    projectId: value.projectId ?? null,
+    commitSha: value.gitSource?.sha ?? null,
+    ref: value.gitSource?.ref ?? null
+  };
+}
+function createVercelActionTools(ctx) {
+  async function request(operation, path, scope, method = "GET", body) {
+    const url = new URL(path, "https://api.vercel.com");
+    if (scope)
+      url.searchParams.set(
+        scope.startsWith("team_") ? "teamId" : "slug",
+        scope
+      );
+    const init = {
+      method,
+      redirect: "error",
+      signal: AbortSignal.timeout(3e4)
+    };
+    if (body !== void 0) {
+      init.headers = { "Content-Type": "application/json" };
+      init.body = JSON.stringify(body);
+    }
+    const response = await ctx.egress.fetch({
+      provider: "vercel",
+      operation,
+      request: new Request(url, init)
+    });
+    if (!response.ok) {
+      const message = `${operation} failed with HTTP ${response.status}`;
+      if (response.status === 400 || response.status === 404)
+        throw new PluginToolInputError(message);
+      throw new Error(message);
+    }
+    if (response.status === 204) return void 0;
+    return response.json();
+  }
+  async function inspectAlias(alias, scope) {
+    const result = aliasSchema.parse(
+      await request(
+        "vercel.alias.get",
+        `/v4/aliases/${encodeURIComponent(alias)}`,
+        scope
+      )
+    );
+    return {
+      target: "alias",
+      alias: result.alias,
+      deploymentId: result.deploymentId,
+      redirect: result.redirect ?? null
+    };
+  }
+  return {
+    deploymentCreate: definePluginTool({
+      annotations: {
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+        readOnlyHint: false
+      },
+      description: "Start a deployment from a Vercel project's linked GitHub repository. Uses project build settings and environment credentials, so builds may run migrations. Returns the new deployment; inspect it to check readiness.",
+      inputSchema: z.object({
+        project: text.describe("Existing Vercel project name or ID."),
+        team,
+        ref: text.describe(
+          "Git branch, tag, or full commit SHA in the project's linked repository."
+        ),
+        commitSha: z.string().regex(/^[a-f0-9]{40}$/i).describe(
+          "Full commit SHA to pin the source while retaining branch context in ref."
+        ).optional(),
+        target: z.enum(["preview", "production"]).describe("Deployment environment; defaults to preview.").optional()
+      }).strict(),
+      outputSchema: deploymentOutput,
+      async execute(input) {
+        const project = z.object({
+          id: text,
+          name: text,
+          link: z.object({
+            type: text,
+            repoId: z.union([text, z.number()]).optional()
+          }).nullable().optional()
+        }).parse(
+          await request(
+            "vercel.project.get",
+            `/v9/projects/${encodeURIComponent(input.project)}`,
+            input.team
+          )
+        );
+        if (project.link?.type !== "github" || !project.link.repoId)
+          throw new PluginToolInputError(
+            "This deployment tool requires a project linked to GitHub. Use the Vercel CLI for other source types."
+          );
+        const gitSource = {
+          type: "github",
+          repoId: project.link.repoId,
+          ref: input.ref,
+          sha: input.commitSha?.toLowerCase()
+        };
+        return deploymentResult(
+          await request(
+            "vercel.deployment.create",
+            "/v13/deployments",
+            input.team,
+            "POST",
+            {
+              name: project.name,
+              project: project.id,
+              // Vercel uses an omitted target for Preview, not "preview".
+              target: input.target === "production" ? "production" : void 0,
+              gitSource
+            }
+          )
+        );
+      }
+    }),
+    deploymentInspect: definePluginTool({
+      annotations: {
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+        readOnlyHint: true
+      },
+      description: "Inspect a Vercel deployment by ID or hostname. Returns its ID, state, environment, and Git source when available. Use the CLI for logs.",
+      inputSchema: z.object({
+        deployment: text.describe(
+          "Deployment ID or hostname, without a scheme or path."
+        ),
+        team
+      }).strict(),
+      outputSchema: deploymentOutput,
+      async execute(input) {
+        return deploymentResult(
+          await request(
+            "vercel.deployment.get",
+            `/v13/deployments/${encodeURIComponent(input.deployment)}?withGitRepoInfo=true`,
+            input.team
+          )
+        );
+      }
+    }),
+    aliasAssign: definePluginTool({
+      annotations: {
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+        readOnlyHint: false
+      },
+      description: "Assign an alias hostname to a deployment ID. This can replace live traffic. Reads the alias back and returns matches=false if its target changed or it redirects.",
+      inputSchema: z.object({ deploymentId, alias: aliasName, team }).strict(),
+      outputSchema: aliasOutput.extend({ matches: z.boolean() }),
+      async execute(input) {
+        await request(
+          "vercel.alias.assign",
+          `/v2/deployments/${encodeURIComponent(input.deploymentId)}/aliases`,
+          input.team,
+          "POST",
+          { alias: input.alias }
+        );
+        const result = await inspectAlias(input.alias, input.team);
+        return {
+          ...result,
+          matches: result.deploymentId === input.deploymentId && !result.redirect
+        };
+      }
+    }),
+    aliasInspect: definePluginTool({
+      annotations: {
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+        readOnlyHint: true
+      },
+      description: "Read a Vercel alias's current deployment ID or redirect.",
+      inputSchema: z.object({ alias: aliasName, team }).strict(),
+      outputSchema: aliasOutput,
+      async execute(input) {
+        return inspectAlias(input.alias, input.team);
+      }
+    }),
+    deploymentDelete: definePluginTool({
+      annotations: {
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+        readOnlyHint: false
+      },
+      description: "Delete a Vercel deployment by ID. This can remove a live deployment. Does not delete its database or other external state.",
+      inputSchema: z.object({ deploymentId, team }).strict(),
+      outputSchema: pluginToolOutputSchema.extend({
+        target: z.literal("deployment"),
+        deploymentId: text,
+        deleted: z.literal(true)
+      }),
+      async execute(input) {
+        await request(
+          "vercel.deployment.delete",
+          `/v13/deployments/${encodeURIComponent(input.deploymentId)}`,
+          input.team,
+          "DELETE"
+        );
+        return {
+          target: "deployment",
+          deploymentId: input.deploymentId,
+          deleted: true
+        };
+      }
+    })
+  };
+}
+
+// src/index.ts
 function vercelPlugin() {
   return defineJuniorPlugin({
     packageName: "@sentry/junior-vercel",
@@ -31,7 +292,7 @@ function vercelPlugin() {
         VERCEL_TOKEN: "host_managed_credential"
       },
       configKeys: ["project", "team"],
-      description: "Query Vercel deployments and logs and monitor deployment outcomes",
+      description: "Deploy and inspect Vercel projects, manage aliases, query logs, and monitor outcomes",
       displayName: "Vercel",
       domains: ["api.vercel.com"],
       envVars: {
@@ -58,7 +319,8 @@ function vercelPlugin() {
       },
       tools(ctx) {
         return {
-          deployment: createVercelDeploymentTool(ctx)
+          deployment: createVercelDeploymentTool(ctx),
+          ...createVercelActionTools(ctx)
         };
       }
     }

package/dist/tools/actions.d.ts

@@ -0,0 +1,274 @@
+import { type ToolRegistrationHookContext } from "@sentry/junior-plugin-api";
+/** Provide Vercel deployment and alias operations. */
+export declare function createVercelActionTools(ctx: ToolRegistrationHookContext): {
+    deploymentCreate: import("@sentry/junior-plugin-api").PluginToolDefinition<{
+        project: string;
+        ref: string;
+        team?: string | undefined;
+        commitSha?: string | undefined;
+        target?: "preview" | "production" | undefined;
+    }, {
+        [x: string]: unknown;
+        target: "deployment";
+        deploymentId: string;
+        url: string;
+        state: string;
+        deploymentTarget: string | null;
+        projectId: string | null;
+        commitSha: string | null;
+        ref: string | null;
+        objectAnnotations?: {
+            kind: "object";
+            key: string;
+            label: string;
+            objectType: "task" | "code_change" | "automation" | "item";
+            title: string;
+            url: string | null;
+            description?: string | undefined;
+            status?: string | undefined;
+            trigger?: string | undefined;
+            warning?: string | undefined;
+        }[] | undefined;
+        truncated?: boolean | undefined;
+        continuation?: {
+            arguments: Record<string, unknown>;
+            reason?: string | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        target: "deployment";
+        deploymentId: string;
+        url: string;
+        state: string;
+        deploymentTarget: string | null;
+        projectId: string | null;
+        commitSha: string | null;
+        ref: string | null;
+        objectAnnotations?: {
+            kind: "object";
+            key: string;
+            label: string;
+            objectType: "task" | "code_change" | "automation" | "item";
+            title: string;
+            url: string | null;
+            description?: string | undefined;
+            status?: string | undefined;
+            trigger?: string | undefined;
+            warning?: string | undefined;
+        }[] | undefined;
+        truncated?: boolean | undefined;
+        continuation?: {
+            arguments: Record<string, unknown>;
+            reason?: string | undefined;
+        } | undefined;
+    }>;
+    deploymentInspect: import("@sentry/junior-plugin-api").PluginToolDefinition<{
+        deployment: string;
+        team?: string | undefined;
+    }, {
+        [x: string]: unknown;
+        target: "deployment";
+        deploymentId: string;
+        url: string;
+        state: string;
+        deploymentTarget: string | null;
+        projectId: string | null;
+        commitSha: string | null;
+        ref: string | null;
+        objectAnnotations?: {
+            kind: "object";
+            key: string;
+            label: string;
+            objectType: "task" | "code_change" | "automation" | "item";
+            title: string;
+            url: string | null;
+            description?: string | undefined;
+            status?: string | undefined;
+            trigger?: string | undefined;
+            warning?: string | undefined;
+        }[] | undefined;
+        truncated?: boolean | undefined;
+        continuation?: {
+            arguments: Record<string, unknown>;
+            reason?: string | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        target: "deployment";
+        deploymentId: string;
+        url: string;
+        state: string;
+        deploymentTarget: string | null;
+        projectId: string | null;
+        commitSha: string | null;
+        ref: string | null;
+        objectAnnotations?: {
+            kind: "object";
+            key: string;
+            label: string;
+            objectType: "task" | "code_change" | "automation" | "item";
+            title: string;
+            url: string | null;
+            description?: string | undefined;
+            status?: string | undefined;
+            trigger?: string | undefined;
+            warning?: string | undefined;
+        }[] | undefined;
+        truncated?: boolean | undefined;
+        continuation?: {
+            arguments: Record<string, unknown>;
+            reason?: string | undefined;
+        } | undefined;
+    }>;
+    aliasAssign: import("@sentry/junior-plugin-api").PluginToolDefinition<{
+        deploymentId: string;
+        alias: string;
+        team?: string | undefined;
+    }, {
+        [x: string]: unknown;
+        target: "alias";
+        alias: string;
+        deploymentId: string | null;
+        redirect: string | null;
+        matches: boolean;
+        objectAnnotations?: {
+            kind: "object";
+            key: string;
+            label: string;
+            objectType: "task" | "code_change" | "automation" | "item";
+            title: string;
+            url: string | null;
+            description?: string | undefined;
+            status?: string | undefined;
+            trigger?: string | undefined;
+            warning?: string | undefined;
+        }[] | undefined;
+        truncated?: boolean | undefined;
+        continuation?: {
+            arguments: Record<string, unknown>;
+            reason?: string | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        target: "alias";
+        alias: string;
+        deploymentId: string | null;
+        redirect: string | null;
+        matches: boolean;
+        objectAnnotations?: {
+            kind: "object";
+            key: string;
+            label: string;
+            objectType: "task" | "code_change" | "automation" | "item";
+            title: string;
+            url: string | null;
+            description?: string | undefined;
+            status?: string | undefined;
+            trigger?: string | undefined;
+            warning?: string | undefined;
+        }[] | undefined;
+        truncated?: boolean | undefined;
+        continuation?: {
+            arguments: Record<string, unknown>;
+            reason?: string | undefined;
+        } | undefined;
+    }>;
+    aliasInspect: import("@sentry/junior-plugin-api").PluginToolDefinition<{
+        alias: string;
+        team?: string | undefined;
+    }, {
+        [x: string]: unknown;
+        target: "alias";
+        alias: string;
+        deploymentId: string | null;
+        redirect: string | null;
+        objectAnnotations?: {
+            kind: "object";
+            key: string;
+            label: string;
+            objectType: "task" | "code_change" | "automation" | "item";
+            title: string;
+            url: string | null;
+            description?: string | undefined;
+            status?: string | undefined;
+            trigger?: string | undefined;
+            warning?: string | undefined;
+        }[] | undefined;
+        truncated?: boolean | undefined;
+        continuation?: {
+            arguments: Record<string, unknown>;
+            reason?: string | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        target: "alias";
+        alias: string;
+        deploymentId: string | null;
+        redirect: string | null;
+        objectAnnotations?: {
+            kind: "object";
+            key: string;
+            label: string;
+            objectType: "task" | "code_change" | "automation" | "item";
+            title: string;
+            url: string | null;
+            description?: string | undefined;
+            status?: string | undefined;
+            trigger?: string | undefined;
+            warning?: string | undefined;
+        }[] | undefined;
+        truncated?: boolean | undefined;
+        continuation?: {
+            arguments: Record<string, unknown>;
+            reason?: string | undefined;
+        } | undefined;
+    }>;
+    deploymentDelete: import("@sentry/junior-plugin-api").PluginToolDefinition<{
+        deploymentId: string;
+        team?: string | undefined;
+    }, {
+        [x: string]: unknown;
+        target: "deployment";
+        deploymentId: string;
+        deleted: true;
+        objectAnnotations?: {
+            kind: "object";
+            key: string;
+            label: string;
+            objectType: "task" | "code_change" | "automation" | "item";
+            title: string;
+            url: string | null;
+            description?: string | undefined;
+            status?: string | undefined;
+            trigger?: string | undefined;
+            warning?: string | undefined;
+        }[] | undefined;
+        truncated?: boolean | undefined;
+        continuation?: {
+            arguments: Record<string, unknown>;
+            reason?: string | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        target: "deployment";
+        deploymentId: string;
+        deleted: true;
+        objectAnnotations?: {
+            kind: "object";
+            key: string;
+            label: string;
+            objectType: "task" | "code_change" | "automation" | "item";
+            title: string;
+            url: string | null;
+            description?: string | undefined;
+            status?: string | undefined;
+            trigger?: string | undefined;
+            warning?: string | undefined;
+        }[] | undefined;
+        truncated?: boolean | undefined;
+        continuation?: {
+            arguments: Record<string, unknown>;
+            reason?: string | undefined;
+        } | undefined;
+    }>;
+};

package/dist/tools/deployment.d.ts

@@ -10,6 +10,18 @@ export declare function createVercelDeploymentTool(ctx: ToolRegistrationHookCont
     deploymentTarget: "preview" | "production" | "staging" | null;
     projectId: string;
     target: "deployment";
+    objectAnnotations?: {
+        kind: "object";
+        key: string;
+        label: string;
+        objectType: "task" | "code_change" | "automation" | "item";
+        title: string;
+        url: string | null;
+        description?: string | undefined;
+        status?: string | undefined;
+        trigger?: string | undefined;
+        warning?: string | undefined;
+    }[] | undefined;
     truncated?: boolean | undefined;
     continuation?: {
         arguments: Record<string, unknown>;
@@ -28,6 +40,18 @@ export declare function createVercelDeploymentTool(ctx: ToolRegistrationHookCont
     deploymentTarget: "preview" | "production" | "staging" | null;
     projectId: string;
     target: "deployment";
+    objectAnnotations?: {
+        kind: "object";
+        key: string;
+        label: string;
+        objectType: "task" | "code_change" | "automation" | "item";
+        title: string;
+        url: string | null;
+        description?: string | undefined;
+        status?: string | undefined;
+        trigger?: string | undefined;
+        warning?: string | undefined;
+    }[] | undefined;
     truncated?: boolean | undefined;
     continuation?: {
         arguments: Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-vercel",
-  "version": "0.222.0",
+  "version": "0.224.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -27,7 +27,7 @@
   ],
   "dependencies": {
     "zod": "^4.5.4",
-    "@sentry/junior-plugin-api": "0.222.0"
+    "@sentry/junior-plugin-api": "0.224.0"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.79.0",

package/skills/vercel/SKILL.md

@@ -1,63 +1,52 @@
 ---
 name: vercel
-description: Query Vercel deployments, build logs, runtime logs, and deployment status through the Vercel CLI. Use when users ask to debug Vercel deployments, inspect failed builds, fetch production or preview runtime logs, find a deployment for a project or commit SHA, or investigate Vercel-hosted app errors. Do not use it for deploying, rolling back, changing project settings, domains, env vars, caches, storage, or any other Vercel mutation.
+description: Deploy and inspect Vercel apps, assign aliases, delete deployments, investigate logs, and monitor deployment outcomes. Use for Vercel deployment and log requests, not GitHub code changes or other cloud providers.
 ---
 
 # Vercel Operations
 
-Use this skill for read-only Vercel deployment and log investigations.
-
-## Read-only command allowlist
-
-Run only these Vercel CLI commands:
-
-- `vercel logs`
-- `vercel inspect`
-- `vercel list` or `vercel ls`
-- `vercel help`, `vercel --help`, or `vercel <command> --help`
-
-Do not run `deploy`, `rollback`, `promote`, `remove`, `env`, `alias`, `dns`, `project`, `cache`, `blob`, `certs`, `teams`, `domains`, `git`, `link`, `login`, `logout`, `switch`, `pull`, `build`, `dev`, `redeploy`, `bisect`, `api`, or any command that creates, updates, deletes, purges, promotes, deploys, links, authenticates, or changes Vercel state.
-
-## Workflow
-
-1. Resolve the target:
-
-- Determine whether the user needs runtime logs, build logs, deployment status, or deployment discovery.
-- Prefer explicit deployment IDs, deployment URLs, project names, environments, branch names, commit SHAs, status filters, and time windows from the user.
-- When the user did not specify a project or team, read `vercel.project` and `vercel.team` with `jr-rpc config get` and treat them as optional conversation defaults. Explicit user input always wins.
-- Only set or change `vercel.project` and `vercel.team` when the user explicitly asks to store a default for this conversation or channel.
-- Ask one concise follow-up only when the request cannot be bounded to a project, deployment, commit, or time window from the thread or config.
-
-2. Run the narrowest safe command:
-
-- The runtime provides Vercel authentication. Do not set, print, echo, write, or ask for `JUNIOR_VERCEL_TOKEN` or `VERCEL_TOKEN`.
-- If a command shape or flag is unclear, inspect `vercel <command> --help` before guessing.
-- Add `--scope <team>` when a team is known.
-- Add `--project <project>` when a project is known and the command supports it.
-- For runtime logs, prefer `vercel logs --project <project> --since <window> --limit 20 --json` plus user-provided filters such as `--environment`, `--level`, `--status-code`, `--source`, `--query`, or `--deployment`.
-- Use `vercel inspect <deployment-id-or-url> --logs` for build logs. Add `--wait` only when the user explicitly wants to wait for an active build; also bound it with `--timeout`.
-- Use `vercel list <project>` or `vercel ls <project>` to find deployments. Prefer filters such as `--status`, `--environment`, `--prod`, or `--meta githubCommitSha=<sha>` when available.
-- For a deployment watch or event automation, call the `vercel_deployment` plugin tool with the project name and optional team slug or ID. Omit `commitSha` to watch every deployment for the project; add `target` (`production`, `preview`, or `staging`) to limit the watch to one environment; add a full 40-character `commitSha` to watch one deployment (`target` defaults to `production` when omitted with a commit). The tool resolves the canonical project ID through Vercel before Junior creates the conversation subscription or event automation.
-- Use `--follow` only when the user asks for live logs, and stop once enough evidence is captured. Do not leave a streaming command running indefinitely.
-
-3. Bound and minimize output:
-
-- Always use a time window for log searches. Default to the last hour for "right now" incidents and the last 24 hours for retrospective deployment investigations.
-- Prefer JSON output for `vercel logs` when parsing or summarizing.
-- Keep page sizes small. Start with 20 log lines or fewer unless the user asked for more.
-- Quote only the minimum log text needed as evidence. Vercel logs may contain customer data, secrets, request headers, or other sensitive payloads.
-
-4. Report the result:
-
-- Answer the user first with deployment status, error pattern, top failing route/function, or the absence of matching logs.
-- Include the project, environment, deployment, time window, and filters used.
-- Include Vercel deployment or dashboard URLs when the CLI output provides them. Do not fabricate URLs from incomplete IDs.
-
-## Failure handling
-
-- Missing `JUNIOR_VERCEL_TOKEN`: tell the operator to add `JUNIOR_VERCEL_TOKEN` to the Junior deployment environment and redeploy.
-- `401`, invalid token, expired token, or revoked token: report that the configured Vercel token cannot authenticate.
-- `403` or permission denied: report that the configured Vercel token or service account cannot read the requested project/deployment/logs. Do not guess missing Vercel permission scopes.
-- Project not found: confirm `vercel.project`, `vercel.team`, and the user-provided project name or scope.
-- Rate limiting or transient network failure: retry the same bounded read command once. If it still fails, report the throttle or network failure and stop.
-- Mutation request: decline briefly and explain this skill is limited to read-only Vercel logs, deployment inspection, and deployment listing.
+## Resolve the target
+
+- Use the user's explicit project, team, deployment, alias, and environment.
+- Read `vercel.project` and `vercel.team` with standalone `jr-rpc config get`
+  commands only when those defaults are needed. They are fallbacks, not limits.
+- Do not change defaults unless requested.
+- Resolve an ambiguous target before a write. Use Production only when requested.
+
+## Tools and CLI
+
+Discover deployment and alias tools in the Vercel catalog. Follow their schemas.
+Use the CLI for logs, local source uploads, other Git providers, or operations
+not covered by tools. Inspect `vercel <command> --help` when needed. Use
+`--scope <team>` and explicit targets.
+
+Authentication is host-managed. Do not set, print, copy, or request tokens.
+Never use another command or API to bypass a denied action.
+
+## Verification and failures
+
+- Record the deployment ID, source commit when available, and environment.
+  Inspect readiness before using a new deployment.
+- Inspect before retrying an uncertain write. A timeout can occur after Vercel
+  accepted it. Do not blindly repeat a deploy, alias assignment, or deletion.
+- For QA, compare alias deployment IDs before and after testing. A changed
+  target makes affected results inconclusive. Alias checks are not locks.
+  If an assignment returns `matches=false`, do not overwrite the changed target.
+- Verify isolated state before QA that must not affect shared data. Builds can
+  run migrations. Moving an alias does not stop older workers.
+- Report missing credentials or provider permission failures. Do not guess
+  permission scopes or change credentials as a workaround.
+- Retry a transient read once. Bound waits and report unresolved failures.
+
+## Logs and watches
+
+- Prefer `vercel logs` with a project, time window, and limit. Default to the
+  last hour for current incidents and the last 24 hours for retrospective work.
+- Use `vercel inspect <deployment> --logs` for build logs and
+  `vercel list <project>` for deployment discovery. Quote only decisive
+  diagnostics; logs can contain private data.
+- Use live log streaming only when requested and stop after collecting evidence.
+- For watches, call `vercel_deployment` with project and optional team, target,
+  and full commit SHA. Use its returned resource. A commit defaults to
+  Production unless `target` is supplied. Create the watch before completion;
+  earlier webhook events are not replayed.

package/skills/vercel/SPEC.md

@@ -0,0 +1,25 @@
+# Vercel skill contract
+
+## Intent and shape
+
+Guide Vercel operations through plugin tools and the CLI. Use inline guidance;
+tool schemas own API inputs and outputs.
+
+## Evidence and limits
+
+Tool schemas and official Vercel APIs define operation inputs. Provider
+responses supply deployment and alias evidence. The existing token and runtime
+review remain authoritative; the skill does not grant permission.
+
+Alias checks are not a lock. Builds inherit credentials and can run migrations.
+A ready deployment does not prove Slack QA passed.
+
+## Validation and maintenance
+
+Trigger for requests such as "deploy this commit to Vercel", "move this alias",
+"delete this Vercel deployment", and "show Vercel build logs". Do not trigger
+for "open a GitHub PR" or "deploy to AWS".
+
+The plugin's action tests cover request payloads, environment selection, alias
+changes, and failures. Run `pnpm skills:check` after skill edits. Live Vercel
+execution and Slack QA need separate validation.