@arcjet/skills 1.12.0

package/docs/guard.md

@@ -0,0 +1,142 @@
+# Guard non-HTTP JavaScript with Arcjet
+
+Source documentation for the `guard` Agent Skill. JavaScript and TypeScript
+only. For HTTP routes, see `docs/protect.md`.
+
+## When to use Guard
+
+Use `@arcjet/guard` when there is no HTTP request object: agent tool calls,
+MCP server handlers, queue workers, and background jobs.
+
+The word "server" on MCP is misleading. MCP tools are invoked over stdio or
+SSE and do not receive an HTTP request.
+
+## Client
+
+```ts
+import { launchArcjet } from "@arcjet/guard";
+
+export const arcjet = launchArcjet({ key: process.env.ARCJET_KEY! });
+```
+
+Create the client once at module scope. Prefer passing the client explicitly.
+`registerArcjet` enables free `guard()` / `capture()` / `flush()` when you
+cannot thread a client. Free `guard()` fail-opens if nothing is registered —
+check `hasFailedOpen()` and do not treat that ALLOW as a pass.
+
+Declare rules at module scope so `.deniedResult(decision)` and
+`.errorResult(decision)` have a stable reference.
+
+## One `guard()` per operation
+
+Call `guard()` where you already know the operation. Hardcode the `label`.
+Do not interpolate names in a generic dispatcher.
+
+Labels are slugs: lowercase letters, digits, dash, and dot only; must start
+and end with a letter or digit; max 256 bytes. Use `tools.get-weather`, not
+`tools.get_weather`. Metadata keys may contain underscores; labels and
+rate-limit `bucket` names may not.
+
+```ts
+const decision = await arcjet.guard("tools.get-weather", {
+  rules: [/* ... */],
+  metadata: { user: { id: userId } },
+});
+
+if (decision.conclusion === "DENY") {
+  const rateLimited = toolCallLimit.deniedResult(decision);
+  if (rateLimited) {
+    throw new Error(`rate limited – retry after unix ${rateLimited.resetAtUnixSeconds}`);
+  }
+  if (decision.reason === "PROMPT_INJECTION") {
+    throw new Error("input flagged as prompt injection");
+  }
+  return { error: decision.reason };
+}
+```
+
+`decision.reason` is a flat string on DENY (`"RATE_LIMIT"`,
+`"PROMPT_INJECTION"`, `"SENSITIVE_INFO"`, `"MODERATE_CONTENT"`, …) and
+`undefined` on ALLOW. Branch on which rule denied, not only on `DENY`.
+
+`metadata` is nested JSON for the Console. It does not affect the decision.
+Do not put secrets or PII in it.
+
+Every rate-limit rule needs a `key` and a `bucket`. Use a user or session id
+when you have one; otherwise a stable identifier you control (`"default"`,
+deployment name). Do not pass an empty string.
+
+A denial by one rule still spends the others' budget in the same `guard()`
+call. Split rules across two calls if a PII false positive must not drain a
+rate-limit bucket.
+
+`guard()` never throws for runtime degradation. `hasFailedOpen()` is true
+when ALLOW means a rule or the decision could not be processed — that is
+the fail-closed gate. `warnings` are request-validation diagnostics; they
+never change the conclusion. Prefer `hasFailedOpen()` over deprecated
+`hasError()`.
+
+Pass `correlationId` to join a guard decision with a request or agent
+trace. It is a dedicated field, not metadata.
+
+`localDetectSensitiveInfo()` defaults to WASM and matches four types:
+card, email, phone, IP. Names, addresses, and government / financial
+identifiers need `@arcjet/sensitive-info-rampart` (`backend: rampart()`).
+Listing a Rampart-only entity without that backend never matches.
+`moderateContent()` is Guard-only.
+
+## Framework wrappers
+
+Prefer the versioned Guard namespaces over hand-wrapping every tool:
+
+| SDK | Import |
+| --- | ------ |
+| Vercel AI SDK v7 | `@arcjet/guard/vercel-ai/v7` |
+| Vercel Eve | `@arcjet/guard/vercel-eve/v0` |
+| Mastra | `@arcjet/guard/mastra/v1` |
+| Claude Agent SDK | `@arcjet/guard/claude-agent-sdk/v0` |
+| Claude Managed Agents | `@arcjet/guard/claude-managed-agents/v0` |
+| LangGraph JS | `@arcjet/guard/langgraph/v1` |
+| LangChain JS `createAgent` | `@arcjet/guard/langchain/v1` |
+| OpenAI Agents | `@arcjet/guard/openai-agents/v0` |
+| Genkit JS | `@arcjet/guard/genkit/v1` |
+| Google ADK JS | `@arcjet/guard/google-adk/v2` |
+| Strands Agents JS | `@arcjet/guard/strands-agents/v1` |
+| TanStack AI | `@arcjet/guard/tanstack-ai/v0` |
+
+Unversioned aliases do not resolve. Load the matching
+`@arcjet/guard#integrate-arcjet-guard-*` skill for the integration you are
+implementing. Those skills ship in the `@arcjet/guard` package.
+
+Framework wrappers fail closed by default when Guard is unavailable. Core
+`guard()` fails open — check `hasFailedOpen()`.
+
+JS LangChain `createAgent` is `@arcjet/guard/langchain/v1`, not LangGraph.
+JS Google ADK is `guardPlugin` on the Runner — there is no `guardTool`.
+TanStack AI is `guardMiddleware` — do not use `guardTool` (an `execute`
+throw is swallowed). JS Strands Agents is official `@strands-agents/sdk`,
+not Python `strands`.
+
+Every adapter uses one `ArcjetDenialResult` payload
+(`{ arcjetDenied: true, reason, message, retryable }`). Delivery is
+per-framework: return the object (AI SDK, Mastra, OpenAI Agents, Genkit
+`toolResponse.output`, LangGraph, LangChain `guardTool`, Google ADK plugin
+dict, Strands `guardTool`); wrap it (Claude Agent SDK `isError: true`,
+LangChain `guardMiddleware` `ToolMessage`, Strands `guardHooks` cancel
+string, TanStack `onBeforeToolCall` skip); or throw `ArcjetDeniedError`
+(Eve, unless `onDeny: "result"`). A throw from a return-style adapter
+drops the fields.
+
+Human-in-the-loop APIs (`needsApproval`, `interrupt()`, `requireApproval`,
+`requireConfirmation`, `canUseTool`) are not policy gates. After a human
+yes, Guard still runs.
+
+## Capture and flush
+
+`capture()` records that something happened. It never denies. Call `flush()`
+on shutdown. On serverless, pass a platform `waitUntil`.
+
+## Verify
+
+Invoke the protected function directly. Do not `curl` an HTTP route to test
+Guard. Confirm with `npx @arcjet/cli@latest guards list --site-id <id>`.

