opencode-knowledge-work 0.0.0-stage → 0.1.1

package/content/small-business/skills/small-business-build-connector/reference/paths.md

@@ -0,0 +1,106 @@
+# Build Paths
+
+Options in order of preference. Prefer the boring one — the owner cannot debug a clever integration that fails in November.
+
+**There is no direct-API build path.** Even when a tool has a clean, documented REST API, do not hand-build a connector against it: that code becomes the business's to maintain — token plumbing, rate limits, silent vendor changes — and nobody here will maintain it. When the Claude connector directory has nothing, the build path is Zapier.
+
+---
+
+## 1. Existing Claude connector / MCP server
+
+**When:** one exists in the Claude connector directory (or the MCP registry) and covers the need.
+
+Always first choice. Someone else maintains it, it survives vendor API changes, and there is nothing custom to break.
+
+Work: install, authenticate, verify scope. Usually minutes.
+
+---
+
+## 2. Zapier connection
+
+**When:** nothing in the directory, and the tool is one of Zapier's 8,000+ apps. This is the build path when the directory has nothing; the mechanics are in `use-zapier.md`.
+
+Good for: "when a work order is created, do X." Zapier handles the trigger and the plumbing.
+
+Poor for: bulk historical pulls, or anything high-volume. Zapier bills per task and the arithmetic gets bad quickly.
+
+**Say the cost out loud.** An owner who discovers a USD 70 monthly Zapier bill they didn't expect blames the integration, and they are not wrong to.
+
+```
+This works through Zapier. Roughly 40 tasks a day at your volume, which is
+their USD 30 tier. Fine if that's worth it — worth knowing before we build.
+```
+
+---
+
+## 3. Scheduled export
+
+**When:** not in the directory and not on Zapier, but the system can email or drop a file on a schedule.
+
+**Underrated.** No tokens to expire, no rate limits, no API changes. For a once-daily need it is often strictly better than a live integration.
+
+Set up:
+
+1. Configure the export in the source system — daily, to a specific address
+2. Watch that inbox for the file
+3. Parse and use it
+
+The main weakness is latency. A daily export cannot support anything needing same-hour data. Say so rather than letting the owner discover it.
+
+**The failure mode is quiet.** If the export stops arriving, nothing errors — the data just goes stale. Build in a check: if no file has arrived in longer than the expected interval, say so loudly.
+
+---
+
+## 4. Screen-level workaround
+
+**When:** everything else failed and the need is real.
+
+Fragile by nature. It breaks whenever the vendor changes their interface, which they do without warning.
+
+Only appropriate when:
+
+- The data genuinely cannot be reached another way
+- The need is significant enough to justify the maintenance
+- The owner understands it will break, and roughly how often
+
+Say it plainly:
+
+```
+This would work, but it's held together with tape — any interface change on
+their side breaks it, and you'd have no warning beyond the data stopping.
+
+Before we go there: can you export this manually once a week? Less clever,
+but it'll still work next year.
+```
+
+Recommending the manual export over the fragile automation is usually the right call, and owners respect being told.
+
+---
+
+## Choosing when several work
+
+| Priority | Reasoning |
+|---|---|
+| Fewest moving parts | Every component is something that can break unmonitored |
+| Nothing to maintain | The owner cannot debug it and will not pay someone to |
+| Fails loudly | Silent failure is worse than no connector |
+| Read-only where possible | Narrower access, smaller consequences |
+| No per-task cost | Unless the owner has agreed to it |
+
+**A daily CSV that always works beats a live API that breaks quarterly.** The owner's actual requirement is that their morning brief is right, not that the integration is elegant.
+
+---
+
+## Scoping the build
+
+Whatever the path, build only what was scoped.
+
+```
+Bad:  Connect ServiceTrade.
+Good: Pull open work orders daily, with customer, description, and assignee,
+      so they appear in the morning brief.
+```
+
+The second is buildable this afternoon and testable against a known answer. The first is a project with no definition of done.
+
+More endpoints can be added when something needs them. Building the whole API surface up front means securing and maintaining code nothing uses.

package/content/small-business/skills/small-business-build-connector/reference/use-zapier.md

