docs: correct and tighten the agent get started page

[davidmytton]

Reviews and corrects the agent get started page from the perspective of an AI
coding agent: accuracy against the rest of the docs, the information an agent
actually needs, and concision.

Every SDK claim and code example here was verified against the @arcjet/guard
type definitions rather than against prose in other docs.

Accuracy fixes

• Removed commands that don't exist. The Verify section told agents to run
  arcjet guards list|details|explain and call the list-guards and
  get-guard-details MCP tools. None of these appear in cli.mdx,
  mcp-server.mdx, or anywhere else in the repo. Guard decisions are now
  pointed at the Console, with a note that the request commands cover
  request-based protection only.
• requests details / requests explain now show their required
  --site-id and --request-id flags.
• Policy tools are MCP-only. The page claimed "both transports expose the
  same policy tools"; the CLI has remote rule commands, not policy commands.
• launchArcjet is not a sync client. The JavaScript guard client is async
  with no blocking variant. Only Python has launch_arcjet_sync.
• Framework adapters take action, not label. Passing label to
  guardTool() does not compile. Both forms are now explained.
• Publication gate corrected. A stored test is required for a live
  expression rule; all-dry-run policies can be saved without one, and
  detector-backed rules are exempt.
• MCP clients and OAuth. Added Codex CLI, and qualified the automatic
  browser claim, which holds for Claude Code and ChatGPT but not for Cursor,
  Codex CLI, or VS Code.
• ARCJET_ENV moved into a shared step, since it is transport-independent,
  with a note that the Go SDK ignores it.
• Dropped the incorrect claim that the install tables match the docs home page.
  Go is not in that list.
• Added the missing content moderation row to the Protect/Guard table.
• Softened the middleware caution to match best-practices.mdx, which
  discourages middleware rather than prohibiting it.

backend: rampart() was flagged during review as unsupported, but it is a real
rule-level field in the SDK types alongside the client-level
sensitiveInfoBackend. Both are now documented, so this claim was kept.

Rendering fix

Eight <Link.Page> components had been reformatted onto their own lines, which
in MDX splits a sentence into separate paragraphs and leaves a trailing .
rendering as its own paragraph. Confirmed by compiling the MDX. These are now
plain markdown links, matching the links already used elsewhere on the page.
Link.Page resolves to an identical href here because the page is not
SDK-scoped.

Content for agents

• Added a "Choose an integration path" decision table up front with manifest
  detection, so an agent can skip to the relevant section instead of reading
  linearly.
• Added verified code examples for the guard call in JavaScript and Python.
  The JavaScript example type-checks clean against @arcjet/guard under
  --strict.
• Added the policyInput shape for typed policy inputs, and the server versus
  local exposure distinction.
• Added a caution that no decision is not the same as a denial, a failure mode
  that makes a broken guard look like a working one.
• Consolidated Claude Managed Agents, which had been spread across four
  sections, and trimmed the prompt list from 18 items to 12.

Verification

• astro check: 0 errors, 0 warnings
• astro build: passes, all internal links valid
• prettier --check: clean
• Guard example type-checks against the real SDK types

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
arcjet-docs	Ready	Preview	Sep 16, 2026 7:07pm UTC

[arcjet-review]

Arcjet Review — 🟡 Medium Risk

Decision: Needs Review

Rationale: This is primarily a documentation and generated snapshot update, with no executable application security logic changed. However, the diff includes authentication-related instructions and OAuth/token language, so the auth escalation trigger fires. The PR also changes security-sensitive agent-facing documentation, including removing client-IP safety guidance from public/llms.txt; that should be verified by a human because AI-agent-facing docs can directly affect generated security integrations. I also found a concrete documentation typo in the new agent guide. Because a security documentation flag is raised, this cannot be approved automatically.

Summary of Changes

Updates Arcjet positioning copy across README, docs metadata, structured data, generated llms files, and snapshots; substantially rewrites the agent get-started guide with integration-path selection, CLI/MCP setup, guard examples, policy guidance, and verification instructions; updates tests around llms.txt discovery.

PR Title & Description

These do not match the changes on the branch. They did not change this review's decision, but they will withhold approval once the other findings are resolved. Update them, then add the ai-review label to re-run the review.

• title (incomplete): The title says this only corrects and tightens the agent get-started page, but the diff also updates README copy, site metadata, structured data, public llms files, generated snapshots, and llms discovery tests.
• description (incomplete): The description is detailed for agent-get-started.mdx, but it does not clearly call out the broad Arcjet positioning/SEO/structured-data changes, the substantial shortening/restructuring of public/llms.txt, the newly hardcoded pricing facts, or the llms discovery test changes.

Suggested title: docs: update agent get-started, llms files, and Arcjet positioning

Suggested description

Updates the agent get-started guide with clearer integration-path selection, CLI/MCP setup, Guard examples, policy guidance, and verification instructions.

Also standardizes Arcjet positioning copy across README, docs pages, structured data, and site metadata; restructures public llms files and agent discovery entry points; updates related llms and screenshot snapshots; and adjusts llms discovery tests.

Escalation Triggers

• Authentication & Authorization: The diff changes documentation containing OAuth/authentication flow guidance and token/API-key handling instructions for the CLI and MCP server.

Security Flags

• [MEDIUM] Security Documentation (public/llms.txt): public/llms.txt removes the previous client-IP safety guidance, including warnings about spoofable forwarding headers and trusted proxy configuration. Because this file is intended for AI agents, please verify that equivalent safety guidance remains easy for agents to discover before they generate request-protection integrations.

Review Focus Areas

• Should the removed client-IP/proxy safety section remain in llms.txt, or is it now clearly discoverable from llms-full.txt or another linked page?
  AI agents may use llms.txt as their primary source. Removing security configuration caveats can lead to insecure generated code that trusts spoofable client-controlled headers.
• Please remove the duplicated product name in the opening sentence.
  The new sentence renders as '[Arcjet] Arcjet is...', which is a visible documentation typo on the main page this PR focuses on.
• Please confirm the newly hardcoded pricing/free-plan facts are intentionally included in an agent-facing static file and have an ownership/update path.
  Pricing copy tends to become stale quickly; stale public docs can mislead both users and AI agents.
• Please visually inspect the updated binary screenshot snapshots.
  The binary PNG diffs cannot be reviewed textually here, so human confirmation is needed that the rendering changes are expected.

Notes

The PR is documentation-heavy with many generated snapshot changes and appears large enough to warrant careful human review despite no runtime code-path changes.

_{Review: 8ae01823 | Model: openai/gpt-5.5 | Powered by Arcjet Review}