docs: add Global Accounts agent guides

mintlify/docs.json

@@ -91,6 +91,14 @@
               "global-accounts/exporting-wallet"
             ]
           },
+          {
+            "group": "Agents (experimental)",
+            "pages": [
+              "global-accounts/agents/overview",
+              "global-accounts/agents/policies-and-permissions",
+              "global-accounts/agents/approvals-and-audit"
+            ]
+          },
           {
             "group": "Platform tools",
             "pages": [

mintlify/global-accounts/agents/approvals-and-audit.mdx

@@ -0,0 +1,126 @@
+---
+title: "Approvals & audit"
+description: "Design approval, activity, and revoke experiences for agent-driven Global Account flows"
+icon: "/images/icons/receipt-check.svg"
+"og:image": "/images/og/og-global-accounts.webp"
+---
+
+<Note>
+Agent connectivity is currently limited availability. To request access, [book a demo](https://www.lightspark.com/contact) or reach out to your Lightspark contact.
+</Note>
+
+Use this page to design how permission requests, decisions, and agent history appear in your app or dashboard. The connected agent may run outside both Grid and your product, but Grid owns approval state, execution gating, and audit history while your surfaces present those requests and records to the user.
+
+<Info>
+Treat approval requests like first-class user tasks. They should be easy to find, easy to understand, and safe to retry without duplicating execution.
+</Info>
+
+## Approval lifecycle
+
+When an agent requests an action that is not eligible for automatic execution:
+
+1. Grid creates a permission request for your product.
+2. Grid dispatches that request to your product, typically via webhook or another configured callback mechanism.
+3. Your app or dashboard shows the user the requested amount, source account, destination, and reason.
+4. The user approves or rejects the action from that trusted surface.
+5. Grid executes or rejects the action based on the latest account and policy state.
+6. Grid records the final status and links it to the resulting transaction or quote execution.
+
+## Approval outcomes
+
+An approval request shown to the user is still subject to the latest account and policy state when Grid processes the decision.
+
+For example, between the original request and the final decision:
+
+- The agent may have been paused
+- The customer's limits may have been reduced
+- The permitted accounts may have changed
+- Another action may already have consumed the available daily spend
+
+<Warning>
+An approval in your UI is not always a guarantee that the original request will execute successfully. Your product should be ready to show a final rejected or failed state if the request is no longer valid when Grid processes it.
+</Warning>
+
+## Activity and audit records
+
+The activity and audit data returned by Grid makes it easy for customers and operators to understand both intent and outcome.
+
+Each activity record captures:
+
+- Agent ID and display name
+- Action type
+- Requested amount and asset
+- Source and destination context
+- Reason or natural-language detail
+- Policy decision
+- Approval status
+- Linked Grid quote ID or transaction ID, when available
+- Created, approved, rejected, and completed timestamps
+
+For example, a permission request surfaced in your product might look like:
+
+```json
+{
+  "id": "Approval:019542f5-b3e7-1d02-0000-000000000099",
+  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
+  "status": "PENDING",
+  "actionType": "EXECUTE_QUOTE",
+  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000025",
+  "source": {
+    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
+    "currency": "USD"
+  },
+  "destination": {
+    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
+    "currency": "EUR"
+  },
+  "sendingAmount": {
+    "amount": 50000,
+    "currency": {
+      "code": "USD",
+      "decimals": 2
+    }
+  },
+  "description": "Send supplier payout",
+  "policyDecision": "APPROVAL_REQUIRED",
+  "createdAt": "2025-10-03T15:00:00Z"
+}
+```
+
+This lets you present a clean customer-facing activity feed while preserving an operator-friendly audit trail.
+
+## Pause and revoke
+
+Customers need immediate control over delegated access.
+
+Support at least two controls:
+
+- `Pause`: temporarily block new executions while preserving the agent configuration.
+- `Revoke`: permanently remove delegated access and invalidate the agent connection.
+
+Pause is useful for temporary uncertainty. Revoke is appropriate when a device is lost, a credential is exposed, or the customer no longer wants the agent connected.
+
+Grid enforces these controls. Your product should surface the current connection state and expose the relevant actions in your own experience.
+
+## What to show in the approval UI
+
+Your approval UI should answer:
+
+- What is the agent trying to do?
+- Which account is affected?
+- How much value is moving?
+- Who or what is on the other side of the transaction?
+- Why is approval required?
+
+If the user cannot answer those questions quickly, the approval surface is too opaque.
+
+## Integration guidance
+
+- Use Grid events or webhooks to reconcile approval decisions with the final activity and transaction state.
+- Treat approval decisions as idempotent in your integration so duplicate taps or retries do not create a confusing UX.
+- Preserve status history in your UI instead of collapsing everything into a single final state.
+- Make agent connection status, approval queue state, and audit history easy to surface in your apps and dashboards.
+
+<Tip>
+Show approvals and audit history close to the account or transaction views users already trust. That reduces confusion and makes agent activity feel like part of the main account lifecycle rather than a separate subsystem.
+</Tip>

mintlify/global-accounts/agents/overview.mdx

@@ -0,0 +1,110 @@
+---
+title: "Overview"
+description: "Experimental native Grid functionality for connecting AI agents to Global Accounts with managed policy and approval flows"
+icon: "/images/icons/agent.svg"
+"og:image": "/images/og/og-global-accounts.webp"
+---
+
+import { FeatureCard, FeatureCardGrid } from '/snippets/feature-card.mdx';
+
+<Note>
+This section describes experimental Grid functionality. Details may evolve as the agent product surface expands. Agent connectivity is currently limited availability. To request access, [book a demo](https://www.lightspark.com/contact) or reach out to your Lightspark contact.
+</Note>
+
+Use Grid-managed agent connectivity to let your users connect AI agents to Global Accounts. The connected agent may run in your product, on the user's device, or through a third-party tool such as OpenClaw or Codex. Grid does not run the agent runtime. Grid powers install, delegated credentials, policy evaluation, approval state, and execution boundaries for agent-initiated actions, while your product surfaces the connection, approval, and history experience to the end user.
+
+<video
+  controls
+  className="w-full aspect-video rounded-xl"
+  src="https://lightspark-web.cdn.prismic.io/lightspark-web/afPmC8BOoF08xhlu_gga-agent-demo-4k.mp4"
+>
+  Your browser does not support the video tag.
+</video>
+
+## Design principles
+
+<FeatureCardGrid cols={2}>
+  <FeatureCard icon="/images/icons/shield.svg" title="Customer-owned funds">
+    Delegation does not transfer account ownership. The customer can still require approvals, pause access, or revoke the agent entirely.
+  </FeatureCard>
+  <FeatureCard icon="/images/icons/IconSquareChecklistMagnifyingGlass.svg" title="Grid-managed policy">
+    Permissions, spend limits, account restrictions, and approval thresholds are evaluated by Grid before any agent-initiated action executes.
+  </FeatureCard>
+  <FeatureCard icon="/images/icons/agent.svg" title="Bounded execution">
+    Agents operate with a narrow, explicit capability set such as viewing balances, preparing withdrawals, or initiating transfers under Grid-defined controls.
+  </FeatureCard>
+  <FeatureCard icon="/images/icons/bell.svg" title="Auditable activity">
+    Every agent-initiated action stays traceable through Grid policy decisions, approval state, and final settlement outcomes.
+  </FeatureCard>
+</FeatureCardGrid>
+
+## How it works
+
+In this model:
+
+- The customer still owns the Global Account and remains the ultimate authority over outbound movement.
+- You let users connect one or more AI agents they already use to their Grid-backed account experience.
+- The connected agent may run in your app, on the user's device, or through a third-party tool.
+- Grid powers agent install and delegated credentials for the connected agent.
+- Grid manages the agent's allowed capabilities, evaluation rules, and approval requirements.
+- The agent can propose or execute only the actions Grid allows for that customer and account scope.
+- Your surfaces remain the place where users view connection status, review permission requests, and inspect agent history.
+
+## System flow
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant P as Partner app
+    participant G as Grid
+    participant A as Connected agent
+
+    U->>P: Connect agent
+    P->>G: Start Grid-powered install flow
+    G-->>P: Agent connection + delegated credentials
+    A->>G: Request action
+    Note over G,P: If approval is required
+    G-->>P: Permission request
+    P-->>U: Show approval UI
+    U->>P: Approve or reject
+    P->>G: Send decision
+    G-->>P: Action executed automatically or after approval
+    G-->>P: Activity, transaction, and audit updates
+```
+
+## Typical flow
+
+1. Your platform creates or links a Global Account for the customer.
+2. The customer connects an existing agent through a Grid-powered install flow embedded in your product.
+3. Grid creates the agent connection, provisions delegated credentials, and saves the configured policy.
+4. The agent requests an action such as creating a quote, creating an external account, or executing a withdrawal.
+5. Grid applies the saved policy for that connection.
+6. The request is either denied, executed automatically, or delivered to your product as a permission request.
+7. Your user reviews the request in a trusted surface you control.
+8. Grid then sends the resulting activity, transaction, and settlement updates back to your product.
+
+## Where Global Accounts fits
+
+This functionality is a natural extension of Global Accounts because outbound money movement already assumes customer-level authorization. Agent access adds a delegated actor while preserving the user's ownership and approval model.
+
+## What you surface
+
+Your product should surface:
+
+- Agent connection state and metadata
+- Policy configuration and permissions screens
+- Approval and decision UX presented to end users on demand
+- Agent activity, audit records, and transaction history
+- Consumption of Grid events, webhooks, or approval callbacks
+- Customer messaging and notification design
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Policies & permissions" href="/global-accounts/agents/policies-and-permissions" icon="shield-check">
+    Define what a connected agent can do, which accounts it can access, and when Grid requires approval.
+  </Card>
+  <Card title="Approvals & audit" href="/global-accounts/agents/approvals-and-audit" icon="receipt">
+    Design the approval and history experience your users see in your app or dashboard.
+  </Card>
+</CardGroup>