package/docs/mcp.md

@@ -0,0 +1,74 @@
+# Arcjet MCP server
+
+Connect an AI coding client to the Arcjet API over HTTP with OAuth. Use this
+when the CLI is not available or the client has built-in MCP support.
+
+**Endpoint:** `https://api.arcjet.com/mcp`
+
+Verify that URL before connecting. Only connect from trusted clients. Enable
+confirmation prompts for write operations.
+
+## Client setup
+
+### VS Code
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "arcjet": {
+      "type": "http",
+      "url": "https://api.arcjet.com/mcp"
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add arcjet --transport http https://api.arcjet.com/mcp
+```
+
+### Cursor
+
+`.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "arcjet": {
+      "type": "streamable-http",
+      "url": "https://api.arcjet.com/mcp"
+    }
+  }
+}
+```
+
+### Windsurf
+
+```json
+{
+  "mcpServers": {
+    "arcjet": {
+      "serverUrl": "https://api.arcjet.com/mcp"
+    }
+  }
+}
+```
+
+### Claude Desktop / ChatGPT
+
+Add a custom connector named `Arcjet` with URL `https://api.arcjet.com/mcp`.
+
+## Authentication
+
+OAuth. The first connection redirects to sign in with an Arcjet account.
+
+## Common workflows
+
+- Bootstrap: `list-teams` → `list-sites` → `get-site-key` → write `ARCJET_KEY`
+- Investigate: `analyze-traffic` → `list-requests` → `investigate-ip`
+- Remote rules: `create-rule` (DRY_RUN) → `get-dry-run-impact` → `promote-rule`
+- Briefing: `get-security-briefing`

