feat(financial_insights): Add README entry and tweak skill files for Financial Insights

README.md

@@ -206,6 +206,81 @@ Link is already integrated with the following agents:
 - [Instinct](https://instinct.com)
 - [Browser Use](https://browser-use.com/)
 
+## Financial Insights
+
+Link CLI can also read a consumer's financial data -- transactions, balances, connected account details, and summarized/aggregated financial data. Agents can use these features to understand user preferences for making smarter purchasing decisions, answer personal finance questions, and track trends. Financial Insights are powered by [Financial Connections](https://stripe.com/financial-connections), covering 12,000+ US financial institutions.
+
+
+### Authentication
+Financial Insights requires additional authorization beyond the default; request access to each type of data you want to access on financial data sources:
+
+```bash
+link-cli auth login \
+  --client-name "My Agent" \
+  --scope "userinfo:read" \
+  --source-actions read_link_transactions \
+  --source-actions read_external_transactions \
+  --source-actions read_balances \
+  --source-actions read_source_details
+```
+If already authenticated for payments, use `auth upgrade` to add financial data access without dropping existing scopes.
+
+#### List sources
+
+```bash
+link-cli sources list
+```
+
+Returns connected financial accounts (bank accounts, credit cards, etc.) with metadata, capabilities, and connection status. Use the `id` field as `--source` in other commands.
+
+#### List transactions
+
+```bash
+link-cli transactions list
+```
+
+Supports server-side filtering:
+
+```bash
+link-cli transactions list --start-date 2026-01-01 --end-date 2026-01-31
+link-cli transactions list --category groceries
+link-cli transactions list --origin external_connection
+link-cli transactions list --source <source_id>
+```
+
+| Flag | Description |
+| ---- | ---- |
+| `--start-date` | Only transactions on or after this date (YYYY-MM-DD) |
+| `--end-date` | Only transactions on or before this date (YYYY-MM-DD) |
+| `--category` | Filter by transaction category |
+| `--origin` | `link` (Link-native) or `external_connection` (from linked bank/card) |
+| `--source` | Filter by source ID (repeatable for multiple accounts) |
+| `--limit` | Max results per page (1–100) |
+
+Amounts are integers in the currency's smallest unit. Negative = money leaving the account, positive = money entering. Transactions may be Link-native (processed directly through Link), or sourced through an external connection (e.g. imported from transactions that would appear on a bank statement).
+
+#### Agent integration
+
+The financial-insights skill teaches agents which command to run for each question type, how to handle pagination, interpret amounts, and summarize results. See skills/financial-insights/SKILL.md for the full agent guide.
+
+
+#### List balances
+
+```bash
+link-cli balances list
+link-cli balances list --source <source_id>
+```
+
+Returns current balances for connected accounts, including `cash.available` (bank/savings) or `credit.used` (credit cards).
+
+#### List summaries
+
+```bash
+link-cli summaries list
+link-cli summaries list --summary <summary_id_1> --summary <summary_id_2>
+```
+
+Returns a list of aggregated summaries based on available financial data, for example top brands over the last 6 months. Use this to quickly and token-efficiently extract insights and user preferences from financial data. Add the repeatable `--summary` flag to filter results to a specific set of summaries.
 
 ## Advanced
 

skills/create-payment-credential/SKILL.md

@@ -78,13 +78,46 @@ _Recommended_: Run `link-cli --llms` to understand all the available commands. T
 
 Copy this checklist and track progress:
 
-- Step 1: Authenticate with Link
+- Step 0: Decide whether merchant selection needs personalization
+- Step 1: Authenticate with Link for the whole task
 - Step 2: Evaluate merchant site (determine credential type)
 - Step 3: Get payment methods
 - Step 4: Create spend request with correct credential type
 - Step 5: Complete payment
 
-### Step 1: Authenticate with Link
+### Step 0: Decide whether merchant selection needs personalization
+
+Respect a merchant the user explicitly names; do not retrieve financial insights
+to second-guess that choice.
+
+If the merchant is unspecified and the request involves personal shopping,
+repeat purchasing, "my usual," or choosing a preferred store, also use the
+`financial-insights` skill before selecting a merchant. Use
+`link-cli summaries list` for preference-based selection. Do not retrieve raw
+transactions unless summaries cannot answer the request and transaction-level
+data is genuinely needed.
+
+Examples:
+
+- "Order flour from Smith's Store" -> use Smith's Store without financial insights.
+- "Order some bulk flour" from a personal shopper -> use summaries to inform
+  merchant selection.
+- "Order from my usual baking supplier" -> use summaries to identify the
+  observed preference.
+
+Note that Financial Insights may not be available in the user's country, the user may
+not have any accounts to share, or the user may choose not to share their accounts. 
+If this becomes evident post authentication, proceed without attempting to use Financial
+Insights commands.
+
+### Step 1: Authenticate with Link for the whole task
+
+Before starting authentication, identify all Link capabilities needed for the
+whole task and request them together. When preference-based merchant selection
+is needed, include `read_link_transactions` and
+`read_external_transactions`. If already authenticated without either action,
+use `auth upgrade` for only the missing actions instead of starting another
+login.
 
 Check auth status:
 
@@ -100,6 +133,15 @@ If not authenticated:
 link-cli auth login --client-name "<your-agent-name>"
 ```
 
+When preference-based merchant selection is also needed:
+
+```bash
+link-cli auth login \
+  --client-name "<your-agent-name>" \
+  --source-actions read_link_transactions \
+  --source-actions read_external_transactions
+```
+
 Replace `<your-agent-name>` with the name of your agent or application (for example, `"Personal Assistant"`, `"Shopping Bot"`). This name appears in the user's Link app when they approve the connection. Use a clear, unique, identifiable name.
 
 The response includes a `_next` command — run it to poll until authenticated. If your environment cannot relay the verification code while a separate polling command blocks I/O, use inline polling instead: `auth login --client-name "<name>" --interval 5 --timeout 300`. This yields the code immediately then polls in the same command.

skills/financial-insights/SKILL.md

@@ -2,7 +2,7 @@
 version: 0.15.1
 name: financial-insights
 description: |
-  Reads a user's Link financial data — summaries, transactions, balances, and wallet sources — so agents can answer questions about spending, available source capabilities, and consumer preferences such as favorite brands, restaurants, and local stores. Use when the user says "check my balance", "how much did I spend", "show my transactions", "what accounts are connected", "summarize my spending", "recent purchases", "where do I usually shop", or asks about their financial activity, account balances, preferences, or linked sources. It can also be a source of data about shopping preferences when determining where to go to satisfy a request to make a purchase.
+  Reads Link financial data to answer questions about spending, balances, transactions, linked sources, and shopping preferences. Also use alongside a purchase skill when acting as a personal shopper and the user has not specified a merchant, or asks for their usual, favorite, or preferred store.
 allowed-tools:
  - Bash(link-cli:*)
  - Bash(npx --yes @stripe/link-cli:*)
@@ -64,10 +64,17 @@ Use the minimum required source actions:
 - Transactions processed through Link: `read_link_transactions`
 - Transactions imported from bank connections: `read_external_transactions`
 - Account balances: `read_balances`
-- Data source details and descriptions: `read_source_details`
+- Data source details and descriptions: `read_source_details`. This action is broadly useful, for example if you will ever need to tie a transaction or balance to a particular account name.
 
 If the user asks a question that requires multiple data types, request all relevant actions together.
 
+When this skill is used alongside a purchase workflow, determine all required
+Link capabilities before authenticating and request them in one login. For
+preference-based merchant selection with `summaries list`, request both
+`read_link_transactions` and `read_external_transactions`. If a payment session
+already exists, use `auth upgrade` for only the missing actions; do not start a
+second login.
+
 Example for a new login that needs all financial data types:
 
 ```bash
@@ -108,10 +115,17 @@ Use the smallest command set that answers the user’s question.
 | Current available balance, account balance, cash position | `link-cli balances list` |
 | Connected accounts, cards, banks, wallet sources, source metadata | `link-cli sources list` |
 
+| Operation | Required source actions |
+|---|---|
+| `summaries list` for merchant preferences | `read_link_transactions`, `read_external_transactions` |
+
 Examples:
 
 - “What brands and restaurants do I prefer?” → Use summaries only.
 - "Order flowers from my flower shop" → Use summaries only to identify most frequently used business rather than transactions.
+- "Order flour from Costco" → Respect the named merchant; do not use this skill.
+- "Order some bulk flour" from a personal shopper → Use summaries before choosing a merchant.
+- "Order from my usual baking supplier" → Use summaries to identify the observed preference.
 - “How much did I spend on restaurants last month?” → Use transactions only.
 - “What is my current checking account balance?” → Use balances only.
 - “Which accounts are connected?” → Use sources only.