@@ -0,0 +1,128 @@
+# Use Zapier
+
+The build path when discovery turned up no native Claude connector. This file covers using the Zapier MCP server itself: authenticating, checking whether an app or action exists, connecting the app's account, enabling exactly the actions the scope named, testing against the owner's actual use case from Step 1 of the skill, and the task bill.
+
+---
+
+## Two modes — say which one, out loud
+
+**On-demand actions (the default).** Zapier's MCP server exposes the tool's actions and Claude calls them only when a skill runs. Nothing is scheduled, nothing polls, no Zap exists in the owner's dashboard, and tasks burn only on actual use. This is what most scopes need — a lead pull when the morning brief runs, a record lookup when the owner asks. Every step below is this mode.
+
+**A Zap (the exception).** A standing automation on Zapier's side that runs without Claude — event fires, Zap acts, around the clock. Build one only when the owner needs something to happen while nobody is talking to Claude. It keeps running and billing on its own, so it gets named in the consent step explicitly, named so it is identifiable in the owner's dashboard six months from now ("Claude: ServiceTrade open work orders," not "Zap 47"), and turned on only after a test run passes.
+
+Owners hear "Zapier" and picture Zaps. If the build is on-demand actions, say so — "no Zaps, nothing runs in the background, Zapier is just the pipe" — or the owner will wonder what invisible machinery got installed.
+
+---
+
+## Step 1 — Authenticate to Zapier
+
+Check whether this is already connected before doing anything else: call `ToolSearch` for `discover_zapier_actions`. If it doesn't resolve — only an `authenticate` / `complete_authentication` pair of tools show up — Zapier isn't connected yet.
+
+**If not connected:** call the platform's Zapier authentication tool. It returns an authorization URL — share it with the owner and ask them to complete it in their browser. The rest of the tool set becomes available automatically once they finish. If the redirect page errors out, have the owner retry from the connector's own settings page; never ask them to paste the callback URL or an authorization code into chat — that puts a credential in the transcript, which Step 3 of the skill forbids.
+
+This authenticates the Zapier platform connection only — it is **not** yet the specific app (ServiceTrade, QuickBooks, whatever). That's Step 3, below, and it's a separate step per app.
+
+---
+
+## Step 2 — Check whether the app and action exist
+
+Call `discover_zapier_actions` with the exact product name from Step 1 of the skill, and read back the counts: read/write/search action totals and category. If nothing comes back, the app isn't on Zapier — continue with `discovery.md`, section 3. **`selected_api` must come verbatim from this call — never guess or construct it.** Zapier's own example: Gmail is `GoogleMailV2CLIAPI`, not `GmailCLIAPI`.
+
+Then pick the actions from the scope, not from the app page: find the one search or read action, and the fewest write actions, that deliver exactly what Step 1 defined, and ignore everything else the app offers. Check each action's fields before promising anything — if the owner's scope needs a field the action doesn't return, that is a deviation to surface before building, not after. An app that is on Zapier but lacks the specific action the scope needs is not a match; say why, plainly, and continue with `discovery.md`, section 3.
+
+---
+
+## Step 3 — Connect the app's own account
+
+Call `manage_zapier_connections` with the `selected_api` from Step 2 to check the connection. If none exists yet, it returns an auth URL (Zapier calls it `connectAuthUrl` in its own error text) — share it with the owner and ask them to confirm once they've connected on Zapier's page. The owner signs into their tool on Zapier's page, never in chat; nothing can run until they do, which makes the click the natural consent moment. Then:
+
+1. Call `list_zapier_connections` to find the new `connection_id`.
+2. Call `manage_zapier_connections` again with that `connection_id` as `default_connection_id`. **An app requires a default connection before any of its actions can run — even with only one connection.** This is by design: Zapier makes the owner choose consciously rather than picking one silently when multiple accounts exist.
+3. **If the owner has multiple accounts for the same app** (two Slack workspaces, a personal and a work Gmail), don't fight over which one is default — pass that connection's specific `connection_id` on each `execute_zapier_read_action` / `execute_zapier_write_action` call instead.
+
+---
+
+## Step 4 — Enable the action, then trim to the scope
+
+Call `enable_zapier_action` with the `selected_api` and the specific action Step 2 chose, plus `app_display_name` so confirmations read as "Gmail," never a raw API ID.
+
+**Enabling does not behave like a menu.** An enable call with no action named turns on every action the app has — including delete, send-email, and raw API request — and enabling one action can switch on a related bundle (asking for one "find" action may enable four). So, every time: enable, then call `inspect_zapier_actions` to read back what is actually on, then `disable_zapier_action` for everything the scope didn't name. The shipped list matches the approved scope exactly — an owner who approved read-only lead pulls must not end up with a live delete action they never heard about.
+
+If a call still fails with a message like:
+
+```
+No default connection is set for Outreach, which is required before running
+its actions.
+```
+
+Step 3 above wasn't completed — the error message itself names the fix; follow it rather than treating it as a dead end.
+
+---
+
+## Step 5 — Test against the owner's actual use case
+
+1. Call `inspect_zapier_actions` with the `tool_name` for the read action Step 2 chose, to get its exact parameter schema.
+2. **Resolve ambiguous matches carefully.** If the owner gave partial or ambiguous information — a first name, a search term with several close matches — a lookup returning one result is not proof it's the right one. Enumerate the candidates and let the owner pick rather than guessing.
+3. Call `execute_zapier_read_action`, show the real data it pulled, and ask if it's correct. That's the only way to confirm the connection is reading their actual data and nothing quietly wasn't mapped.
+
+**Write actions get the same scrutiny plus a confirmation gate.** They have real, often irreversible side effects — confirm the target whenever there's any doubt, and every write gets an approval gate regardless of what the owner asked for.
+
+---
+
+## Estimating the task bill
+
+Zapier bills per task — roughly, every `execute_zapier_*_action` call that runs. The estimate goes in front of the owner before any build.
+
+1. **Volume:** how many calls per month, from the owner's own numbers in Step 1. 40 work orders a day is about 1,200 a month.
+2. **Tier:** see `zapier.com/pricing.md` for current plans and task allowances. **Never quote pricing from memory** — Zapier changes tiers and allowances regularly.
+3. **Overage:** say what happens past the limit — plans differ on whether calls pause or bill as overage. A paused plan is silent; see "How this breaks."
+
+**If it is a Zap,** the arithmetic changes: every action step that runs on every record that gets through is a task, so count steps per event, and put a Filter by Zapier step immediately after the trigger, before any action that costs a task, on the narrowest condition the scope defines. Filtered-out runs are cheaper than full runs, and most scopes only want a subset (open work orders, not all work orders). That filter is the single biggest lever on the monthly bill.
+
+If the volume makes per-task billing absurd — a nightly pull of two thousand records — stop and say so plainly rather than presenting a bad Zapier bill as the only option. This is still not a reason to hand-build against the app's raw API; a scheduled export (`discovery.md`, section 4) is usually the right answer at that volume.
+
+---
+
+## How this breaks
+
+- **The owner disconnects the app account inside Zapier**, which breaks every call using that connection at once.
+- **Zapier deprecates a trigger or action version**, usually with notice in their changelog and nowhere the owner looks.
+- **The task limit is reached**, which can block calls silently depending on the owner's plan settings.
+
+The failure signature is the same for all three: nothing errors, it just produces nothing. **Empty output from a Zapier action is broken until proven empty** — check `inspect_zapier_actions` (or, for a Zap, its run history) before reporting "no records."
+
+---
+
+## The tool set
+
+| Tool | Does |
+|---|---|
+| `discover_zapier_actions` | Searches Zapier's app catalog — `app` is a free-text query |
+| `inspect_zapier_actions` | Inspects currently enabled apps/actions and resolves the exact schema before executing. Call this before every execute call — never guess action names, they aren't intuitive and will fail |
+| `enable_zapier_action` | Enables an action for an app, using the `selected_api` from `discover_zapier_actions` |
+| `disable_zapier_action` | Removes an action — the trim step after every enable |
+| `list_zapier_connections`* | Lists the owner's connected accounts for an app |
+| `manage_zapier_connections`* | Connects a new account and/or sets the app's default connection |
+| `execute_zapier_read_action` | Runs a search/read action |
+| `execute_zapier_write_action` | Runs a write/create action — real, often irreversible side effects |
+
+\* Not documented in `docs.zapier.com/mcp/how-tools-work.md` (see References below), and what Step 3 depends on.
+
+Zapier's own tool descriptions sometimes reference an old name, `list_enabled_zapier_actions` — that tool no longer exists; use `inspect_zapier_actions` instead.
+
+---
+
+## References
+
+**Zapier:**
+
+- `zapier.com/apps/<slug>/integrations.md` — per-app triggers and actions
+- `zapier.com/pricing.md` — current plan tiers and task billing
+- `zapier.com/llms.txt` — Zapier's machine-readable documentation index
+- `zapier.com/.well-known/ai-catalog.json` — Zapier's discovery manifest for its MCP server, SDK, and app directory
+- `docs.zapier.com/mcp/how-tools-work.md` — the meta-tools referenced above, markdown mirror
+
+**Claude:**
+
+- `code.claude.com/docs/en/mcp.md` — how Claude Code connects to and manages MCP servers, markdown mirror
+- `support.claude.com/en/articles/13837440-use-plugins-in-claude` — how plugins, including bundled connectors, work in Claude Cowork specifically

