Editorial improvements for #749

app/en/guides/contextual-access/build-your-own/page.mdx

@@ -5,11 +5,13 @@ description: "Build your own Logic Extensions webhook server from the OpenAPI sp
 
 # Build Your Own Contextual Access Server
 
-This guide walks through implementing a webhook server that satisfies the Contextual Access Webhook contract. You can write it in any language — the contract is defined by an OpenAPI 3.0 spec.
+You can implement a webhook server that satisfies the Contextual Access Webhook contract in any language using the OpenAPI 3.0 spec.
+
+This guide explains how to build a custom contextual access server from scratch. You'll learn to implement the webhook endpoints, handle authentication, and integrate with Arcade's contextual access system. Use this approach when you need full control over your server implementation or want to use a language not covered by existing examples.
 
 ## OpenAPI spec
 
-The canonical contract is maintained in the [ArcadeAI/schemas](https://github.com/ArcadeAI/schemas) repository:
+The canonical contract lives in the [ArcadeAI/schemas](https://github.com/ArcadeAI/schemas) repository:
 
 - **OpenAPI 3.0 spec:** [logic_extensions/http/1.0/schema.yaml](https://github.com/ArcadeAI/schemas/blob/main/logic_extensions/http/1.0/schema.yaml)
 
@@ -32,11 +34,11 @@ curl -sL https://raw.githubusercontent.com/ArcadeAI/schemas/main/logic_extension
 oapi-codegen -generate types,server -package server schema.yaml
 ```
 
-The [logic-extensions-examples](https://github.com/ArcadeAI/logic-extensions-examples) repo uses this approach — see `pkg/server/` for the generated types.
+The [logic-extensions-examples](https://github.com/ArcadeAI/logic-extensions-examples) repo uses this approach—see `pkg/server/` for the generated types.
 
 ## Endpoints to implement
 
-Your server needs to expose HTTP POST endpoints for each hook point you want to handle. Endpoint paths are fully configurable in the Dashboard — the defaults are shown below.
+Your server needs to expose HTTP POST endpoints for each hook point you want to handle. Endpoint paths are fully configurable in the Dashboard—the defaults show below.
 
 | Endpoint | Hook point | Required |
 | --- | --- | --- |
@@ -109,17 +111,17 @@ Return either an allow list or a deny list (not both):
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `only` | object | If present, **only** these tools are allowed (deny list ignored) |
-| `deny` | object | Tools listed here are denied (ignored if `only` is present) |
+| `only` | object | If present, **only** these tools can be accessed (deny list ignored) |
+| `deny` | object | Tools listed here cannot be accessed (ignored if `only` is present) |
 
-If you return neither field, the Arcade treats it as "no change" — all tools remain allowed at this hook.
+If you return neither field, Arcade treats it as "no change"—all tools remain allowed at this hook.
 
 ## Response codes (pre and post)
 
 | Code | Meaning |
 | --- | --- |
-| `OK` | Proceed; optional `override` is applied |
-| `CHECK_FAILED` | Deny the operation; `error_message` is shown to the agent |
+| `OK` | Proceed; system applies optional `override` |
+| `CHECK_FAILED` | Deny the operation; system displays `error_message` to the agent |
 | `RATE_LIMIT_EXCEEDED` | Deny with rate-limit semantics |
 
 
@@ -134,11 +136,11 @@ Configure the auth method when creating your extension in the Dashboard.
 
 ## Failure handling and retries
 
-- **Timeout:** Configurable per extension (default 5s); can be overridden per hook. On timeout, the hook's failure mode applies (Fail closed = block, Fail open = allow).
+- **Timeout:** Configurable per extension (default 5 s); can be overridden per hook. On timeout, the hook's failure mode applies (Fail closed = block, Fail open = allow).
 - **Retries:** Optional at the extension level; only for transient failures (5xx, timeout, connection error). 4xx responses are not retried.
 
 ## Next steps
 
-- [API Reference](/references/contextual-access-webhook-api) — Interactive Swagger documentation for the full schema
-- [Run an extension](/guides/contextual-access/examples) — Try the open-source example servers as reference
-- [How Hooks Work](/guides/contextual-access/how-hooks-work) — Understand execution order, phases, and failure modes
+- [API Reference](/references/contextual-access-webhook-api)—Interactive Swagger documentation for the full schema
+- [Run an extension](/guides/contextual-access/examples)—Try the open-source example servers as reference
+- [How Hooks Work](/guides/contextual-access/how-hooks-work)—Understand execution order, phases, and failure modes

app/en/guides/contextual-access/examples/page.mdx

@@ -3,7 +3,9 @@ title: "Running a Server"
 description: "Run open-source example webhook servers to get started with Contextual Access"
 ---
 
-# Running an Server
+# Running a Server
+
+Run open-source example webhook servers to get started with Contextual Access.
 
 The fastest way to get started with Contextual Access is to run one of the open-source example servers. These are example Go implementations you can use as-is or as a starting point for your own server.
 
@@ -67,7 +69,7 @@ go run ./examples/contextual_access/basic_rules -config ./examples/basic_rules/e
 
 Each server exposes `GET /health`, `POST /access`, `POST /pre`, and `POST /post` (or a subset, depending on which hook points it implements).
 
-## Connect to the Arcade
+## Connect to Arcade
 
 Once your server is running:
 
@@ -79,5 +81,5 @@ See [How Hooks Work](/guides/contextual-access/how-hooks-work) for details on co
 
 ## Next steps
 
-- [Build your own](/guides/contextual-access/build-your-own) — Implement the webhook contract in any language
-- [API Reference](/references/contextual-access-webhook-api) — Interactive schema documentation for the webhook contract
+- [Build your own](/guides/contextual-access/build-your-own)—Implement the webhook contract in any language
+- [API Reference](/references/contextual-access-webhook-api)—Interactive schema documentation for the webhook contract

app/en/guides/contextual-access/how-hooks-work/page.mdx

@@ -5,17 +5,19 @@ description: "Understand hook points, execution order, extensions, failure modes
 
 # How Hooks Work
 
-This page explains how Arcade invokes your external logic at each stage of tool execution, how you configure extensions and hook points, and how  ordering and failures are handled.
+This page explains how Arcade invokes your external logic at each stage of tool execution.
+
+This guide is for developers implementing contextual access controls who need to understand how Arcade's webhook system works. You'll learn about hook points, execution order, extensions, and failure modes so you can design effective access controls and tool modifications. Use this information when planning your webhook architecture and configuring hook behaviors. The concepts covered here apply whether you're building organization-wide compliance checks or project-specific customizations.
 
 ## Hook points
 
 Arcade defines three hook points. You do not create new ones, you configure behavior at the ones that exist:
 
 | Hook point | When it fires | What you can do |
 | --- | --- | --- |
-| **Access Hook** | When listing tools for a user | Return an allow list or deny list to control which tools the user can see. Results are cached. |
+| **Access Hook** | When listing tools for a user | Return an allow list or deny list to control which tools the user can see. Results cache automatically. |
 | **Pre-Execution Hook** | Before each tool execution | Allow, deny, or modify the request (inputs, secrets, routing). |
-| **Post-Execution Hook** | After tool execution completes | Allow, deny, or modify the output (e.g. PII redaction, content filtering). |
+| **Post-Execution Hook** | After tool execution completes | Allow, deny, or modify the output (for example, PII redaction, content filtering). |
 
 You only need to implement the hook points you care about. If you only need post-execution filtering, you only implement the post-execution endpoint.
 
@@ -25,8 +27,8 @@ A Webhook **extension** is the connection between Arcade and your webhook server
 
 - **Endpoint URLs** for each hook point you implement (access, pre-execution, post-execution)
 - **Authentication** method (Bearer token or mTLS)
-- **Timeout** (default 5s), **retry**, and **cache** settings
-- **Scope** — bound to an organization or a specific project
+- **Timeout** (default 5 s), **retry**, and **cache** settings
+- **Scope**—bound to an organization or a specific project
 
 One extension can serve multiple hook configurations. When you change a URL or rotate a credential, you update the extension once and every hook that uses it picks up the change.
 
@@ -41,25 +43,25 @@ One extension can serve multiple hook configurations. When you change a URL or r
 
 A **hook configuration** attaches an extension to a specific hook point and controls its behavior:
 
-- **Hook point** — Which of the three hooks to run at
-- **Extension** — Which extension to call (must be in scope)
-- **Phase** — `before` or `after` (organization hooks only; see execution order below)
-- **Priority** — Order within the same phase and extension scope (lower number = runs first)
-- **Failure mode** — What happens when the webhook is unreachable
+- **Hook point**—Which of the three hooks to run at
+- **Extension**—Which extension to call (must be in scope)
+- **Phase**—`before` or `after` (organization hooks only; see execution order below)
+- **Priority**—Order within the same phase and extension scope (lower number = runs first)
+- **Failure mode**—What happens when the webhook is unreachable
 
-You can have multiple configurations on the same hook point (e.g. an organization access check and a project-level access check). They all run in a defined order.
+You can have multiple configurations on the same hook point (for example, an organization access check and a project-level access check). They all run in a defined order.
 
 ## Execution order
 
 Hooks at both organization and project scope run together. Arcade executes them in this fixed order:
 
-1. **Organization before** — Organization-scoped hook configs with phase `before`, ordered by priority
-2. **Project** — Project-scoped hook configs, ordered by priority
-3. **Organization after** — Organization-scoped hook configs with phase `after`, ordered by priority
+1. **Organization before**—Organization-scoped hook configs with phase `before`, ordered by priority
+2. **Project**—Project-scoped hook configs, ordered by priority
+3. **Organization after**—Organization-scoped hook configs with phase `after`, ordered by priority
 
 Organization hooks have a **phase** setting (`before` or `after`) that controls whether they run before or after project hooks. Project hooks always run in the middle and do not have a phase setting.
 
-Within each group, lower priority numbers run first. Each hook sees the accumulated result from all previous hooks (e.g. modified inputs from an earlier hook). **Any denial stops the entire pipeline** and the operation fails immediately.
+Within each group, lower priority numbers run first. Each hook sees the accumulated result from all previous hooks (for example, modified inputs from an earlier hook). **Any denial stops the entire pipeline** and the operation fails immediately.
 
 | Goal | Scope | Configuration |
 | --- | --- | --- |
@@ -73,20 +75,24 @@ When your webhook is unreachable (timeout, 5xx, connection error, etc), Arcade a
 
 | Mode | Behavior |
 | --- | --- |
-| **Fail closed** | Block the operation. Use for security-critical checks (e.g. access control). |
-| **Fail open** | Allow the operation to proceed. Use for non-critical enhancements (e.g. metrics, optional enrichment). |
+| **Fail closed** | Block the operation. Use for security-critical checks (for example, access control). |
+| **Fail open** | Allow the operation to proceed. Use for non-critical enhancements (for example, metrics, optional enrichment). |
 
 Set the failure mode per hook configuration. Timeout can be overridden per hook; otherwise the extension default applies.
 
+- Set headers programmatically (for example, adding custom auth headers)
+- Add retry logic (for example, exponential backoff for flaky services)
+- Log requests and responses for debugging
+
 ## Setting up in the Dashboard
 
 You configure extensions and hook points from the **Arcade Dashboard**:
 
-1. **Create an extension** — Navigate to **Contextual Access**, click **Create Extension**, fill in endpoint URLs, auth, scope, and timeout/retry settings.
-2. **Create a hook configuration** — Navigate to **Logic Extensions → Hook Points**, click **Create Hook Configuration**, select the extension, hook point, phase, priority, and failure mode.
+1. **Create an extension**—Navigate to **Contextual Access**, click **Create Extension**, fill in endpoint URLs, auth, scope, and timeout/retry settings.
+2. **Create a hook configuration**—Navigate to **Logic Extensions → Hook Points**, click **Create Hook Configuration**, select the extension, hook point, phase, priority, and failure mode.
 
 ## Next steps
 
-- [Run an extension](/guides/contextual-access/examples) — Try the open-source example servers
-- [Build your own](/guides/contextual-access/build-your-own) — Implement the webhook contract from the OpenAPI spec
-- [API Reference](/references/contextual-access-webhook-api) — Interactive schema documentation for the webhook contract
+- [Run an extension](/guides/contextual-access/examples)—Try the open-source example servers
+- [Build your own](/guides/contextual-access/build-your-own)—Implement the webhook contract from the OpenAPI spec
+- [API Reference](/references/contextual-access-webhook-api)—Interactive schema documentation for the webhook contract

app/en/guides/contextual-access/page.mdx

@@ -1,26 +1,28 @@
 ---
 title: "Contextual Access"
-description: "Control who can see and use which tools, validate requests, and filter outputs — per user, per org, per project"
+description: "Control who can see and use which tools, validate requests, and filter outputs—per user, per org, per project"
 ---
 
 import { Cards } from "nextra/components";
 
 # Contextual Access
 
-Agents have broad access to tools, but enterprises need fine-grained control. Arcade's contextual access lets you govern tool visibility and behavior at every stage of execution — who can see a tool, what inputs are allowed, and what comes back.
+Control who can see and use which tools, validate requests, and filter outputs based on user, organization, or project context.
+
+Agents have broad access to tools, but enterprises need fine-grained control. Arcade's contextual access lets you govern tool visibility and behavior at every stage of execution—who can see a tool, what inputs you allow, and what comes back.
 
 You connect your own access-control, compliance, or transformation logic to the Arcade Engine. Your rules run inline during tool execution with no changes to your tools or agents required.
 
 ## What you can do
 
-- **Control tool visibility** — Decide which tools each user can see based on role, team, entitlement, or any signal from your IDP
-- **Validate requests** — Enforce policies before execution (e.g., block certain domains, require org-scoped inputs)
-- **Transform payloads** — Enrich inputs, inject secrets, redact PII from outputs, or filter content
-- **Audit every interaction** — Route all tool calls through your security and logging infrastructure
+- **Control tool visibility**—Decide which tools each user can see based on role, team, entitlement, or any signal from your IDP
+- **Validate requests**—Enforce policies before execution (for example, block certain domains, require org-scoped inputs)
+- **Transform payloads**—Enrich inputs, inject secrets, redact PII from outputs, or filter content
+- **Audit every interaction**—Route all tool calls through your security and logging infrastructure
 
 ## How it works
 
-Contextual access is powered by **Logic Extensions**, a framework that allows you to hook in and add logic directly to Arcade's execution flow. Arcade calls your server at three predefined hook points in the tool lifecycle:
+Contextual access uses **Logic Extensions**, a framework that allows you to hook in and add logic directly to Arcade's execution flow. Arcade calls your server at three predefined hook points in the tool lifecycle:
 
 ![Contextual Access Flow Diagram](/images/logic-extensions/flow_diagram.png)
 
@@ -51,4 +53,4 @@ You only implement the hooks you need. Configure everything through the Dashboar
     title="API Reference"
     href="/references/contextual-access-webhook-api"
   />
-</Cards>
+</Cards>