docs: add provider integration setup guides

docs/concepts/salesforce-integration.md

@@ -12,6 +12,9 @@ useful provider surface for generic Salesforce access. The reason to route
 Salesforce through Veryfront is that customer support agents need a governed
 workflow surface, not only a raw CRM protocol surface.
 
+For installation, OAuth, and service-account setup, see
+[Set up Salesforce](../guides/integrations/salesforce.md).
+
 ## The design choice
 
 Salesforce owns CRM data and CRM permissions. Veryfront owns the agent runtime:

docs/guides/index.md

@@ -64,13 +64,16 @@ details, see [API reference](../api-reference/index.md).
 
 ## Connect external systems
 
-| Goal                                               | Guide                               |
-| -------------------------------------------------- | ----------------------------------- |
-| Sign users in with OAuth                           | [OAuth](./oauth.md)                 |
-| Add connector-backed service tools                 | [Integrations](./integrations.md)   |
-| Expose tools, prompts, and resources to assistants | [MCP server](./mcp-server.md)       |
-| Connect coding agents to the dev server            | [Coding agents](./coding-agents.md) |
-| Run isolated commands or file operations           | [Sandbox](./sandbox.md)             |
+| Goal                                               | Guide                                      |
+| -------------------------------------------------- | ------------------------------------------ |
+| Sign users in with OAuth                           | [OAuth](./oauth.md)                        |
+| Add connector-backed service tools                 | [Integrations](./integrations.md)          |
+| Set up GitHub                                      | [GitHub](./integrations/github.md)         |
+| Set up Jira                                        | [Jira](./integrations/jira.md)             |
+| Set up Salesforce                                  | [Salesforce](./integrations/salesforce.md) |
+| Expose tools, prompts, and resources to assistants | [MCP server](./mcp-server.md)              |
+| Connect coding agents to the dev server            | [Coding agents](./coding-agents.md)        |
+| Run isolated commands or file operations           | [Sandbox](./sandbox.md)                    |
 
 ## Deploy and extend
 
@@ -86,6 +89,6 @@ details, see [API reference](../api-reference/index.md).
 
 ## Troubleshoot
 
-| Goal                                | Guide                             |
-| ----------------------------------- | --------------------------------- |
-| Look up an error slug you were shown | [Error reference](./errors.md)   |
+| Goal                                 | Guide                          |
+| ------------------------------------ | ------------------------------ |
+| Look up an error slug you were shown | [Error reference](./errors.md) |

docs/guides/integrations.md

@@ -146,6 +146,17 @@ No OAuth connect step is shown for these connectors. The integration runtime
 resolves their credentials during tool execution; agents do not receive raw
 secrets.
 
+## Set up a provider
+
+Use a provider guide when a connector needs provider-specific installation,
+permissions, OAuth configuration, or service-account credentials.
+
+| Provider   | Guide                                             |
+| ---------- | ------------------------------------------------- |
+| GitHub     | [Set up GitHub](./integrations/github.md)         |
+| Jira       | [Set up Jira](./integrations/jira.md)             |
+| Salesforce | [Set up Salesforce](./integrations/salesforce.md) |
+
 ## Available integrations
 
 The built-in connector catalog contains 204 connectors. The supported set is
@@ -176,3 +187,13 @@ when you need exact exported names or icon metadata:
 4. Confirm the run retries the tool and receives a non-error result.
 5. Reload the project and confirm connection inventory still reports the
    connection independently of agent source and both policy layers.
+
+## Next
+
+- [Set up GitHub](./integrations/github.md)
+- [Set up Jira](./integrations/jira.md)
+- [Set up Salesforce](./integrations/salesforce.md)
+
+## Related
+
+- [veryfront/integrations](../api-reference/veryfront/integrations.md): Connector catalog and helper API.

docs/guides/integrations/github.md