package/content/small-business/skills/small-business-business-pulse/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: business-pulse
+description: >
+  Produces a one-page cross-functional business snapshot for SMB owners —
+  cash position (the ledger: MYOB, NetSuite, QuickBooks, Xero, or Zoho Books), sales trend
+  (PayPal/Square/Stripe), pipeline movement (HubSpot), this week's commitments
+  (Calendar), urgent watch-list items (Gmail or M365, Slack), and the single most
+  important thing needing attention today.
+  Proactively tries every available connector and gracefully scopes to
+  whatever is connected — one connector gives a partial pulse; the full stack
+  gives the full picture. Trigger when the user asks how the business is
+  doing, wants a snapshot, a daily brief, a Friday recap, or says anything
+  like "what am I missing" or "catch me up on the business." A start-of-week
+  briefing routes to /monday-brief, which runs this skill as its first link.
+allowed-tools: Read, WebFetch
+---
+
+# Business Pulse
+
+One prompt, one page. Pull live data from every connected tool, synthesize it into a single scannable brief, and surface the single most important thing to act on today. Do the work — don't ask the user to help find the data.
+
+## Step 1 — Pull data in parallel
+
+**Dispatch all connector calls in a single parallel batch** — see `reference/data_sources.md` for the exact tool-to-metric mapping. Do not pull serially; latency turns a 30-second skill into a painful wait.
+
+Connectors to attempt simultaneously:
+
+- **QuickBooks** — cash balance, MTD revenue, outstanding receivables, overdue invoices
+- **Xero** — same ledger read for Xero shops: cash position, receivables, P&L trend
+- **Zoho Books** — same ledger read for Zoho shops: bank balances, invoiced revenue, overdue invoices (no P&L endpoint, so the revenue line is invoiced revenue and says so)
+- **PayPal / Square** — 7-day settlements, sales trend, failed/pending transactions
+- **Stripe** — settlements and sales trend, failed payments, and any new disputes — a fresh dispute goes straight to the watch list (if connected)
+- **Ramp** — company card spend for the week and the account balance, read-only (if connected)
+- **Gusto** — next payroll run date and amount, the week's biggest cash commitment (if connected)
+- **TikTok Ads** — last week's ad spend, results, and cost per result, so paid spend shows up next to the sales it claims to drive (if connected)
+- **Expensify** — last week's card spend and any expenses missing receipts, read-only, so spending surprises surface before the month-end scramble (if connected)
+- **HubSpot** — pipeline by stage, deals moved/closed, deals gone cold, new leads
+- **Google Calendar** — key meetings, deadlines, events this week and next 7 days
+- **Gmail or Microsoft 365** — threads flagged urgent, customer complaints, time-sensitive requests
+- **Slack / Teams** — urgent internal signals, threads needing owner attention
+- **RingEx Chat** — the same internal-signal read for RingEx shops: urgent team-chat posts needing the owner (if connected)
+- **DocuSign** — envelopes sitting unsigned, flagged once they are more than a few days old — money waiting on a signature (if connected)
+- **Zoho Desk** — open tickets, escalations (if connected)
+- **Shopify** — orders, revenue, sales trend, and fulfillment issues, so a commerce business sees its actual day (if connected)
+- **Square** — fulfillment issues (if connected)
+
+If a connector errors or returns no data, record it internally and move on. Never block the pulse on a single bad integration.
+
+**QuickBooks fallback**: if QBO returns an unexpected state (account not connected, sync pending, empty response), mark the Cash section "n/a — QuickBooks unavailable" and proceed. Do not retry or ask the user to reconnect.
+
+**Gmail fallback**: Gmail auth is intermittently flaky. If the call errors, skip the Watch List section silently and note "Gmail unavailable" in the appendix — do not surface an error mid-pulse.
+
+**Nothing connected at all is a supported path, not a failure.** If every connector is unavailable, don't stop and don't tell the owner to go connect things. Ask once, in one short message, for the handful of numbers that carry the pulse:
+
+- Cash in the bank right now, and roughly what it was a week ago
+- Anything overdue — invoices owed to them, bills they owe
+- Sales this week versus a normal week, even roughly
+- Anything already worrying them this week
+
+Build the same one-page pulse from those answers, label the source line "owner-supplied, not pulled," and skip any section they had no number for. If they'd rather not type numbers, point them at the siblings that run off a file export instead — `cash-flow-snapshot` and `report-builder` both take a CSV — and say plainly that gives a partial picture, not the full one.
+
+## Step 2 — Compute metrics
+
+Read `reference/thresholds.md` for red/yellow/green cutoffs. Compute:
+
+- **AR aging** — open QuickBooks invoices grouped by days since due date (0–30, 31–60, 61+)
+- **Pipeline coverage** — HubSpot weighted pipeline ÷ monthly revenue target
+- **Revenue trend** — this month's QBO revenue vs. prior month (or 7-day PayPal/Square vs. prior 7 days)
+
+Assign a 🟢/🟡/🔴 status to each section. If a source returned nothing, mark the metric "n/a" and note it in the appendix.
+
+## Step 3 — Flag risks proactively
+
+Scan for actionable items. Every risk entry must name a specific record and a next step — "some overdue invoices" is useless; "USD 3,400 from Acme Corp, 47 days overdue, no response since Mar 12" is actionable.
+
+- Ledger invoices past due > 30 days — name customer, amount, days overdue
+- HubSpot deals with no activity in 7+ days, or close date in past but still open
+- Mail threads marked urgent or containing "escalation," "complaint," "cancel," "refund"
+- Failed or pending PayPal/Square/Stripe transactions above the threshold in `reference/thresholds.md` (200 in the business's currency)
+
+## Step 4 — Compose the output
+
+Use the exact template in `reference/output_template.md`. Include only sections where real data exists — omit headers for connectors that weren't available. Adapt depth to context: a casual "how are we doing" gets a fuller report; "quick snapshot before a call" gets a tighter one.
+
+Cross-connector synthesis is where this skill earns its keep. If a Slack message connects to a stalled HubSpot deal, surface that link in the #1 Priority section. Synthesis is what makes the pulse more useful than checking each tool separately.
+
+Writing rules:
+- Numbers lead, words follow. Never write "revenue is healthy" — write "USD 43k this month, ▲ 8% MoM" and let the owner judge.
+- Every number carries a delta vs. the prior period where available. Absolute snapshots (cash balance) still show WoW delta.
+- Names and dollars, not adjectives. "USD 4,200 from Acme, 23 days overdue" beats "some concerning receivables."
+- No filler. If a section has nothing worth reporting, write "No material changes" and move on.
+
+## Step 5 — Deliver the pulse page
+
+Alongside the chat pulse — never instead of it — deliver the full pulse per
+the owner's stored output preference — never default to a markdown file.
+Check the `## Business context` block's `Output preference` (shared style
+guide rule, `../../shared/artifact-style.md`):
+
+- **Visual artifact (the default):** render the pulse as an HTML page in the
+  house style. Cash balance, MTD revenue, and weighted pipeline are stat tiles
+  with their deltas as context lines; each section's 🟢/🟡/🔴 becomes a status
+  pill (good, warn, critical); the watch-list risks are a table with
+  tabular-nums amount columns; the #1 Priority gets its own panel at the top;
+  unavailable connectors go in one quiet appendix line.
+- **docx / md / notion / canva preference:** deliver the same content in that
+  form — a DOCX or markdown file, a Notion page created via the connector
+  (named destination, never overwriting), or a Canva Doc created via the Canva
+  connector (a new design each run, named with the date; tables become
+  lists); fall back to the visual artifact if Notion or Canva is not
+  connected — and say that is why.
+- **Best for skill:** use the visual artifact — a pulse is scanned, not filed.
+
+## Step 6 — Export and share (once)
+
+After presenting the pulse, offer once:
+- "Want me to save this as a file?" (use Files connector if available — this means a copy in their drive, not a second HTML download beside the artifact)
+- "Should I post this to your Slack?" (only if Slack is connected and the user confirms — Slack write requires explicit approval)
+
+If they say yes, do it. If they say no or don't respond, move on — don't ask again.
+
+## After the run
+
+Close with one line on what the pulse covered, then the single most relevant
+next step and at most two others nearby:
+
+- If cash or AR flagged red: "who owes me money" runs `invoice-chase`.
+- If growth questions dominate: "is my marketing working" runs `growth-pulse`.
+- To make this recurring: "Monday brief" runs `/monday-brief` every week.
+
+Max three offers. Never repeat an offer the owner declined this session.
+
+## Scope variants
+
+The owner may ask for a narrower cut:
+
+- **"Just cash" / "financial check"** → only Cash & Finance + AR-related risks
+- **"Pipeline only" / "deals check"** → only Pipeline section + stalled-deal risks
+- **"Watch list" / "anything urgent"** → only Watch List + all risks, no metric sections
+- **"Quick snapshot before a call"** → TL;DR + #1 Priority only, no full sections
+
+## What not to do
+
+- **Do not ask permission before pulling data.** If the skill was invoked, run it. Asking "should I check QuickBooks?" defeats the whole point.
+- **Do not invent or estimate numbers.** If a source returned nothing, say "n/a" explicitly. Never fill a gap with guesswork.
+- **Do not skip the delta.** A number without a comparison is a missed insight. If there's no prior-period baseline, say "(no prior baseline)" rather than omitting the field.
+- **Do not surface connector errors mid-pulse.** Log them to the appendix. The pulse leads with what was delivered.
+- **Do not trust a QuickBooks summary object.** Expenses, margin, and AP aging buckets come from the rows or the detail call (`../../shared/quickbooks-report-traps.md`).
+
+## More sources, and scheduled presets
+
+Read `reference/v2_sources.md` for the mapping:
+
+- **Shopify** — orders, revenue, and fulfillment status, so a commerce business sees its actual day in the pulse
+- **Any ledger** — MYOB, NetSuite, QuickBooks, Xero, or Zoho Books feed the Cash & Finance section; they are peers (`../../shared/connector-neutrality.md`). With two connected, the owner names one as the source of record for totals
+
+The pulse still builds from whatever is connected and degrades gracefully — one connector gives a partial pulse, the full stack gives the full picture.
+
+### Scheduled presets
+
+This skill is schedulable, and the preset decides the shape:
+
+| Preset | When | Shape |
+|---|---|---|
+| Monday | Start of week | Full pulse, forward-looking. What's coming and what needs attention |
+| Friday | End of week | Recap. What moved, what closed, what slipped |
+
+Scheduling is a property of this skill, not a reason for a separate command.
+
+Offer a cadence once, after a pulse the owner found useful. Don't ask twice.
+
+## Reference files
+
+- `reference/data_sources.md` — exact connector tool → metric mapping with fallbacks
+- `reference/thresholds.md` — 🟢/🟡/🔴 cutoffs, tunable per owner
+- `reference/output_template.md` — exact markdown structure; do not deviate
+- `reference/gotchas.md` — known failure modes (QB states, Gmail auth, Slack write)
+
+## Using a tool that isn't listed
+
+The connectors named in this skill are the tested paths, not a wall. If the owner wants this flow to use a tool that isn't connected or listed, offer `build-connector` — it checks the connector directory first and connects through Zapier otherwise, never hand-building against a raw API. Once the connection exists, the tool joins this skill like any other optional connector, under the same approval gates.