package/docs/protect.md

@@ -0,0 +1,186 @@
+# Protect HTTP routes with Arcjet
+
+Source documentation for the `protect` Agent Skill. JavaScript and TypeScript
+only. For non-HTTP tool calls, jobs, and MCP handlers, see `docs/guard.md`.
+
+## When to use request protection
+
+Use a framework adapter when the code has an HTTP request object (Next.js
+`Request`, Express `req`, Fastify request, SvelteKit `RequestEvent`).
+
+| Runtime / framework | Package |
+| ------------------- | ------- |
+| Next.js | `@arcjet/next` |
+| Node.js (`http`, Express) | `@arcjet/node` |
+| Bun | `@arcjet/bun` |
+| Deno | `@arcjet/deno` |
+| Fastify | `@arcjet/fastify` |
+| NestJS | `@arcjet/nest` |
+| Nuxt | `@arcjet/nuxt` |
+| React Router | `@arcjet/react-router` |
+| Remix | `@arcjet/remix` |
+| SvelteKit | `@arcjet/sveltekit` |
+| Astro | `@arcjet/astro` |
+
+Hono on Node uses `@arcjet/node`. Hono on Bun uses `@arcjet/bun`.
+
+MCP servers, queue workers, and agent tool calls do **not** receive an HTTP
+request. Use `@arcjet/guard` instead.
+
+Server actions, tRPC, and other RPC-over-HTTP still have an HTTP request —
+use request protection.
+
+Runtime baseline: Node.js `>=22.21.0 <23 || >=24.5.0`, Bun ≥ 1.3.0, Deno
+`stable` / `lts`. Bump the runtime before installing if the project is below
+those floors.
+
+## Client setup
+
+Create **one** `arcjet()` client at module scope in a shared file. Use
+`withRule()` for route-specific extras so clones share the decision cache.
+Sibling `arcjet()` constructors do not share cache.
+
+Always include `shield({ mode: "LIVE" })` as a base rule.
+
+```ts
+import arcjet, { shield, detectBot } from "@arcjet/next";
+
+export const aj = arcjet({
+  key: process.env.ARCJET_KEY!,
+  rules: [
+    shield({ mode: "LIVE" }),
+    detectBot({ mode: "LIVE", allow: ["CATEGORY:SEARCH_ENGINE"] }),
+  ],
+});
+```
+
+Rules that omit `mode` default to `DRY_RUN` in the JavaScript HTTP SDKs. Pass
+`mode: "LIVE"` to enforce.
+
+Never hardcode `ARCJET_KEY`. Write it to the project's env file. Prefer
+`npx @arcjet/cli@latest` to create a site and fetch a key (see `docs/cli.md`).
+
+Install the adapter with the project's package manager. Do not hand-edit
+`package.json` and guess a version.
+
+### Frameworks that are not a shared client file
+
+- **Astro** — register the integration in `astro.config.mjs` and import
+  `arcjet:client`. There is no `lib/arcjet.ts` and no `withRule()`.
+  `@arcjet/astro` validates with Zod `.strict()`, so leftover
+  `detectPromptInjection({ threshold })` throws at startup.
+- **Nuxt** — register the `@arcjet/nuxt` module. The key lives in
+  `nuxt.config.ts`. Import from `#arcjet`. Each `arcjet()` call is its own
+  cache — share one server module.
+- **NestJS** — `ArcjetModule.forRoot()` plus `@InjectArcjet()`.
+- **Bun / Deno** — wrap the fetch handler with `aj.handler()` so Arcjet can
+  see the socket for client IP. Still call `protect()` inside. Deno imports
+  use the `npm:` prefix.
+- **Hono on Node** — type the app with `HttpBindings` from
+  `@hono/node-server` and pass `c.env.incoming` to `protect()`. Hono on Bun
+  passes `c.req.raw`.
+
+### What to pass to `protect()`
+
+| Framework | Argument |
+| --------- | -------- |
+| Express / Node.js | `req` |
+| Next.js App Router | `req` |
+| Next.js Server Components / actions | `await request()` from `@arcjet/next` |
+| Fastify | `request` (Fastify request, not raw Node) |
+| NestJS | `req` |
+| SvelteKit / Nuxt | `event` |
+| Remix / React Router | `args` |
+| Astro / Bun / Deno | `request` |
+| Hono on Node | `c.env.incoming` |
+| Hono on Bun | `c.req.raw` |
+
+## Call `protect()` in the handler
+
+Call `protect()` inside each route handler, once per request. Do not call it
+from Express middleware or Next.js middleware.
+
+```ts
+export async function GET(request: Request) {
+  const decision = await aj.protect(request);
+
+  if (decision.isDenied()) {
+    return Response.json({ error: "Forbidden" }, { status: 403 });
+  }
+
+  return Response.json({ ok: true });
+}
+```
+
+Map denial reasons to HTTP responses only when the status or body should
+differ:
+
+- `decision.reason.isRateLimit()` → 429
+- `decision.reason.isEmail()` / `isSensitiveInfo()` / `isPromptInjection()` → 400
+- everything else (bot, shield, filter) → 403
+
+`decision.isErrored()` means the SDK failed open. Log it and allow.
+
+`detectBot` requires exactly one of `allow` or `deny`. Neither or both throws.
+
+`detectPromptInjection` takes `mode` only. Do not pass `threshold`. Do not
+read `score`; branch on `isPromptInjection()` / `injectionDetected`.
+
+Rules that need extra input at `protect()` time: `tokenBucket` needs
+`{ requested }`, `validateEmail` / `protectSignup` need `{ email }`,
+`sensitiveInfo` needs `{ sensitiveInfoValue }`, `detectPromptInjection`
+needs `{ detectPromptInjectionMessage }`.
+
+Pass `correlationId` when the decision must join another request, guard
+call, or agent trace. It does not affect fingerprinting.
+
+## Characteristics and client IP
+
+Put a `userId` characteristic on the rule that needs it, then pass a trusted,
+authenticated user ID at protection time. Never rate limit by a client-controlled
+header unless a trusted proxy strips and rewrites it.
+
+Treat client-IP provenance as security configuration. When no usable public
+address is available, adapters may fall back to forwarding headers and log one
+`client_ip_provenance="unverified-header"` warning for the lifetime of each
+SDK client. Configure every trusted proxy (`proxies`, or a helper such as
+`cloudflare()`). The application must be reachable only through infrastructure
+that overwrites or safely appends those headers. Malformed proxy entries are
+rejected. `0.0.0.0/0` and `::/0` warn because they trust every peer.
+
+If the application already has an independently trusted client IP, pass it as
+`ipSrc` to both `protect()` and the diagnostics API. A non-empty value wins
+over automatic detection. An empty string is treated as omitted. Malformed
+values are rejected. Syntax validation does not prove provenance.
+
+Never silence an `unverified-header` warning by copying `X-Forwarded-For` (or
+another client-controlled header) into `ipSrc`. That relabels attacker input
+as trusted. Inspect representative requests with
+`client.clientIpDetails(request)` in `@arcjet/node`, or `findIpDetails()` /
+`resolveClientIp()` from `@arcjet/ip`. Check `ip`, `provenance`, `verified`,
+and `header`. These diagnostics do not consume the once-per-client warning.
+
+`protect()` accepts nested-JSON `metadata`. It does not affect fingerprinting.
+Do not put secrets or PII in it. When present, request decisions also expose
+optional IP threat intelligence (`decision.ip.threat`).
+
+When present, `decision.ip.threat` is optional IP threat intelligence. Check
+before reading.
+
+## Common mistakes
+
+- Using `@arcjet/guard` on an HTTP route, or a request adapter on a tool call
+- Calling `protect()` in middleware instead of the route handler
+- Calling `protect()` twice for the same request (double-counts rate limits)
+- Leaving rules in `DRY_RUN` and expecting them to block
+- Passing both `allow` and `deny` to `detectBot`
+- Passing `threshold` to `detectPromptInjection`
+- Copying `X-Forwarded-For` into `ipSrc` to hide an unverified-header warning
+- Hardcoding `ARCJET_KEY`
+
+## Verify
+
+1. Type-check or build the project.
+2. Hit the protected route (`curl`). To trip a rate limit, loop the request.
+3. Confirm the decision with `npx @arcjet/cli@latest requests list --site-id <id>`
+   or the [Console](https://console.arcjet.com).

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@arcjet/skills",
+  "version": "1.12.0",
+  "description": "Versioned Agent Skills for the Arcjet JavaScript SDK, shipped with TanStack Intent",
+  "keywords": [
+    "agent-skills",
+    "ai",
+    "arcjet",
+    "security",
+    "tanstack-intent"
+  ],
+  "homepage": "https://arcjet.com",
+  "bugs": {
+    "url": "https://github.com/arcjet/arcjet-js/issues",
+    "email": "support@arcjet.com"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Arcjet",
+    "email": "support@arcjet.com",
+    "url": "https://arcjet.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arcjet/arcjet-js.git",
+    "directory": "arcjet-skills"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "skills"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --tsconfig=tsconfig.json",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "validate-skills": "node ../.github/scripts/intent-cli.mjs validate",
+    "stale-skills": "node ../.github/scripts/intent-cli.mjs stale --json",
+    "test-api": "node --test -- test/*.test.ts",
+    "test-coverage": "node --experimental-test-coverage --test -- test/*.test.ts",
+    "test": "npm run build && npm run test-coverage && npm run validate-skills && node ../.github/scripts/check-skill-source-stale.mjs"
+  },
+  "devDependencies": {
+    "@tanstack/intent": "0.3.8",
+    "@types/node": "22.20.1",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2"
+  },
+  "engines": {
+    "node": ">=22.21.0 <23 || >=24.5.0"
+  }
+}