@@ -0,0 +1,58 @@
+---
+title: "Set up GitHub"
+description: "Connect a GitHub account to Veryfront for repository, issue, and pull-request tools."
+order: 51
+---
+
+Use GitHub OAuth when an agent needs repository, issue, or pull-request tools.
+
+## Connect a GitHub user
+
+1. In Veryfront, open the project that needs GitHub tools.
+2. Start the GitHub connection from the integration prompt or project integration settings.
+3. Sign in to GitHub and approve the requested access.
+4. Run a read-only GitHub tool, such as listing repositories, to verify the connection.
+
+Managed GitHub OAuth works without project credentials. Set project credentials
+only when the project must use its own GitHub OAuth app for custom consent
+branding, verification, or scope requirements.
+
+## Use your own GitHub OAuth app
+
+1. In [GitHub Developer Settings](https://github.com/settings/developers), create an OAuth App.
+2. Add the exact callback URL for the target environment:
+   - Production: `https://api.veryfront.com/oauth/callback/github`
+   - Staging: `https://api.veryfront.org/oauth/callback/github`
+3. These are the hosted Veryfront provider-adapter callbacks. Do not replace
+   them with the `veryfront/oauth` framework callback path. A self-hosted
+   framework application instead registers its own `APP_URL` origin with
+   `/api/auth/github/callback`.
+4. For another hosted environment, copy the callback URL displayed by its
+   Veryfront OAuth connection flow. A GitHub OAuth App can serve more than one
+   route only when GitHub's host, port, and callback-path rules accept the
+   route. The hosted production and staging URLs above do not share a base host,
+   so use separate OAuth Apps for them.
+5. Set the OAuth app client ID and client secret as project environment variables:
+
+| Variable               | Value                          |
+| ---------------------- | ------------------------------ |
+| `GITHUB_CLIENT_ID`     | GitHub OAuth App client ID     |
+| `GITHUB_CLIENT_SECRET` | GitHub OAuth App client secret |
+
+Keep the secret in your approved secret manager. Never place it in agent
+prompts, project files, tickets, or client-side environment variables.
+
+## Verify it worked
+
+1. Start a new agent run that uses a read-only GitHub tool.
+2. Confirm the tool returns the connected user's GitHub data.
+
+## Next
+
+- [Integrations](../integrations.md): Declare GitHub tools and apply source or project policy.
+- [Set up Jira](./jira.md): Connect a Jira provider.
+- [Set up Salesforce](./salesforce.md): Connect a Salesforce provider.
+
+## Related
+
+- [veryfront/integrations](../../api-reference/veryfront/integrations.md): Connector catalog and helper API.

docs/guides/integrations/jira.md

@@ -0,0 +1,60 @@
+---
+title: "Set up Jira"
+description: "Connect an Atlassian account to Veryfront for Jira project and issue tools."
+order: 52
+---
+
+Use Jira OAuth when an agent needs to read or update Jira projects and issues.
+
+## Connect a Jira user
+
+1. In Veryfront, open the project that needs Jira tools.
+2. Start the Jira connection from the integration prompt or project integration settings.
+3. Sign in to Atlassian and approve the requested access.
+4. Run a read-only Jira tool, such as listing accessible sites or projects, to verify the connection.
+
+Managed Atlassian OAuth works without project credentials. Set project
+credentials only for a self-hosted framework deployment that owns one
+distributable Atlassian OAuth app. Hosted Veryfront projects must use the
+managed OAuth connection.
+
+## Use an Atlassian OAuth app in a self-hosted deployment
+
+1. In the [Atlassian developer console](https://developer.atlassian.com/console/myapps/), create an OAuth 2.0 app.
+2. Register your deployment's `APP_URL` origin with
+   `/api/auth/jira/callback`, for example
+   `https://app.example.com/api/auth/jira/callback`.
+3. Grant all four scopes that the Jira connector requests by default:
+   - `read:jira-work` for Jira reads.
+   - `write:jira-work` for write tools.
+   - `read:jira-user` for `jira__search_users`.
+   - `offline_access` to receive refresh tokens. Veryfront uses refresh tokens
+     to keep a user connection active; omit it only when the connection must
+     not be refreshable.
+4. Set the OAuth app client ID and client secret as project environment variables:
+
+| Variable                  | Value                         |
+| ------------------------- | ----------------------------- |
+| `ATLASSIAN_CLIENT_ID`     | Atlassian OAuth client ID     |
+| `ATLASSIAN_CLIENT_SECRET` | Atlassian OAuth client secret |
+
+Set `JIRA_CLOUD_ID` when the connected user has access to more than one
+Atlassian site. Obtain the site ID from the list-sites tool result.
+
+Keep the secret in your approved secret manager. Never place it in agent
+prompts, project files, tickets, or client-side environment variables.
+
+## Verify it worked
+
+1. Start a new agent run that uses a read-only Jira tool.
+2. Confirm the tool returns the expected Atlassian site or Jira project data.
+
+## Next
+
+- [Integrations](../integrations.md): Declare Jira tools and apply source or project policy.
+- [Set up GitHub](./github.md): Connect a GitHub provider.
+- [Set up Salesforce](./salesforce.md): Connect a Salesforce provider.
+
+## Related
+
+- [veryfront/integrations](../../api-reference/veryfront/integrations.md): Connector catalog and helper API.

docs/guides/integrations/salesforce.md

@@ -0,0 +1,97 @@
+---
+title: "Set up Salesforce"
+description: "Install and connect the Veryfront Salesforce integration with per-user OAuth or a service account."
+order: 50
+---
+
+Use this guide to connect a Salesforce org to Veryfront. Choose per-user OAuth
+when each action must use an individual's Salesforce access. Choose a service
+account for scheduled or project-owned automation.
+
+## Prerequisites
+
+- A Salesforce administrator for the target org.
+- A Veryfront project with Salesforce tools declared in an agent.
+- The hosted Veryfront API, which supplies the Salesforce provider adapter. The
+  generic Veryfront runtime cannot scaffold or execute Salesforce OAuth routes.
+  An embedding host that supplies its own Salesforce adapter must declare
+  `VERYFRONT_HOST_ADAPTER_INTEGRATIONS=salesforce` to expose the connector
+  catalog. This does not enable generic Salesforce scaffolding.
+
+## Connect a Salesforce user
+
+Install the **Veryfront Salesforce Integration** package in each Salesforce
+org that users connect to Veryfront. Salesforce External Client Apps are scoped
+to an org. Without the installed package, Salesforce rejects a cross-org
+authorization request.
+
+1. Sign in to the Salesforce org as an administrator.
+2. Open the [Veryfront Salesforce Integration beta installation page](https://login.salesforce.com/packaging/installPackage.apexp?p0=04tfj000000RX37AAG).
+3. Select **Install for Admins Only** and acknowledge that the application is not distributed through AppExchange.
+4. Wait for the installation to complete.
+5. In Salesforce Setup, open **External Client App Manager** and select **Veryfront**.
+6. Confirm that the app is **Packaged (Installed)** and **Enabled**.
+7. Under **Policies**, select the permitted-users policy. The beta package permits all users to self-authorize. Restrict access to the required profile or permission set when the org uses a tighter access policy.
+
+Install the beta package in a sandbox or test org before installing it in a
+production Salesforce org.
+
+In Veryfront, open the project and start the Salesforce connection from the
+integration prompt or project integration settings. Sign in to the Salesforce
+org where the package is installed, approve consent, then run a read-only
+Salesforce tool to verify access.
+
+Never paste a Salesforce consumer secret into an agent prompt, project file,
+ticket, or client-side environment variable.
+
+## Use a service account
+
+Use a service account when a run needs non-interactive access. Veryfront uses
+Salesforce OAuth client credentials and executes as the Connected App's
+dedicated **Run As** integration user. It does not open browser consent or use
+a user's personal OAuth token.
+
+In the target Salesforce org:
+
+1. Create a dedicated integration user with the minimum object, field, and API permissions required by the project.
+2. Create or configure a Salesforce Connected App for the client-credentials flow.
+3. Enable **Client Credentials Flow** and select the **Manage user data via APIs** (`api`) OAuth scope.
+4. In the Connected App policy, set permitted users to **Admin approved users are pre-authorized**, then select the dedicated integration user as the **Run As** user.
+5. Record the Connected App consumer key and consumer secret in your approved secret manager.
+
+Set all three values as project environment variables in the matching
+Veryfront environment:
+
+| Variable                                   | Value                         |
+| ------------------------------------------ | ----------------------------- |
+| `SALESFORCE_SERVICE_ACCOUNT_CLIENT_ID`     | Connected App consumer key    |
+| `SALESFORCE_SERVICE_ACCOUNT_CLIENT_SECRET` | Connected App consumer secret |
+| `SALESFORCE_SERVICE_ACCOUNT_LOGIN_URL`     | Salesforce My Domain origin   |
+
+Set `SALESFORCE_SERVICE_ACCOUNT_LOGIN_URL` to the target org's Salesforce My
+Domain origin, for example `https://acme.my.salesforce.com`. Veryfront rejects
+generic login endpoints such as `https://login.salesforce.com` and
+`https://test.salesforce.com`; it also rejects paths and non-HTTPS URLs. Use
+the My Domain origin, not the instance URL returned after authentication.
+
+All three variables are required. If any service-account variable is missing,
+Veryfront fails closed and does not fall back to a human OAuth connection for
+non-interactive runs. Rotate the consumer secret in Salesforce and update the
+project environment variable through the approved secret-management workflow.
+
+## Verify it worked
+
+1. Start a new agent run that uses a read-only Salesforce tool, such as account or case lookup.
+2. Confirm the tool returns data from the target Salesforce org.
+3. For a service account, confirm the Salesforce audit trail attributes the request to the configured integration user.
+
+## Next
+
+- [Integrations](../integrations.md): Declare Salesforce tools and apply source or project policy.
+- [Set up GitHub](./github.md): Connect a GitHub provider.
+- [Set up Jira](./jira.md): Connect a Jira provider.
+
+## Related
+
+- [veryfront/integrations](../../api-reference/veryfront/integrations.md): Connector catalog and helper API.
+- [Salesforce integration](../../concepts/salesforce-integration.md): Why Veryfront uses a governed Salesforce integration layer.

tests/docs/guide-contracts.test.ts

@@ -553,6 +553,38 @@ const GUIDE_CONTRACTS: Record<string, GuideContract> = {
       "Available integrations",
     ],
   },
+  "guides/integrations/github.md": {
+    references: ["../../api-reference/veryfront/integrations.md"],
+    snippets: [
+      "Connect a GitHub user",
+      "https://api.veryfront.com/oauth/callback/github",
+      "GITHUB_CLIENT_ID",
+      "Verify it worked",
+    ],
+  },
+  "guides/integrations/jira.md": {
+    references: ["../../api-reference/veryfront/integrations.md"],
+    snippets: [
+      "Connect a Jira user",
+      "/api/auth/jira/callback",
+      "read:jira-user",
+      "ATLASSIAN_CLIENT_ID",
+      "JIRA_CLOUD_ID",
+    ],
+  },
+  "guides/integrations/salesforce.md": {
+    references: [
+      "../../api-reference/veryfront/integrations.md",
+      "../../concepts/salesforce-integration.md",
+    ],
+    snippets: [
+      "Connect a Salesforce user",
+      "VERYFRONT_HOST_ADAPTER_INTEGRATIONS=salesforce",
+      "SALESFORCE_SERVICE_ACCOUNT_CLIENT_ID",
+      "Admin approved users are pre-authorized",
+      "Verify it worked",
+    ],
+  },
   "guides/runs.md": {
     references: ["../api-reference/veryfront/runs.md"],
     snippets: [