package/content/small-business/skills/small-business-business-pulse/reference/data_sources.md

@@ -0,0 +1,173 @@
+# Data Sources
+
+Exact mapping from each pulse section to the MCP tool that produces it. **Dispatch all calls in a single parallel batch** — do not pull serially.
+
+## Cash & Finance (the ledger)
+
+Whichever ledger is connected feeds this section — MYOB, NetSuite, QuickBooks, Xero, or Zoho Books, as peers (`../../../shared/connector-neutrality.md`). The QuickBooks table is first only because it is the longest; the Xero, NetSuite, MYOB, and Zoho Books tables below map the same metrics. Amounts carry the business's currency code (`../../../shared/currency-and-locale.md`); thresholds are in that currency.
+
+### QuickBooks
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Cash / bank balance | `cash_flow_quickbooks_account` | Current balance; show delta vs. prior week if available |
+| MTD revenue | `profit_loss_quickbooks_account` | Current month vs. prior month. Read income and expenses from the report rows or `monthlyBreakdown`; the response's top-level `totalExpenses`, `grossProfit`, and `grossProfitMargin` report 0 / 100% against real rows (a defect in the response shape), so never read them |
+| Outstanding receivables | QuickBooks invoice list | Filter to open/unpaid |
+| AR aging | QuickBooks invoice list | Group by days since due: 0–30, 31–60, 61+ |
+| Overdue invoices | QuickBooks invoice list | Filter to due_date > 30 days past; name customer + amount + days overdue |
+
+**Ledger state handling**: if the ledger's cash read returns an error, empty response, or "not connected" state, mark the entire Cash section as "n/a — ledger unavailable" (naming which) and continue. Do not retry.
+
+### Xero
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Cash / bank balance | `get_cash_position` | Same role as the QuickBooks cash read |
+| MTD revenue, P&L trend | `get_profit_and_loss` | Current month vs. prior |
+| Receivables, AR aging, overdue | `get_aged_receivables` | Name customer + amount + days overdue. (`get_contacts_and_receivables` is deprecated in the Xero server; do not call it) |
+
+### NetSuite
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Cash, receivables, P&L | `ns_runReport` / `ns_runCustomSuiteQL` | Same metrics, same section |
+
+### MYOB
+
+| Metric | Tool | Notes |
+|---|---|---|
+| MTD revenue, P&L trend | `myob_get_profit_loss` | Resolve the financial year first with `myob_get_financial_year_dates` |
+| Receivables, overdue | `myob_get_outstanding_customer_balances` | No cash balance exists in MYOB; leave the cash line as "not available from MYOB" |
+
+### Zoho Books
+
+Every call takes `organization_id` from `list_organizations`.
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Cash / bank balance | `list_bank_accounts` with `filter_by=Status.Active` | Sum `current_balance` across bank and cash accounts (`bcy_balance` is the same figure in base currency). No history endpoint, so the WoW delta needs the prior pulse's stored figure or is omitted |
+| MTD revenue | `list_invoices` with `date_start`/`date_end` for the month and `response_option=3` | Returns the count and the summed `total`; invoiced revenue, not a P&L — say so. Zoho Books exposes no P&L report endpoint |
+| Outstanding receivables | `list_invoices` with `status=unpaid` and `response_option=3` | Summed `balance` |
+| AR aging, overdue invoices | `list_invoices` with `status=overdue`, sorted by `due_date` | Each carries `due_days` ("Overdue by 323 days"), `customer_name`, `balance`, `email`; bucket by due date yourself |
+
+Zoho Desk is a separate connector and a separate organisation ID; it feeds the support section below, not this one.
+
+## Revenue & Sales (PayPal / Square / Stripe)
+
+| Metric | Tool | Notes |
+|---|---|---|
+| 7-day settlement total | PayPal transactions | Sum completed settlements in window |
+| Sales trend | PayPal transactions | This 7 days vs. prior 7 days; compute delta |
+| Failed / pending transactions | PayPal transactions | Flag any > 200 (business currency; `thresholds.md`) |
+| Square settlements | Square (if connected) | Same as PayPal — sum + trend |
+| Stripe revenue | Stripe `list_invoices` (if connected) | Paid invoices in window |
+| Stripe failed payments | Stripe API read — charges/payment intents (if connected) | Failed charges in window; flag any > 200 (business currency) |
+| Stripe disputes | Stripe API read — disputes (if connected) | Any dispute opened in window goes to the watch list, named |
+
+Use whichever payment connectors are available. If both PayPal and Square are connected, report combined and per-source.
+
+## Pipeline (HubSpot)
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Pipeline by stage | `search_crm_objects` type=deals (`get_crm_objects` needs explicit IDs; see `../../../shared/connector-call-shapes.md`) | Group by deal stage; sum amount |
+| Deals closed this week | `search_crm_objects` | Filter closedate in window, stage = closed-won |
+| Deals gone cold | `search_crm_objects` | Filter `notes_last_updated` > 7 days ago, open stage. That is HubSpot's "Last Activity Date" on deals — there is no `hs_last_activity_date` or `hs_lastactivitydate` property |
+| New leads this week | `search_crm_objects` | Filter createdate in window |
+| Stalled/slipped deals | `search_crm_objects` | Open deals where closedate < today |
+
+## Commitments (Google Calendar)
+
+| Metric | Tool | Notes |
+|---|---|---|
+| This week's key items | `list_events` | Filter to current week; surface meetings with customers, deadlines, important holds |
+| Next 7 days | `list_events` | Forward-looking view; highlight anything with external parties |
+
+## Watch List (Gmail or Microsoft 365)
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Urgent threads | `search_threads` | Query: `is:important OR is:starred` in last 7 days |
+| Customer escalations | `search_threads` | Query: terms like "escalation," "complaint," "cancel," "refund," "urgent" in last 7 days |
+| Time-sensitive requests | `search_threads` | Query: `is:unread` + keywords like "deadline," "ASAP," "today" |
+
+**Gmail fallback**: if the Gmail call errors (auth flaky), skip Watch List silently and add "Gmail unavailable" to the appendix. Do not surface the error in the pulse body.
+
+## Internal Signals (Slack / Teams)
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Urgent threads | Slack search (if connected) | Threads with @mentions or urgency signals in owner-relevant channels |
+| Action items | Slack search | Messages directed at the owner or tagged for follow-up |
+
+Every section below this point follows the same rule: include only if the connector is available; omit the section entirely if not.
+
+## Commerce (Shopify, if connected)
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Orders, revenue, sales trend | `list-orders`, `run-analytics-query` | This 7 days vs. prior 7 |
+| Fulfillment issues | `list-orders` filtered to unfulfilled past promise | Named orders to the watch list |
+
+## Fulfillment (Square, if connected)
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Fulfillment issues | Square orders API via `make_api_request` | Same watch-list treatment as Shopify |
+
+## Payroll (Gusto, if connected)
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Next payroll run | `list_payrolls` / `list_pay_periods` | Date and expected amount — the week's biggest cash commitment |
+
+## Ads (TikTok Ads, if connected)
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Ad spend, results, cost per result | TikTok reporting (`report_integrated_get`) | Last 7 days vs. prior 7; sits beside the sales trend |
+
+## Card spend (Ramp / Expensify, if connected)
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Week's card spend | Ramp `ramp_get_transactions` | Sum for window; call out any single transaction > 500 (business currency) |
+| Account balance | Ramp `ramp_get_ramp_business_account_balance` | Read-only |
+| Card spend + missing receipts | Expensify `Search` | Read-only; count expenses without receipts |
+
+## Signatures (DocuSign, if connected)
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Unsigned envelopes | `getEnvelopes` filtered to sent status | Flag any sitting unsigned > 3 days, named |
+
+## Internal signals (RingEx Chat, if connected)
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Urgent team-chat posts | `read_team_chat` | Same role as Slack: escalation keywords, threads needing the owner. Chat only — no call data exists here |
+
+## Customer Support (Zoho Desk, if connected)
+
+| Metric | Tool | Notes |
+|---|---|---|
+| Open tickets, escalations | `getTickets` (`status`, `priority`, `sortBy=recentThread`) / `getTicketsMetrics` | Count open; flag any > 48h unresolved and any priority High, named. `getTickets` rejects an `include` parameter — request extra fields with `fields` |
+
+## Risks scan
+
+Run these alongside the metric pulls — don't wait for metrics to finish first.
+
+| Risk | Source | Trigger condition |
+|---|---|---|
+| Overdue AR | Ledger invoices / aged receivables | due_date > 30 days past, unpaid |
+| Stalled deals | HubSpot | Open deal, no activity 7+ days |
+| Slipped deals | HubSpot | Open deal, closedate in past |
+| Urgent mail threads | Gmail or Microsoft 365 | `is:important` or escalation keywords |
+| Failed payments | PayPal / Square / Stripe | Failed or pending > 200 (business currency) |
+| New dispute | Stripe / PayPal | Any dispute opened in window — always a watch-list item |
+| Stale unsigned envelope | DocuSign | Sent envelope unsigned > 3 days |
+| Missing receipts piling up | Expensify | 5+ expenses without receipts in window |
+
+## Parallelization
+
+All of the above should fire in a single tool-call batch. A complete pulse is typically 8–15 parallel calls. If one errors, the rest proceed normally and the failed source appears in "Sources unavailable" at the bottom of the pulse.