package/skills/choose-protections/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: choose-protections
+description: Choose which Arcjet rules address a security problem. Use when deciding between detectBot, shield, rate limits, detectPromptInjection, sensitiveInfo, validateEmail, filter, or Guard-only content moderation.
+license: Apache-2.0
+compatibility: JavaScript and TypeScript Arcjet SDK.
+metadata:
+  author: arcjet
+  type: core
+  library: "@arcjet/skills"
+  library_version: "1.12.0" # x-release-please-version
+sources:
+  - docs/choose-protections.md
+---
+
+# Choose Arcjet protections
+
+Load this skill when you need to pick rules. Then load `@arcjet/skills#protect`
+or `@arcjet/skills#guard` to implement them.
+
+| Problem | Rule | Where |
+| --- | --- | --- |
+| Bots, scrapers, automated clients | `detectBot` (`allow` **or** `deny`, not both) | Request only |
+| SQLi / XSS / common probes | `shield` (`mode: "LIVE"`) | Request only |
+| Cost / abuse quotas | `tokenBucket`, `fixedWindow`, `slidingWindow` | Request and Guard |
+| Jailbreaks, instruction overrides | `detectPromptInjection` (binary; no `threshold`) | Request and Guard |
+| Card / email / phone / IP in text | `sensitiveInfo` / `localDetectSensitiveInfo` | Request and Guard |
+| Names, addresses, gov IDs | same rules + `@arcjet/sensitive-info-rampart` | Server runtime |
+| Unsafe / abusive text | `moderateContent` | Guard only |
+| Signup spam, disposable email | `validateEmail` + `protectSignup` | Request only |
+| VPN / Tor / country / IP lists | `filter` | Request only |
+| Dangerous tool calls | Guard per-tool `label` + rate limits | Guard only |
+
+Token bucket: variable-cost AI (`requested` per call). Fixed window: hard cap.
+Sliding window: no boundary burst. Request rate limits default to IP; set
+`characteristics: ["userId"]` for a user key. Guard rate limits always need
+`key` and `bucket`.
+
+Default sensitive-info backend matches four structured types. Rampart-only
+entities never match without `backend: rampart()`.
+
+`capture()` records that an action happened. It is not a protection rule.
+
+Remote bot and filter rules can be managed with the CLI or MCP without a
+redeploy — load `@arcjet/skills#cli` or `@arcjet/skills#mcp`.

