opencode-knowledge-work 0.0.0-stage → 0.1.0

package/content/small-business/skills/small-business-smb-onboard/reference/gotchas.md

@@ -0,0 +1,111 @@
+# Gotchas
+
+## Gotcha: Skipping the prove-value step when a connection takes too long
+
+**Why it matters:** If the owner connects a tool but Claude moves straight to the interview, the "aha" moment never lands. The prove-value step is what makes the owner trust the setup is worth completing — and what distinguishes this skill from a form-filling exercise.
+
+### ✗ Bad
+
+> "Great, QuickBooks is connected! Now let me ask you a few questions about your business."
+
+Skips the recipe entirely. Owner leaves not knowing what they just enabled.
+
+### ✓ Good
+
+> "QuickBooks is live. Let me pull your last 30 days of cash flow — takes about 10 seconds."
+> *[runs cash-flow-snapshot, shows results]*
+> "That's what we can do anytime you want a number check. Now, a few questions about your business…"
+
+The demo runs before the interview, every time, without exception.
+
+---
+
+## Gotcha: Dumping all five interview questions at once
+
+**Why it matters:** Five questions presented together feel like a form, not a conversation. Owners either skim-answer or drop off. Conversational pacing produces richer answers and higher completion.
+
+### ✗ Bad
+
+> "To get you set up, I need: (1) What kind of business do you run? (2) How many employees? (3) What are your top headaches? (4) What tools do you use? (5) How often do you want check-ins?"
+
+### ✓ Good
+
+Ask each question, receive the full answer, then ask the next. Compress to three (industry, headaches, tools) if the owner signals they're in a hurry — never skip those three.
+
+---
+
+## Gotcha: Writing context without showing the profile first
+
+**Why it matters:** Silent writes feel intrusive and remove the owner's chance to correct misheard answers. Showing the draft profile is also a natural confirmation that Claude understood correctly — it often surfaces a correction the owner wouldn't have volunteered.
+
+### ✗ Bad
+
+> "Got it, I've saved your business profile!"
+
+No preview, no approval — owner doesn't know what was written.
+
+### ✓ Good
+
+> "Here's what I'm about to save as your business profile — let me know if anything needs fixing:"
+>
+> ```
+> Business: Lakewood Hardware — retail hardware store
+> Size: 4 people (including owner)
+> Top headaches: cash flow gaps · slow-paying contractors · scheduling part-timers
+> Connected tools: QuickBooks, Gmail
+> Country: US
+> Currency: USD
+> Financial year end: 31 December
+> Weekly cadence: weekly check-in every Monday
+> Onboarded: 2026-04-23
+> ```
+>
+> "Look right? I'll save it once you confirm."
+
+Show the block, wait for approval, then write.
+
+---
+
+## Gotcha: Pitching the platform instead of the capability
+
+**Why it matters:** Owners already know what HubSpot, QuickBooks, Gmail, and Calendar do. When the recommendation reads like a product page ("HubSpot — One place for every lead, customer, deal, and conversation…"), it lands as an ad, not advice. The owner tunes out exactly when we need their attention.
+
+### ✗ Bad
+
+> "1. HubSpot (CRM) — One place for every lead, customer, deal, and conversation. Once it's in, I can prioritize who to call today, draft follow-ups, log notes from your inbox, and spot deals going stale.
+>
+> 2. Gmail — Email is where most of the chaos lives: commitments buried in threads, customer questions waiting on a reply, things slipping through. Connecting your inbox lets me surface what actually needs an answer…"
+
+Reads like marketing for HubSpot and Gmail. The owner is being sold to.
+
+### ✓ Good
+
+> "For customer follow-up, the two pieces I'd want are a CRM and your inbox.
+>
+> What do you use for a CRM today?"
+>
+> *(Owner: "Pipedrive.")*
+>
+> "Got it — we don't have a Pipedrive connector yet. Two ways to go: I can connect Pipedrive through Zapier, which takes about ten minutes of setup and then lead scoring and drafted follow-ups work from inside it. Or you can export your leads as a CSV whenever you want a call list, and I'll work from that. Which do you prefer?"
+
+States the function, asks what the owner uses without naming a vendor, offers the Zapier connection and the fallback with the trade-off in one line each, and leaves the decision with the owner. It never suggests switching to a CRM we happen to support. If the owner asks "which CRM should I get?" — that's an explicit invitation; describe what each connector in the category unlocks, alphabetically and in the same number of words, and let them choose.
+
+---
+
+## Gotcha: Recommending a vendor because it is the one we have
+
+**Why it matters:** The plugin is neutral. An owner on Xero told to "connect QuickBooks first" hears that their tool is second-class, and an owner with no bookkeeping tool told to get a specific one hears an ad. Both are wrong. The rule is `../../../shared/connector-neutrality.md`.
+
+### ✗ Bad
+
+> "Let's connect QuickBooks first — that lets me pull your cash position anytime."
+
+### ✓ Good
+
+> "Let's start with your bookkeeping — what do you use?"
+>
+> *(Owner: "Xero.")*
+>
+> "Xero it is. Here's how to authorize the connection…"
+
+Ask the category, connect what they name. If they have nothing in the category, say what the zero-connector path gives them and name the category — "once you have a bookkeeping tool connected, this gets deeper" — not a product.

package/content/small-business/skills/small-business-smb-onboard/reference/onboard-checklist.md