package/skills/cli/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: cli
+description: "Connect a project to Arcjet with the CLI: sign in, pick a team and site, and write ARCJET_KEY. Use when bootstrapping Arcjet, listing requests or guards, or managing remote rules from a terminal."
+license: Apache-2.0
+compatibility: Any project that can run npx or the arcjet binary.
+metadata:
+  author: arcjet
+  type: core
+  library: "@arcjet/skills"
+  library_version: "1.12.0" # x-release-please-version
+sources:
+  - docs/cli.md
+---
+
+# Arcjet CLI
+
+Preferred way to get a real `ARCJET_KEY` before writing Arcjet code. Do not
+leave the key as a TODO.
+
+```bash
+npx -y @arcjet/cli@latest auth status
+# if not signed in:
+npx -y @arcjet/cli@latest auth login
+
+npx -y @arcjet/cli@latest teams list --output json --fields id,name
+npx -y @arcjet/cli@latest sites list --team-id <team_id> --output json --fields id,name
+npx -y @arcjet/cli@latest sites get-key --site-id <site_id> --output json --fields key
+```
+
+Write `key` to the project's env file as `ARCJET_KEY=ajkey_...`. Match
+existing env-file conventions and `.gitignore`. Never hardcode the key.
+
+Frequent use: `npm install -g @arcjet/cli`, `brew install arcjet/tap/arcjet`,
+or `curl -sSfL https://arcjet.com/cli/install.sh | bash`.
+
+`--output json` and `--fields` keep agent context small. Confirm with the
+user before write or delete operations (`--confirm`).
+
+Investigate: `requests list` / `guards list` / `requests explain` /
+`guards explain` / `briefing`. Remote rules: `rules create` (DRY_RUN) →
+`analyze dry-run-impact` → `rules promote`.
+
+If the CLI cannot run, load `@arcjet/skills#mcp` or send the user to
+https://console.arcjet.com.

package/skills/guard/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: guard
+description: "Add Arcjet Guard to non-HTTP JavaScript: agent tool calls, MCP handlers, queue workers, and background jobs. Use when there is no HTTP request object, or when the user asks to guard tools, rate-limit agent actions, or block prompt injection on tool arguments."
+license: Apache-2.0
+compatibility: JavaScript and TypeScript apps using @arcjet/guard on Node.js >= 22.
+metadata:
+  author: arcjet
+  type: core
+  library: "@arcjet/skills"
+  library_version: "1.12.0" # x-release-please-version
+sources:
+  - docs/guard.md
+---
+
+# Guard non-HTTP JavaScript
+
+Use `@arcjet/guard` when there is no HTTP request. MCP tools, queue workers,
+and agent tool calls are Guard. HTTP routes are `@arcjet/skills#protect`.
+
+For a specific vendor SDK, load the matching skill from `@arcjet/guard`
+(`@arcjet/guard#integrate-arcjet-guard-agents`, `-eve`, `-mastra`,
+`-langgraph`, `-langchain`, `-openai-agents`, `-genkit`, `-google-adk`,
+`-strands-agents`, `-tanstack-ai`, `-claude-agent-sdk`,
+`-claude-managed-agents`).
+
+## Client
+
+```ts
+import { launchArcjet } from "@arcjet/guard";
+
+export const arcjet = launchArcjet({ key: process.env.ARCJET_KEY! });
+```
+
+One client at module scope. Get the key with `@arcjet/skills#cli` first.
+Declare rules at module scope so `.deniedResult(decision)` works.
+
+## One `guard()` per operation
+
+Hardcode the `label`. Do not interpolate in a generic dispatcher.
+
+Labels: lowercase letters, digits, `-`, `.` only; start and end with a letter
+or digit. `tools.get-weather`, not `tools.get_weather`.
+
+```ts
+const decision = await arcjet.guard("tools.get-weather", {
+  rules: [/* ... */],
+  metadata: { user: { id: userId } },
+});
+
+if (decision.conclusion === "DENY") {
+  const rateLimited = toolCallLimit.deniedResult(decision);
+  if (rateLimited) {
+    return { error: `rate limited, retry after ${rateLimited.resetAtUnixSeconds}` };
+  }
+  return { error: decision.reason };
+}
+if (decision.hasFailedOpen()) {
+  // ALLOW only because a rule could not run — deny here if the site is sensitive
+}
+```
+
+Core `guard()` fails open — check `hasFailedOpen()`. `warnings` never change
+the conclusion. Rate-limit rules need `key` and `bucket`. Nested `metadata`
+is Console-only; no secrets or PII. `decision.reason` is a flat string on
+DENY and `undefined` on ALLOW.
+
+`localDetectSensitiveInfo()` default backend matches card / email / phone /
+IP only. Names and government IDs need `backend: rampart()`.
+`moderateContent()` is Guard-only.
+
+`capture()` is visibility, never a deny. `flush()` on shutdown.
+
+## Versioned wrappers
+
+Import `@arcjet/guard/<vendor>/v<major>` — unversioned paths do not resolve.
+Wrappers fail closed by default. HITL (`needsApproval`, `interrupt()`,
+`requireConfirmation`, `canUseTool`) is not a policy gate; Guard still runs
+after a human yes.
+
+Google ADK is `guardPlugin` (no `guardTool`). TanStack AI is
+`guardMiddleware` (do not wrap `execute`). LangChain `createAgent` is
+`/langchain/v1`, not LangGraph.
+
+Load `@arcjet/skills#choose-protections` to pick rules. Exact signatures live
+in the installed `@arcjet/guard` types.