@@ -0,0 +1,99 @@
+# Onboard checklist
+
+## The seven interview questions
+
+Ask one at a time. Wait for the full answer before moving on. One follow-up is fine if an answer is vague; do not drill further.
+
+1. **Industry and business type.** "What kind of business do you run? Give me the one-liner."
+2. **Team size.** "How many people work with you, including yourself?"
+3. **Top three headaches.** "What are your three biggest headaches right now — the things that eat your time or keep you up at night?"
+4. **Tools already in use.** "Which tools do you already use day-to-day? Your bookkeeping software, email, online store or point of sale, a CRM, team chat…" Ask by category, never by product name. The owner names the vendors.
+5. **Preferred cadence.** "How would you like me to check in — daily, weekly, or only when you ask?"
+6. **Website and brand look.** Run the `brand-style` skill's capture-and-preview flow (Steps 2–3 there): a pasted website link auto-pulls logo, colors, and tagline; with no site, a plain-words description ("forest green and cream") is translated to colors. Never hex codes, pickers, or uploads. The welcome page in Step 6 doubles as the live preview.
+7. **Output format.** Run `brand-style` Step 4 — the six-way multiple choice: visual artifacts (default) / Word docs / markdown / Notion pages / Canva Docs / best for the skill. Store the answer verbatim as one of: `visual artifacts`, `docx`, `md`, `notion`, `canva`, `best for skill`.
+
+If the owner is short on time, compress to questions 1, 3, and 4 — those three feed the most downstream skills. Skipped questions keep their defaults (visual pages for output).
+
+---
+
+## Connector priority matrix
+
+Map the owner's stated headache to the two **categories** of tool to link first. The plugin never recommends a vendor inside a category (`../../../shared/connector-neutrality.md`): it asks what the owner already uses, and connects that.
+
+| Primary headache | First category | Second category | Prove-value recipe |
+|---|---|---|---|
+| Cash flow / invoicing | Accounting ledger | Payments or point of sale | `cash-flow-snapshot` |
+| Customer follow-up | CRM | Mail | `lead-triage` — the growth quick-win, ranks who to call back first |
+| Hiring / job posts | Mail | Calendar | `job-post-builder` |
+| Staying organized | Desktop (folder setup) | Mail | Desktop folder structure demo |
+| Scheduling overload | Calendar | Mail | `business-pulse` |
+| Selling online / stock | Storefront or point of sale (holds orders and stock) | Accounting ledger | `inventory-planner` |
+| General / unsure | Mail | Accounting ledger | `cash-flow-snapshot` |
+
+One optional third category for the customer follow-up row: **lead data and enrichment**, which fills in company size and industry when the CRM's leads carry no company record. It is metered (credits per row), so it is never the first ask and never named by vendor here — if the owner already has one, connect it after the CRM and `lead-triage` uses it; if not, the recipe runs without it.
+
+**How to fill a category.** Ask what the owner uses for it: *"What do you use for bookkeeping?"* Then one of three, in this order, said once with the trade-off in one line:
+
+1. **We have the connector** (see the category table in `../../../shared/connector-neutrality.md`) — guide the connection.
+2. **We do not** — offer `build-connector`, which checks the connector directory and connects through Zapier otherwise. Say what the connection unlocks and what it costs them in setup time.
+3. **They do not want the Zapier connection, or have no tool in that category** — run the recipe's zero-connector path (CSV, pasted text) and move to the next category. Name the category, not a product, when saying what would make it deeper.
+
+Never suggest the owner switch to a tool we support. If they ask "which one should I get?", that is an explicit invitation: describe what each connector in the category unlocks, in the same number of words each, alphabetically, and leave the choice with them.
+
+---
+
+## Recipe selection
+
+Run the prove-value recipe immediately after the **first** connector is live — do not wait for the second. If connectors are already active at session start, run the matched recipe for the owner's primary headache before beginning the interview. Keyed by category, whichever connector fills it:
+
+1. Any accounting ledger, or any payments / point-of-sale connector → `cash-flow-snapshot`
+2. Any CRM → `lead-triage` (rank the open leads, recommend today's callbacks — nothing is written back)
+3. Any storefront or point-of-sale connector that holds orders and stock → `inventory-planner` (a payments-only connector with no stock data belongs under rung 1)
+4. Any mail connector → search for unread invoice-related emails, surface top 3
+5. Calendar → `business-pulse`
+6. Desktop only → walk Desktop folder setup, create recommended structure
+
+### Connector-specific setup notes
+
+These are technical steps one connector needs before its recipe can run. They are not preferences.
+
+- **QuickBooks `profile_info_required`:** if QuickBooks returns this status (missing business_name or industry), use the `quickbooks-profile-info-update` tool with the owner's business name from interview question 1 before running `cash-flow-snapshot`. Do not skip the recipe — collect the missing info first.
+- **HubSpot portal readiness:** before running `lead-triage` as the recipe, count contacts with one `search_crm_objects` call (limit 1; read `total`). Zero means the recipe would rank an empty list: say so in one line, offer `manage_onboarding` (action `SET_GOAL`) to start HubSpot's own setup, and run the recipe only once contacts exist — or on a pasted lead list if the owner prefers. `get_user_details` also returns an `onboarded` flag; treat it as a hint about HubSpot's guided setup, not as the test, because a portal with hundreds of contacts can still report `onboarded: false`. This is a technical readiness step for one connector, not a preference.
+
+### Country, currency, and financial year — read from the ledger first, then the storefront
+
+Once the first ledger connector is live, read the organisation record before the recipe runs and fill the three locale fields in the profile without asking: QuickBooks `company_info`; Xero `get_organisation_info` and `get_organisation_financial_year`; MYOB `myob_get_financial_year_dates`; NetSuite `ns_getSubsidiaries` (country and currency; ask for the year end if the connector does not expose it); Zoho Books `get_organization` (`country_code`, `currency_code`, and `fiscal_year_start_month`, a zero-based month index — the year end is the last day of the month before it). Take what the connector exposes.
+
+If no ledger is connected but a storefront or point-of-sale connector is, read its shop record instead — Shopify `get-shop-info` (country and currency); Square the merchant record via `make_api_request` (`country`, `currency`). Neither holds a financial year end, so ask that one field alone during the interview: *"When does your financial year end?"* — do not re-ask country or currency. Storefronts are peers here as everywhere (`../../../shared/connector-neutrality.md`): read whichever is connected.
+
+If neither a ledger nor a storefront is connected, or the record is missing a field, ask one question during the interview: *"Which country is the business in, and what currency do you invoice in?"* Financial year end defaults to the country's common convention only after the owner confirms it. The rule and the field formats are in `../../../shared/currency-and-locale.md`.
+
+---
+
+## Owner profile — storage format
+
+Write this block to the Cowork session memory directory under the heading `## Business context`. Every other skill reads this section by heading match. Do not rename the heading or change the field names.
+
+```markdown
+## Business context
+
+- **Business:** <one-liner — industry, product/service>
+- **Size:** <number of people, including owner>
+- **Top headaches:** <headache 1> · <headache 2> · <headache 3>
+- **Connected tools:** <comma-separated list of active connectors, by product name — "Trello", never a registration name like "small-business:trello">
+- **Country:** <ISO 3166 two-letter code, e.g. GB, AU, NZ, US, CA>
+- **Currency:** <ISO 4217 code the business invoices in, e.g. GBP, AUD, USD>
+- **Financial year end:** <day and month, e.g. 30 June, 31 March, 31 December>
+- **Weekly cadence:** <trigger phrase and day, e.g. "weekly check-in every Monday">
+- **Website:** <URL, if any>
+- **Brand colors:** <primary and secondary colors, from the website or the owner's plain-words description, if any>
+- **Logo:** <logo image URL pulled from the website, if any>
+- **Output preference:** <"visual artifacts" (default), "docx", "md", "notion", "canva", or "best for skill">
+- **Notion destination:** <the parent page or database the owner named for skill output, if the preference is "notion"; asked once, the first time a skill needs it>
+- **Canva brand kit:** <the name and id of the Canva brand kit the owner chose for skill output, or "none", if the preference is "canva"; asked once, by brand-style Step 4 or the first time a skill needs it>
+- **Onboarded:** <YYYY-MM-DD>
+```
+
+If a memory file already exists, append or update only the `## Business context` section. Do not touch other content.
+
+**Return sessions with an older profile.** If the block exists but has no Country, Currency, or Financial year end line (profiles written before these fields existed), read them from the ledger if one is connected, otherwise ask the one locale question, and update only those three fields. Do not re-interview.

package/content/small-business/skills/small-business-smb-onboard/reference/website-research.md

@@ -0,0 +1,82 @@
+# Website research
+
+Read this before fetching the owner's site. The goal is to replace interview
+questions the site already answers, not to add a research phase on top of the
+interview — onboarding should still finish in 15–20 minutes.
+
+---
+
+## What to fetch
+
+The homepage plus whichever of these exist and are linked from it: about,
+services or products, pricing, locations, contact. Three or four pages total
+is enough — this is not a full site crawl.
+
+## What to extract
+
+| Field | What it feeds |
+|---|---|
+| What they actually sell | Business context; sharper than a one-line owner description alone |
+| Who they sell to (consumer, business, both; specific niche) | Every skill that drafts customer-facing copy |
+| Service area or locations | Local-service and retail skills |
+| Team size signals (staff photos, "our team," locations count) | A cross-check on the interview answer, never a replacement for it |
+| Price positioning (premium, budget, mid-market — inferred, not guessed as a number) | Proposal and marketing skills |
+| The words they use for their own work | Feeds `shared/voice-profile.md` directly — this is real copy in the owner's own hand, even before any email is read |
+| Brand colors (dominant background/accent from the site's own CSS) | The welcome artifact and every artifact after it, per `shared/artifact-style.md` |
+| A declared font-family, if one is easy to find | Same — applied only if it resolves on Google Fonts; otherwise skip it, never fight the CSP |
+
+**Do not infer anything the site doesn't actually say.** "Looks premium" from
+a photo is a guess; "prices start at USD 200" printed on a pricing page is a
+fact. Keep the two separate in what gets shown back — say when something is
+inferred rather than read.
+
+---
+
+## Showing what was found
+
+Always show it before storing anything, and keep it short — a wall of
+extracted facts is worse than the interview it was meant to replace.
+
+```
+Read your site. Looks like: commercial HVAC repair and maintenance, Denver
+metro, same-day service is a big deal to you — it's on every page. Found a
+deep green and a slab serif in your branding.
+
+Anything off, or should I use that for your reports too?
+```
+
+**Treat a correction as expected, not a failure.** Sites go stale, and an
+owner catching one wrong detail in ten seconds is the whole point of showing
+the draft rather than silently storing it.
+
+---
+
+## Brand token extraction
+
+Pull the two or three colors that actually recur across the site — usually
+visible in a header, a button, or a logo background — and any font-family
+declared in the page's own stylesheet. Do not invent a palette from a single
+photo; only extract what's structurally present in the site's own CSS or
+repeated markup.
+
+**Apply only on a yes.** Show the finding in the same message as the business
+summary (see above), and only wire the colors and font into the welcome
+artifact's tokens (`shared/artifact-style.md`) if the owner confirms. If the
+site's declared font doesn't resolve on Google Fonts, keep the house default
+silently — never show a broken font as if it worked.
+
+Store the resolved values — not the raw scrape — in the `## Business context`
+block's Brand colors and Logo fields (format in [onboard-checklist.md](onboard-checklist.md)), so
+every later skill's artifact reads the same finished tokens without
+re-deriving them.
+
+---
+
+## When there is no website, or the owner skips it
+
+Say nothing lost — move straight to the interview. This step is a shortcut
+when it exists, never a requirement:
+
+```
+No problem — I'll just ask a few questions instead.
+```

package/content/small-business/skills/small-business-smb-router/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: smb-router
+description: >
+  The front door to the Small Business plugin. Listens to what the owner needs
+  right now — vague or specific — and routes them to the best skill or slash
+  command for the moment. Also serves as a guide: explains what's available,
+  suggests what to try next, and adapts recommendations based on stored business
+  context. Trigger whenever the owner asks "what can you do," "help me with my
+  business," "what should I focus on," "I don't know where to start," or any
+  open-ended business request that doesn't clearly match a single skill.
+allowed-tools: Read, WebFetch
+---
+
+# SMB Router
+
+You are the concierge for this plugin. Your job is to understand what the owner needs right now and get them to the right place — fast. You are not a skill that does work yourself. You route to the skills and commands that do.
+
+## Quick start
+
+```
+Owner: "I'm stressed about making payroll next week"
+→ Read business context from memory
+→ Match: cash concern + upcoming payroll = /plan-payroll
+→ "Sounds like you need a cash forecast and invoice chase before payroll.
+   I'll run /plan-payroll — it'll show your 30-day cash picture and
+   stage reminders for overdue invoices. Ready?"
+→ On confirmation, trigger /plan-payroll
+```
+
+## How to route
+
+### Step 1 — Read business context
+
+Check session memory for `## Business context`. If it exists, use it to inform your recommendation (industry, headaches, connected tools). If it doesn't exist, note that onboarding hasn't been run — suggest it if the owner seems new, but don't force it if they have a specific ask.
+
+### Step 2 — Match intent to the routing table
+
+Pick the **single best match**, not a list of options. If two are close, pick the one that addresses the most urgent concern.
+
+**Money & cash:**
+| Owner says something like... | Route to |
+|---|---|
+| "Can I make payroll?" / "cash is tight" | `/plan-payroll` |
+| "Cash forecast" / "runway" / "what does next month look like?" | `cash-flow-snapshot` (monthly preset) |
+| "Close the books" / "close the month" / "month-end" / "reconcile" / "close packet" | `/close-month` |
+| "Just reconcile, no packet" / "what's missing from the books" / "flag the duplicates" | `month-end-prep` |
+| "Pay the bills" / "AP inbox → payment run" | `/pay-the-bills` |
+| "Code these invoices" / "process these bills" (no payment yet) | `ap-processor` |
+| "Run payroll" / "timesheets" | `payroll-prep` |
+| "Who owes me money?" / "overdue invoices" | `invoice-chase` |
+| "Margins" / "should I raise prices?" | `content-strategy` |
+| "Taxes" / "1099s" / "quarterly estimates" / "set aside for taxes" | `/tax-prep` |
+| "Books are closed, just the 1099s" / "the estimate off the closed numbers" | `tax-season-organizer` |
+| "Build me a report" / "track these numbers" / "KPI pack" | `report-builder` |
+| "My recurring reports" / "the weekly pack, on schedule" | `/report-pack` |
+
+**Sales & growth:**
+| Owner says something like... | Route to |
+|---|---|
+| "Find me customers" / "prospect list" / "more leads" | `lead-finder` |
+| "Write this outreach" / "cold email" / "follow-up sequence" | `outreach-composer` |
+| "Leads are going cold" / "answer inquiries fast" / "nothing falls through the cracks" | `speed-to-lead` |
+| "Rank my leads" / "score my pipeline" / "who should I call first?" — no calendar blocks | `lead-triage` |
+| "Call list" / "who am I calling today?" / "top five to call" / "block time for calls" | `/call-list` |
+| "Write this up" / "quote this job" / "bid" / "proposal" / "RFP" | `proposal-builder` |
+| "Fill my funnel" / "pipeline end to end" | `/grow-pipeline` |
+| "Win back quiet customers" / "re-engage" | `/reactivate` |
+| "Weekly growth brief" / "marketing Monday" | `/marketing-monday` |
+| "Update the CRM" / "log this call" / "HubSpot is a mess" | `crm-autopilot` (hygiene mode) |
+| "Is my marketing working?" / "campaign ROI" / "funnel" | `growth-pulse` |
+| "What should I promote?" / "sales brief" | `content-strategy` |
+| "Make the content" / "posts" / "assets" / "calendar" | `social-content-engine` |
+| "Run this brief" / "execute the campaign" — a finished brief in hand | `canva-creator` |
+| "My ads" / "ad spend" / "is the ad money working?" | `ad-manager` |
+| "Be found on Google" / "AI search" / "SEO" / "website visibility" | `seo-ai-visibility` |
+| "What are competitors doing?" / "market check" | `growth-pulse` |
+| "Grants" / "government bids" / "RFP funding" | `grant-rfp-writer` |
+
+**Customers & reputation:**
+| Owner says something like... | Route to |
+|---|---|
+| "What are customers saying?" / "reviews" / "churn" | `review-reputation` |
+| "A customer is upset" / "angry email" | `ticket-deflector` |
+| "Check my orders" / "anything about to blow up?" | `ticket-deflector` (order-triage mode) |
+| "Pulse check on customers" | `review-reputation` |
+
+**Operations & people:**
+| Owner says something like... | Route to |
+|---|---|
+| "Go through my email" / "drowning in email" | `inbox-manager` |
+| "Brief me" / "prep my day" / "what's my day look like?" | `business-pulse` |
+| "Reorder" / "stock" / "running out of" | `/restock` (analysis only: `inventory-planner`) |
+| "Write a job post" / "hiring packet" | `job-post-builder` |
+| "Screen these applications" / "rank candidates" | `hiring-screener` |
+| "I need to hire someone" (starting out) | `job-post-builder` |
+| "Review this contract" / "NDA" / "should I sign?" | `contract-review` |
+
+**Business intelligence:**
+| Owner says something like... | Route to |
+|---|---|
+| "How's the business doing?" / "snapshot" / "catch me up" | `business-pulse` |
+| "Monday brief" / "start my week" / "start of week" / "weekly briefing" | `/monday-brief` |
+| "Friday recap" / "how'd we do this week?" | `business-pulse` (Friday preset) |
+
+**Build your own:**
+| Owner says something like... | Route to |
+|---|---|
+| "I do this every week" / "automate this" / "make this a thing" | `build-agent` |
+| "Update my brand" / "we rebranded" / "change how you give me reports" | `brand-style` |
+| "Connect to my ERP" / "my tool isn't supported" / "make my tools talk" | `build-connector` |
+
+**Getting started:** "set me up" / "I'm new" → `smb-onboard`. For "what can you do," the rule is: no stored business context (new owner) → route to `smb-onboard`; stored context already exists → answer directly with the Step 4 overview, no onboarding detour.
+
+All 11 command folders exist (see the connector map), plus the scheduled chain that lives inside the speed-to-lead skill. Route to the command when the owner wants the end-to-end flow; route to the skill when they want just that step.
+
+**Four pairs that sound alike.** Each pair is a command and the skill it runs first. The command wins on the shared phrases; the skill wins only on the phrases that say "just this step."
+
+| Shared phrases go to | The skill alone, only for |
+|---|---|
+| `/close-month` — "close the month," "month-end," "reconcile," "close the books" | `month-end-prep` — "just reconcile, no packet," "what's missing from the books," "flag the duplicates" |
+| `/monday-brief` — "Monday brief," "start my week," "weekly briefing" | `business-pulse` — "how's the business doing," "snapshot," "daily brief," "Friday recap" |
+| `/call-list` — "call list," "who am I calling today," "block time for calls" | `lead-triage` — "rank my leads," "score my pipeline," "who should I call first" with no calendar blocks |
+| `/tax-prep` — every tax phrase: "quarterly taxes," "1099s," "set aside for taxes" | `tax-season-organizer` — "books are closed, just the 1099s," "the estimate off the closed numbers" |
+
+/tax-prep exists to make the books-first order hold, so a tax phrase never skips straight to tax-season-organizer unless the owner says the books are already closed.
+
+**Disambiguation — do the task vs. build the automation.** Task words ("do this reconciliation," "write this post," "chase these invoices") route to the skill that does the work. Automation words ("learn it," "make it automatic," "do this every month," "I do this every week") route to `build-agent`, even when a shipped skill covers the one-off version.
+
+**Disambiguation — content.** A finished, approved campaign brief in hand routes to `canva-creator` — the one-shot executor. Everything else content-shaped ("post more," "what should we post," the standing calendar) routes to `social-content-engine`. When it's unclear whether a brief exists, ask that one question.
+
+**Disambiguation — hiring.** "I need to hire someone" starts at `job-post-builder`, which produces the post and the screening rubric. Once applications arrive, `hiring-screener` scores them, drafts the replies, schedules interviews, and preps onboarding.
+
+### Step 3 — Present the recommendation
+
+Don't dump a menu. Recommend **one thing**, one sentence on why, ask to run it. If the request spans two, name the most urgent first and mention the follow-up.
+
+### Step 4 — Handle "what can you do?"
+
+First check for stored business context. No stored context means a new owner — route to `smb-onboard` instead of listing capabilities, because the overview lands better after setup. If context exists, answer directly with the buckets below and do not suggest onboarding again.
+
+Organize by what matters to them, using stored context. Five buckets, lead with the one matching their headaches:
+
+**Your money:** `/plan-payroll` · `/close-month` · `/pay-the-bills` · `report-builder` · `invoice-chase` · `/tax-prep`
+**Your growth:** `/grow-pipeline` · `speed-to-lead` · `proposal-builder` · `crm-autopilot` · `/marketing-monday` · `social-content-engine`
+**Your customers:** `review-reputation` · `ticket-deflector` · `/reactivate`
+**Your week:** `/monday-brief` · `business-pulse` · `inbox-manager`
+**Build your own:** `build-agent` · `build-connector`
+
+Two or three sentences per bucket, then: "What's on your mind? I'll get you to the right place."
+
+Alongside the chat answer, render the overview as a visual catalog — an HTML artifact using the house artifact style (`../../shared/artifact-style.md`). Not a data page: grouped by job to be done using the five buckets above (money, growth, customers, week, build your own), never alphabetically, with each entry carrying its name, one line on what it does, and its exact trigger phrase from the routing table. Lead with the bucket matching the owner's stored headaches. The chat answer stays; the catalog is the page they come back to.
+
+### Step 5 — Connector-aware routing
+
+Before recommending, check which connectors are active. A product the owner connected themselves and the plugin's own registration of it (`small-business:<name>`) are one connector, not two — use whichever is authorized, and never count them as two sources in a category (`../../shared/connector-neutrality.md`, "One connector, two registrations"). Three rules, in order:
+
+**1. Prefer what is already connected.** When a skill can run on more than
+one MCP, the connected one wins — always. Never recommend connecting a new
+tool when a connected one already covers the job, and never route a skill
+onto a disconnected source when a connected equivalent exists. Connected
+beats preferred-on-paper, every time.
+
+**2. Two or more connected sources that could each carry the run — ask,
+as a multiple choice.** When the owner has two connected MCPs in the same
+category (two ledgers for a books skill; two CRMs for a CRM skill), do not
+pick silently. Put it to the owner as a short multiple-choice question — one
+line per option, connected options only, each option described by what it
+holds for this run and nothing that ranks it against the other (the facts below
+are illustrative; read them from what each connector actually returns):
+
+```
+Both of these are connected and can run your month-end close. Which one
+holds the books you want closed?
+  1. QuickBooks — connected; holds the bills and the payroll journal
+  2. Xero — connected; holds the bank feeds and the invoices
+```
+
+Remember the answer for the session (and offer to store it in the business
+context as the source of record), so the same question is not asked twice.
+After the choice the skill may still read the other connector for anything
+it uniquely holds, but every total comes from the named source of record and
+is never summed across both — the rule is `../../shared/connector-neutrality.md`.
+
+**3. If the best match needs a connector that's missing:**
+
+1. Name the recommendation and the blocker by category: "Best fit is `ap-processor`, but it needs a ledger (MYOB, NetSuite, QuickBooks, Xero, or Zoho Books) and your mailbox. Which do you use? I'll walk you through connecting it."
+2. Offer the fallback path — every skill has one (CSV, pasted text, forwarded email, or web research). "With no ledger connected, upload the AR report as a CSV and `invoice-chase` works the same."
+3. Never silently route to something that will partially fail. Say upfront what they'll get and what they won't.
+4. If the tool the owner wants has no listed connector at all, offer `build-connector`: it checks the connector directory first and connects through Zapier otherwise. Once built, the tool works inside the recommended skill like any other connector — this holds for every skill, not just the ones that name it.
+
+**4. Never recommend one vendor over another in a category.** The gate is
+"a ledger," "a CRM," "a mailbox" — never a product. When nothing in the
+category is connected, name the category and the fallback, and ask what the
+owner uses. Do not propose a vendor for them to adopt.
+
+Read `reference/connector-map.md` for the full skill-to-connector table.
+
+### Step 6 — Tiebreakers and no-match
+
+Tied match: urgency wins (cash beats marketing, complaints beat pipeline), then smaller scope, then one clarifying question with at most two options.
+
+No match: check whether `build-agent` fits — "I do this every week" is buildable even when no shipped skill covers it. If genuinely out of scope, say so plainly and give the Step 4 overview. Never claim a capability that doesn't exist.
+
+## Guardrails
+
+- **Never do the work yourself.** You route. If you catch yourself pulling data or drafting an email, you're in the wrong lane.
+- **Never dump a full menu unprompted.** One recommendation, one reason, one ask.
+- **Never skip confirmation** before triggering anything.
+- **Never silently route to a broken command.** Missing connector gets named first, with the fallback offered.
+- **Never pick between two connected equals silently.** Two connected MCPs that both fit means a multiple-choice question, once per session — then the answer sticks.
+- **Never rank vendors.** Gates are categories. Same-category connectors are peers (`../../shared/connector-neutrality.md`).
+- **Adapt to context.** Lead with the bucket matching their stored headaches.
+
+## Reference files
+
+- `reference/connector-map.md` — required and optional connectors per skill and command, with each skill's fallback

package/content/small-business/skills/small-business-smb-router/reference/connector-map.md

@@ -0,0 +1,96 @@
+# Connector Map
+
+Required and optional connectors per skill, plus each skill's zero-connector fallback. The router uses this to avoid recommending something that will partially fail, and to offer the fallback path instead.
+
+**The lists below are the tested paths, not a wall.** When the owner wants a skill to use a tool that is not listed for it, route to `build-connector` first — it checks the connector directory, then connects through Zapier. Once the connection exists, the tool joins that skill like any other optional connector, with the same approval gates.
+
+Every skill works with zero connectors. "Required" below means required for the *connected* path — the fallback column is always available.
+
+**Call shapes.** Parameter shapes that connectors require and tool descriptions do not make obvious are collected in [`../../../shared/connector-call-shapes.md`](../../../shared/connector-call-shapes.md); a skill reads the row for a connector before its first call to it.
+
+**One product, possibly two entries.** The owner's own connector and the plugin's manifest registration of it (`small-business:<name>`) count as one; a gate opens if either is authorized (`../../../shared/connector-neutrality.md`, "One connector, two registrations").
+
+**Gates are categories, not vendors.** Where a row says "a ledger," any of MYOB, NetSuite, QuickBooks, Xero, or Zoho Books opens the gate; "a payments connector" is any of PayPal, Square, or Stripe; "a CRM" is any of HubSpot, Monday.com, Salesforce, or Zoho CRM (Salesforce is owner-added as a custom connector, not in the manifest); "a storefront" is either of Shopify or Square (the connectors that hold orders and stock); "Mail" is either of Gmail or Microsoft 365; "a file store" is either of Google Drive or Microsoft 365 (Microsoft 365 is one connector covering both of those categories, and is owner-added as a custom connector, not in the manifest); and none ranks above another (`../../../shared/connector-neutrality.md`). Vendor lists are alphabetical. Capability limits that matter to a gate are in the footnotes under each table, stated as what the connector holds, not as a ranking.
+
+---
+
+## Run the business
+
+| Skill | Required | Optional | Zero-connector fallback |
+|---|---|---|---|
+| `report-builder` | any one data source | Expensify, HubSpot, MYOB, NetSuite, PayPal, QuickBooks, Ramp, Shopify, Square, Stripe, Xero, Zoho Books | CSV/XLSX upload — fully functional |
+| `business-pulse` | none | Calendar, DocuSign, Expensify, Gmail or M365, Gusto, HubSpot, MYOB, NetSuite, PayPal, QuickBooks, Ramp, RingEx Chat, Shopify, Slack, Stripe, TikTok Ads, Xero, Zoho Books, Zoho Desk | builds from whatever exists, or pasted data |
+| `cash-flow-snapshot` | a ledger (MYOB, NetSuite, QuickBooks, Xero, or Zoho Books) or a payments connector (PayPal, Square, or Stripe) | Gusto, Ramp, Shopify | CSV upload |
+| `month-end-prep` | a ledger (MYOB, NetSuite, QuickBooks, Xero, or Zoho Books) | Expensify, Gusto, PayPal, Ramp, Shopify, Square, Stripe | statement/CSV uploads |
+| `invoice-chase` | a ledger (MYOB, NetSuite, QuickBooks, Xero, or Zoho Books) | Airwallex, Gmail, Microsoft 365, PayPal, Shopify, Square, Stripe | AR CSV in, drafted reminders out |
+| `ap-processor` | a ledger (MYOB, NetSuite, QuickBooks, Xero, or Zoho Books) + Mail (Gmail or M365) | Expensify, Ramp | PDF/photo bill upload, entries exported |
+| `payroll-prep` | Gusto or QuickBooks Payroll | a ledger with a write path, for the journal post | timesheet upload → validated run sheet |
+| `inventory-planner` | Shopify or Square | Calendar, NetSuite, QuickBooks | sales + stock CSV |
+| `inbox-manager` | Gmail or M365 | Slack | pasted/forwarded email text |
+| `hiring-screener` | Mail (Gmail or M365) + Calendar | DocuSign, Drive or M365, Gusto, Trello | resume uploads, drafts for manual send |
+| `job-post-builder` | none | DocuSign, Drive or M365 | fully standalone |
+| `contract-review` | none (file upload) | DocuSign, Drive or M365, Gmail or M365 | file upload is the primary mode |
+| `tax-season-organizer` | a ledger (MYOB, NetSuite, QuickBooks, Xero, or Zoho Books) | Expensify, Gusto, PayPal, Ramp, Square, Stripe | CSV/document upload; the tax math is US-only (`../../../shared/currency-and-locale.md`) |
+| `ticket-deflector` | a payments connector (PayPal, Square, or Stripe), a CRM, or Mail | Atlassian, RingEx Chat, Shopify, Zoho Desk | pasted text |
+
+Ledger capability notes (what each holds, per its own reference files):
+- **MYOB** — P&L, AR and AP balances, sales totals, payment terms. No bank or cash balances, no vendor or payee detail, no customer email addresses. A skill that needs those asks the owner or uses another source, and says so.
+- **Xero** — P&L, bank transactions, bills, invoices, aged receivables, organisation record. Bill and invoice attachments are visible. See `../../month-end-prep/reference/xero-reconcile.md`.
+- **NetSuite** — full ledger via reports and SuiteQL. Common at the larger end of the segment.
+- **QuickBooks** — full ledger, with the report traps in `../../../shared/quickbooks-report-traps.md`.
+- **Zoho Books** — invoices, estimates, sales orders, expenses, purchase orders, customer payments, bank and cash account balances, contacts with a 1099 flag, organisation record. No bill object, no bank-transaction feed, no journals, no report endpoints (P&L, cash flow, aging). A skill that needs those asks for the export and says so; see `../../month-end-prep/reference/zoho-books-reconcile.md`.
+- Two ledgers connected: read both, one named as the source of record for totals, never summed.
+
+Storefront and point-of-sale capability notes (what each holds, per its own reference files; the category is defined in `../../../shared/connector-neutrality.md`):
+- **Shopify** — orders, customers, products with images, stock levels, and ShopifyQL analytics; shop record carries country and currency. No payouts: the connector's scopes exclude Shopify Payments, so settlement timing is asked of the owner, never inferred (`../../cash-flow-snapshot/reference/v2_sources.md`). One `productId` per inventory read (`../../../shared/connector-call-shapes.md`).
+- **Square** — orders with line items, catalog with images, inventory counts, payments, and payouts; merchant record carries country and currency. Payments list one location per call, so skills iterate locations. Payouts can be structurally absent on a production account.
+- A storefront alone satisfies any gate written as "a CRM, a payments connector, or a storefront": order history is who bought what and when.
+- Storefront and payments connectors both connected: an order and its settlement are one sale. Revenue comes from the one the owner names as source of record; the other supplies timing, fees, or stock.
+
+## Grow the business
+
+| Skill | Required | Optional | Zero-connector fallback |
+|---|---|---|---|
+| `lead-finder` | Apollo or Clay | HubSpot | web research + customer CSV |
+| `outreach-composer` | Gmail or M365 | Apollo, Clay, HubSpot, Mailchimp | draft-only, paste anywhere |
+| `speed-to-lead` | HubSpot + Mail (Gmail or M365) | Calendar, RingEx Chat | forwarded/pasted inquiries |
+| `lead-triage` | HubSpot | Apollo, Calendar, Clay, Gmail or M365 | pasted/uploaded lead list |
+| `proposal-builder` | Drive or M365 | Apollo, Atlassian, Canva, DocuSign, Notion, Trello, Zoom; a ledger or a payments connector for pricing history and the deposit invoice | uploads in, DOCX/PDF out |
+| `crm-autopilot` | a CRM (HubSpot, Monday.com, Salesforce, or Zoho CRM) | Calendar, Notion, RingEx Chat, Trello, Zoom | built-in spreadsheet CRM |
+| `growth-pulse` | HubSpot + one revenue source | Mailchimp, PayPal, Shopify, Square, Stripe, TikTok Ads | CSV exports |
+| `content-strategy` | QuickBooks or PayPal | Shopify, Square | sales CSV |
+| `social-content-engine` | Canva | HubSpot, Mailchimp, Notion, Shopify, Trello | calendar + copy + briefs for manual posting |
+| `canva-creator` | Canva, HubSpot | Shopify, Square — product photos and prices read from the store before the owner is asked for them | brief in; calendar, copy, and asset briefs out for manual design and posting |
+| `review-reputation` | a CRM, a payments connector (PayPal, Square, or Stripe), or a storefront (Shopify or Square) | Gmail or M365, Zoho Desk | pasted/exported reviews + web |
+| `ad-manager` | TikTok Ads (native); other ad platforms via a `build-connector` Zapier connection | Canva | CSV performance exports — the common path today |
+| `seo-ai-visibility` | none (web-native) | Shopify, Wix | crawls any public site |
+| `grant-rfp-writer` | Drive or M365 | DocuSign, Calendar, Trello | document upload + web search |
+
+## Build & meta
+
+| Skill | Required | Optional | Fallback |
+|---|---|---|---|
+| `build-agent` | none | whatever it builds against | native |
+| `build-connector` | none | Emergent, Zapier | it builds the fallback |
+| `smb-onboard` | none | all | interview-based, recommends what to connect |
+| `brand-style` | none | website via WebFetch | plain-words brand description; house default on skip |
+
+## Commands (11 folders + 1 in-skill chain)
+
+The eleven command folders are listed below. The twelfth flow is the scheduled inquiry chain that lives inside the `speed-to-lead` skill rather than in its own folder, and its gate matches `speed-to-lead` (HubSpot + Gmail).
+
+Commands inherit the requirements of the skills they chain. The lead skill's requirement decides whether the command can start; optional legs degrade per skill.
+
+| Command | Gate to start |
+|---|---|
+| `/report-pack` | any one data connector, or CSV |
+| `/pay-the-bills` | a ledger (MYOB, NetSuite, QuickBooks, Xero, or Zoho Books) + Mail (Gmail or M365) |
+| `/restock` | Shopify, Square, or CSV |
+| `/grow-pipeline` | Apollo or Clay, + HubSpot |
+| `/marketing-monday` | any one of PayPal / Shopify / HubSpot; TikTok Ads adds the paid-spend layer |
+| `/reactivate` | a CRM, a payments connector (PayPal, Square, or Stripe), or a storefront (Shopify or Square); a ledger and a support desk add invoice and service history |
+| `/plan-payroll` | a ledger (MYOB, NetSuite, QuickBooks, Xero, or Zoho Books); Gusto or QuickBooks Payroll for the timesheet leg |
+| `/close-month` | a ledger (MYOB, NetSuite, QuickBooks, Xero, or Zoho Books) |
+| `/tax-prep` | a ledger (MYOB, NetSuite, QuickBooks, Xero, or Zoho Books); the tax math runs only for a US business |
+| `/monday-brief` | none — degrades gracefully |
+| `/call-list` | HubSpot; Mail (Gmail or M365) adds email context, Google Calendar adds the blocks, Apollo or Clay adds company fit (metered, asked once) |