package/skills/mcp/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: mcp
+description: Connect an AI coding client to the Arcjet MCP server at https://api.arcjet.com/mcp. Use when the client has built-in MCP support or the CLI is not available.
+license: Apache-2.0
+compatibility: AI clients that support remote MCP over HTTP / OAuth.
+metadata:
+  author: arcjet
+  type: core
+  library: "@arcjet/skills"
+  library_version: "1.12.0" # x-release-please-version
+sources:
+  - docs/mcp.md
+---
+
+# Arcjet MCP server
+
+Endpoint: `https://api.arcjet.com/mcp` only. OAuth on first connect. Enable
+write confirmations. Prefer `@arcjet/skills#cli` when a terminal is available.
+
+**Cursor** — `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "arcjet": {
+      "type": "streamable-http",
+      "url": "https://api.arcjet.com/mcp"
+    }
+  }
+}
+```
+
+**VS Code** — `.vscode/mcp.json` with `"type": "http"` and the same URL.
+
+**Claude Code:**
+
+```bash
+claude mcp add arcjet --transport http https://api.arcjet.com/mcp
+```
+
+Bootstrap: `list-teams` → `list-sites` → `get-site-key` → write `ARCJET_KEY`.
+Investigate: `analyze-traffic`, `list-requests`, `list-guards`,
+`investigate-ip`. Remote rules: `create-rule` (DRY_RUN) →
+`get-dry-run-impact` → `promote-rule`.