@mccaskie-labs/workbench-config 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @mccaskie-labs/workbench-config
 
+## 0.3.0
+
+### Minor Changes
+
+- Every component now ships its client questions: email (which emails, where replies go, drafts of the wording), inbound email (which addresses, attachments), strings (other languages) and the database (what to store and who sees it). `OFFER_PENDING` is removed, and so is `delivery.when`: a component's `offer.when` says when its tool applies, and a manifest with neither `offer` nor `no_offer` fails the checks.
+
+## 0.2.5
+
+### Patch Changes
+
+- Client questions for country formats (where the readers are, the business's time zone, the currency), visitor counts (page views, and which actions to count) and admin pages (which pages, and who sees each).
+
 ## 0.2.4
 
 ### Patch Changes

package/capabilities/analytics.json

@@ -7,8 +7,7 @@
   "status": "built",
   "delivery": {
     "choice": "optional",
-    "intro": "Counting page views and the things visitors do on the site.",
-    "when": "The client wants to know how many people visit, which pages they open, or to count an action such as a sign-up or an order."
+    "intro": "Counting page views and the things visitors do on the site."
   },
   "surfaces": {
     "package": [
@@ -99,5 +98,50 @@
       "cost_hint_usd": 0,
       "note": "Create the site, drive page views, query them back (cf_analytics_query, later)"
     }
-  ]
+  ],
+  "offer": {
+    "pattern": "switch_on",
+    "when": "The client wants to know how many people visit, which pages they open, or to count an action such as a sign-up or an order.",
+    "say": "The project already has Workbench visitor counts: page views counted by Cloudflare without cookies, and the actions you choose counted in the app's own database. I'll switch on what you want.",
+    "answers_file": "workbench/analytics.json",
+    "answers_format": "`{ \"format\": 1, \"page_views\": true, \"events\": [{ \"name\": \"order.placed\", \"when\": \"a customer sends an order\", \"details\": [\"items\", \"total_band\"] }] }`. For page views, create the Web Analytics site with Workbench Control (`cf_web_analytics_site_create`), write its beacon token onto staging and production (`cf_worker_secret_put source=web_analytics`), and put `beacon(env)` on every page customers see. For each event, call `eventsFor(db).track(name, details)` where the action happens.",
+    "questions": [
+      {
+        "id": "analytics.page-views",
+        "sets": "page_views",
+        "ask": "Should the site count its page views?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "Yes",
+            "value": true,
+            "means": "How many people visit and which pages they open, counted by Cloudflare. No cookies, and no personal details kept."
+          },
+          {
+            "label": "No",
+            "value": false,
+            "means": "Nothing is counted on the site's pages."
+          }
+        ],
+        "note": "Only pages customers see; never the owner's or admins' pages."
+      },
+      {
+        "id": "analytics.actions",
+        "sets": "events",
+        "ask": "Which actions should be counted?",
+        "style": "table",
+        "note": "Propose the few actions that show whether the site is working for the business (a sign-up, an order, a booking, a form sent), each with a name (`thing.past_verb`, lower case: `order.placed`), when it happens in the client's words, and its details. Details are counts, choices and bands (`items`, `plan`, `total_band`), never an email address, a name, a phone number or free text someone typed. The client accepts, removes or adds; an empty list is fine."
+      }
+    ],
+    "not_asked": [
+      {
+        "sets": "consent",
+        "why": "The page-view counter sets no cookies and keeps no personal details, and events hold none either, so they add nothing that a cookie notice would need to cover."
+      },
+      {
+        "sets": "reports",
+        "why": "Page views are seen in Cloudflare's Web Analytics, and events are rows in the app's own `events` table; ask what the owner wants to see when they ask for a report."
+      }
+    ]
+  }
 }

package/capabilities/country.json

@@ -7,8 +7,7 @@
   "status": "built",
   "delivery": {
     "choice": "optional",
-    "intro": "Dates, times, numbers and money written the way readers in your country expect.",
-    "when": "The app shows a date, a time, a number, a phone number or an amount of money to its readers, or the client says where their readers are."
+    "intro": "Dates, times, numbers and money written the way readers in your country expect."
   },
   "surfaces": {
     "package": [
@@ -84,5 +83,163 @@
       "cost_hint_usd": 0,
       "note": "Every pack's spelling is one the Gateway accepts (en-PH, en-AU, en-GB, en-US), checked against the ai manifest's spellings; no Gateway call"
     }
-  ]
+  ],
+  "offer": {
+    "pattern": "project",
+    "when": "The app shows a date, a time, a number, a phone number or an amount of money to its readers, or the client says where their readers are.",
+    "say": "I'll write dates, times and money with Workbench country formats, the way your readers expect them. That needs to know where they are, once for the whole site.",
+    "answers_file": "workbench/country.json",
+    "answers_format": "`{ \"format\": 1, \"country\": \"AU\", \"time_zone\": null, \"currency\": null }`: the country code (or `ZZ`, the package's WORLDWIDE, for readers everywhere), and an IANA time zone or `{ \"code\", \"symbol\" }` currency only when they differ from the country's own (the Australian and US time questions both fill `time_zone`). Then set `READERS` in `src/lib/country.ts` to match: `audiencePack({ country, timeZone, currency })`, leaving out what is null. Every page, email, PDF and form reads `READERS`, so nothing else changes.",
+    "questions": [
+      {
+        "id": "country.where",
+        "sets": "audience.country",
+        "ask": "Where are most of the site's readers?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "Australia",
+            "value": "AU",
+            "means": "26 September 2026, A$1,400, Sydney time, Australian spelling."
+          },
+          {
+            "label": "The Philippines",
+            "value": "PH",
+            "means": "September 26, 2026, ₱1,400, Manila time."
+          },
+          {
+            "label": "The United Kingdom",
+            "value": "GB",
+            "means": "26 September 2026, £1,400, UK time, British spelling."
+          },
+          {
+            "label": "The United States",
+            "value": "US",
+            "means": "September 26, 2026, US$1,400, Eastern time, American spelling."
+          }
+        ],
+        "other": {
+          "kind": "text",
+          "min": 2,
+          "max": 60,
+          "description": "Another country, or readers all over the world."
+        },
+        "note": "Recommend Australia unless the client's words say otherwise. A country with no pack yet, or readers everywhere, gets the neutral one (`ZZ`: 26 September 2026, 24-hour clock, UTC, US$): say so, and ask for the currency."
+      },
+      {
+        "id": "country.au-time",
+        "sets": "audience.time_zone.au",
+        "ask": "Which Australian time should the site show?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "Sydney, Melbourne, Canberra",
+            "value": null,
+            "means": "The pack's own (Australia/Sydney), with daylight saving."
+          },
+          {
+            "label": "Brisbane",
+            "value": "Australia/Brisbane",
+            "means": "Queensland, no daylight saving."
+          },
+          {
+            "label": "Adelaide",
+            "value": "Australia/Adelaide",
+            "means": "South Australia, half an hour behind Sydney."
+          },
+          {
+            "label": "Perth",
+            "value": "Australia/Perth",
+            "means": "Western Australia."
+          }
+        ],
+        "other": {
+          "kind": "text",
+          "min": 5,
+          "max": 40,
+          "description": "Another Australian time zone, such as Australia/Darwin or Australia/Hobart."
+        },
+        "when": {
+          "id": "country.where",
+          "is": [
+            "AU"
+          ]
+        },
+        "note": "The time zone of the business, where bookings and opening hours happen. Hobart follows Sydney; Darwin is Australia/Darwin."
+      },
+      {
+        "id": "country.us-time",
+        "sets": "audience.time_zone.us",
+        "ask": "Which US time should the site show?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "Eastern",
+            "value": null,
+            "means": "The pack's own (America/New_York)."
+          },
+          {
+            "label": "Central",
+            "value": "America/Chicago"
+          },
+          {
+            "label": "Mountain",
+            "value": "America/Denver"
+          },
+          {
+            "label": "Pacific",
+            "value": "America/Los_Angeles"
+          }
+        ],
+        "other": {
+          "kind": "text",
+          "min": 5,
+          "max": 40,
+          "description": "Another US time zone, such as America/Phoenix or Pacific/Honolulu."
+        },
+        "when": {
+          "id": "country.where",
+          "is": [
+            "US"
+          ]
+        },
+        "note": "The time zone of the business."
+      },
+      {
+        "id": "country.currency",
+        "sets": "audience.currency",
+        "ask": "Which money are prices in?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "The country's own",
+            "value": null,
+            "means": "A$ in Australia, ₱ in the Philippines, £ in the UK, US$ in the US."
+          },
+          {
+            "label": "US dollars",
+            "value": "USD",
+            "means": "Shown as US$1,400."
+          }
+        ],
+        "other": {
+          "kind": "text",
+          "min": 3,
+          "max": 3,
+          "description": "Another currency's three-letter code, such as NZD or EUR."
+        },
+        "note": "Write a currency other than the country's as `{ \"code\", \"symbol\" }` (NZD is NZ$). Ask it only when the client sells something; otherwise record null."
+      }
+    ],
+    "not_asked": [
+      {
+        "sets": "audience.format",
+        "why": "Date order, the clock, number separators, spelling and phone number shapes all come from the country's pack, so they match what readers expect without asking."
+      },
+      {
+        "sets": "audience.owner_pages",
+        "why": "Pages only the owner sees use workbench-ui's own times and money, not the readers'."
+      }
+    ]
+  }
 }

package/capabilities/database.json

@@ -7,8 +7,7 @@
   "status": "built",
   "delivery": {
     "choice": "built_in",
-    "intro": "The app's own database, one for testing and one for the live site.",
-    "when": "The app needs to store or read data, or the client asks for a change to what is stored: a new table, column, rule or migration."
+    "intro": "The app's own database, one for testing and one for the live site."
   },
   "surfaces": {
     "package": [
@@ -237,5 +236,35 @@
       "cost_hint_usd": 0,
       "note": "On a project's staging: cf_turnstile_widget_create and the turnstile_sitekey and turnstile_secret sources; the sign-in page shows the check, /auth/code without a passed token sends no code, and with one it does"
     }
-  ]
+  ],
+  "offer": {
+    "pattern": "settings",
+    "when": "The app needs to store or read data, or the client asks for a change to what is stored: a new table, column, rule or migration.",
+    "say": "The app's data goes in its own Workbench database, one for testing and one for the live site. I'll propose what to store and who can see it, and change it with a migration you can undo.",
+    "answers_file": "workbench/database.json",
+    "answers_format": "`{ \"format\": 1, \"status\": \"draft\", \"tables\": [{ \"name\": \"orders\", \"row\": \"one order\", \"columns\": [{ \"name\": \"total\", \"kind\": \"money\", \"required\": true }], \"read\": \"own\", \"change\": \"own\" }] }`. Then write one migration (`supabase/migrations/<14 digits>_<name>.sql`) with its down file, turning on row-level security with one policy per answer, apply it on staging with Workbench Control (`sb_migration_apply`), and refresh `supabase/staging-columns.json`.",
+    "questions": [
+      {
+        "id": "database.tables",
+        "sets": "tables",
+        "ask": "What should the app store, and who can see and change it?",
+        "style": "table",
+        "note": "Propose the tables the request needs, each with what one row is, its columns (name, kind such as text, number, money, date, yes/no, a link to another table; and whether it is required), and who may read and who may change its rows: `own` (the person who made the row), `admins`, `signed_in` (anyone signed in) or `public` (anyone, read only). Recommend `own` for anything about a person. Show money as whole cents, never a fraction. The client accepts, removes or adds tables and columns."
+      }
+    ],
+    "not_asked": [
+      {
+        "sets": "keys",
+        "why": "The app reaches the database as the signed-in person (`dbAs`), so row-level security decides what each person sees; the template holds no secret key."
+      },
+      {
+        "sets": "hosting",
+        "why": "Each project has its own staging and production databases, made by Workbench Control in the region set for the install."
+      },
+      {
+        "sets": "sign_in_settings",
+        "why": "The database's sign-in settings follow the Workbench baseline (the workbench-sign-in skill)."
+      }
+    ]
+  }
 }

package/capabilities/email-inbound.json

@@ -7,8 +7,7 @@
   "status": "built",
   "delivery": {
     "choice": "optional",
-    "intro": "Receiving email at the project's own addresses, for the app to act on.",
-    "when": "The client wants the app to receive email: replies to its messages, or an address such as hello@ that the app handles."
+    "intro": "Receiving email at the project's own addresses, for the app to act on."
   },
   "surfaces": {
     "tools": [
@@ -129,5 +128,50 @@
       "two_step": true,
       "note": "cf_email_routing_rule_delete returns a confirmation and changes nothing until Robert approves"
     }
-  ]
+  ],
+  "offer": {
+    "pattern": "switch_on",
+    "when": "The client wants the app to receive email: replies to its messages, or an address such as hello@ that the app handles.",
+    "say": "The project can already receive email with Workbench inbound email: each address goes straight to the app, which decides what to do with every message. I'll switch on the addresses you want.",
+    "answers_file": "workbench/email-inbound.json",
+    "answers_format": "`{ \"format\": 1, \"addresses\": [{ \"name\": \"hello\", \"does\": \"saves it as a message the admins see\" }] }`. Then set `INBOUND_EMAIL` to `\"on\"` in `wrangler.jsonc`, write `handleEmail` in `src/app.ts` to do what each address `does`, and make the addresses with Workbench Control: `cf_email_routing_enable`, then `cf_email_routing_rule_create` for each address on staging first (the capabilities guide below has the steps).",
+    "questions": [
+      {
+        "id": "email-inbound.addresses",
+        "sets": "addresses",
+        "ask": "Which addresses should the app receive, and what should it do with each message?",
+        "style": "table",
+        "note": "Propose the addresses the request needs, each with its name (the part before @, lower case: `hello`, `bookings`) and what the app does with a message, in the client's words: save it for the admins to read, add it to a booking, answer it automatically. One address, one job. Say plainly that the app reads the mail itself: nothing is forwarded to anyone's inbox."
+      },
+      {
+        "id": "email-inbound.attachments",
+        "sets": "attachments",
+        "ask": "What should happen to files attached to these emails?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "Leave them out",
+            "value": "drop",
+            "means": "The app keeps the words of each email, not its files. Nothing extra to store or check."
+          },
+          {
+            "label": "Keep them",
+            "value": "keep",
+            "means": "The app stores each file for the admins. Files can be large or unsafe, so keep only the types the job needs."
+          }
+        ],
+        "note": "With keep, ask which types (photos, PDFs) and store them outside the Worker, in file storage the app already has, or ask the owner before adding some; refuse other types with `reject`."
+      }
+    ],
+    "not_asked": [
+      {
+        "sets": "domain",
+        "why": "Addresses are on the project's own email domain: its staging name first, and the client's own domain once it is attached for production (`cf_zone_attach`)."
+      },
+      {
+        "sets": "forwarding",
+        "why": "Workbench never forwards mail outside the project or catches every address: each literal address goes to the app."
+      }
+    ]
+  }
 }

package/capabilities/email.json

@@ -7,8 +7,7 @@
   "status": "built",
   "delivery": {
     "choice": "built_in",
-    "intro": "The emails the app sends, such as confirmations, receipts and sign-in codes.",
-    "when": "The app needs to send an email: a confirmation, receipt, notification, invitation or sign-in code."
+    "intro": "The emails the app sends, such as confirmations, receipts and sign-in codes."
   },
   "surfaces": {
     "gateway": ["POST /v1/email/send"],
@@ -71,5 +70,70 @@
   ],
   "styles": {
     "prefix": "wb-email-"
+  },
+  "offer": {
+    "pattern": "settings",
+    "when": "The app needs to send an email: a confirmation, receipt, notification, invitation or sign-in code.",
+    "say": "I'll send these with Workbench email, which sends from the app's own address in your brand, with no email key in the app. The sign-in codes are already there; I'll add yours beside them.",
+    "answers_file": "workbench/email.json",
+    "answers_format": "`{ \"format\": 1, \"status\": \"draft\", \"reply_to\": null, \"emails\": [{ \"id\": \"order_confirmed\", \"when\": \"a customer sends an order\", \"to\": \"the customer\", \"parts\": [\"heading\", \"paragraph\", \"button\"], \"link_changes_something\": false }] }`. Declare each email in `src/lib/emails.ts` with `defineEmails` (stream `transactional`, shell `account`, `decidedBy` naming this answers file), put its words in the strings under `email.<id>.<key>`, and send it with `mailerFor(env)` and an `idempotencyKey` whenever a retry could repeat it.",
+    "questions": [
+      {
+        "id": "email.emails",
+        "sets": "emails",
+        "ask": "Which emails should the app send?",
+        "style": "table",
+        "note": "Propose the emails the request needs, each with an id (snake_case: `order_confirmed`), when it is sent, who gets it, its parts in order (heading, paragraphs, a button and its link, small print) and whether its link changes something (then the link lands on a confirmation page first). Only emails a person's own action or account causes: receipts, confirmations, notices. The client accepts, removes or adds. The wording is drafted afterwards, one email at a time."
+      },
+      {
+        "id": "email.reply-to",
+        "sets": "reply_to",
+        "ask": "Where should a reply to these emails go?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "Nowhere",
+            "value": null,
+            "means": "The emails come from an address that isn't read. Say so in the small print, with where to get help instead."
+          },
+          {
+            "label": "To the app",
+            "value": "app",
+            "means": "Replies go to an address the app reads itself (Workbench inbound email)."
+          }
+        ],
+        "other": {
+          "kind": "text",
+          "min": 6,
+          "max": 254,
+          "description": "An email address someone at the business reads."
+        },
+        "must_ask": true,
+        "note": "A typed address goes in each send as `replyTo`; check it looks like an email address. With the app, the workbench-email-inbound skill sets up the address."
+      }
+    ],
+    "not_asked": [
+      {
+        "sets": "sender",
+        "why": "Emails come from the project's own sending address (`FROM` in `src/lib/email.ts`) on its own domain, which Workbench Control sets up."
+      },
+      {
+        "sets": "marketing",
+        "why": "Only transactional email exists: newsletters and other bulk mail are refused until Workbench has a sender for them, so offer none."
+      },
+      {
+        "sets": "look",
+        "why": "Emails take the brand's name, colour and logo, and the project's `project.css` (see Restyling)."
+      }
+    ],
+    "drafts": {
+      "of": "wording for one email",
+      "surface": "ai",
+      "alias": "claude-default",
+      "count": 3,
+      "max_rounds": 3,
+      "job": "ai.drafts",
+      "command": "npx workbench-ai drafts text email_<id> --about \"<what the email is for, who gets it and its parts>\""
+    }
   }
 }

package/capabilities/schema.json

@@ -745,10 +745,6 @@
           "type": "string",
           "minLength": 1,
           "maxLength": 160
-        },
-        "when": {
-          "type": "string",
-          "minLength": 1
         }
       },
       "required": [

package/capabilities/strings.json

@@ -7,8 +7,7 @@
   "status": "built",
   "delivery": {
     "choice": "built_in",
-    "intro": "The words on the app's screens and in its emails, kept in one place for each language.",
-    "when": "The client wants to add or change wording on a page or in an email, or asks about showing the app in another language."
+    "intro": "The words on the app's screens and in its emails, kept in one place for each language."
   },
   "surfaces": {
     "package": [
@@ -132,5 +131,49 @@
       "cost_hint_usd": 0,
       "note": "The app's own checkStrings run passes in its tests, and npx workbench-strings check passes in CI"
     }
-  ]
+  ],
+  "offer": {
+    "pattern": "project",
+    "when": "The client wants to add or change wording on a page or in an email, or asks about showing the app in another language.",
+    "say": "Every word the app shows is kept in one place with Workbench strings, so changing wording never means hunting through code, and other languages can be added later.",
+    "answers_file": "workbench/strings.json",
+    "answers_format": "`{ \"format\": 1, \"languages\": [\"en-AU\"], \"later\": [\"fil\"] }`: the language the site is written in first, and any the client wants later. New wording goes into `strings/strings.<base>.json` with one key per sentence, and `npm run check:strings` checks it.",
+    "questions": [
+      {
+        "id": "strings.languages",
+        "sets": "languages",
+        "ask": "Does the site need to be in any language besides English?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "English only",
+            "value": "none",
+            "means": "Every page and email is in English."
+          },
+          {
+            "label": "Another language later",
+            "value": "later",
+            "means": "English now. The words are kept so a translation can be added, checked by a native speaker, without changing the code."
+          }
+        ],
+        "other": {
+          "kind": "text",
+          "min": 2,
+          "max": 120,
+          "description": "The languages, such as Filipino or Spanish."
+        },
+        "note": "Translations come with a Workbench tool that isn't built yet: record the languages under `later`, keep every word in the catalogue, and tell the client a translation goes live only once a named native speaker has checked it."
+      }
+    ],
+    "not_asked": [
+      {
+        "sets": "base",
+        "why": "The site is written first in English, in the readers' spelling from the country answers, so it isn't asked again."
+      },
+      {
+        "sets": "wording",
+        "why": "Wording is content, not a setting: the client says what they want in their own words, or asks for drafts (the workbench-ai skill), and it goes into the catalogue."
+      }
+    ]
+  }
 }

package/capabilities/ui.json

@@ -7,8 +7,7 @@
   "status": "built",
   "delivery": {
     "choice": "optional",
-    "intro": "A ready-made look for the pages only you and your admins see.",
-    "when": "The client wants a page only the owner or the app's admins see: a dashboard, a list, a settings page or a status page."
+    "intro": "A ready-made look for the pages only you and your admins see."
   },
   "surfaces": {
     "package": [
@@ -95,5 +94,31 @@
   ],
   "styles": {
     "prefix": "wb-ui-"
+  },
+  "offer": {
+    "pattern": "switch_on",
+    "when": "The client wants a page only the owner or the app's admins see: a dashboard, a list, a settings page or a status page.",
+    "say": "I'll build this with the Workbench owner-page look, the same top bar, cards and pills as the other admin pages, so it's quick to build and consistent. Your customers never see it.",
+    "answers_file": "workbench/ui.json",
+    "answers_format": "`{ \"format\": 1, \"pages\": [{ \"path\": \"/admin/orders\", \"what\": \"every order this month, newest first\", \"who\": \"admins\" }] }`. Build each page with `shell`, `topBar`, `card` and `pill`. An `admins` page lives under `/admin/` and checks `requireUser` and `app_admins` (the workbench-sign-in skill); an `owner` page lives under `/owner/` and is behind Access in production.",
+    "questions": [
+      {
+        "id": "ui.pages",
+        "sets": "pages",
+        "ask": "Which admin pages should the app have?",
+        "style": "table",
+        "note": "Propose the pages the request needs, each with its path, what it shows or lets them change in the client's words, and who sees it: `admins` (the business's people, who sign in to the app) or `owner` (whoever runs the app's Workbench, through Access). Recommend `admins` unless the page is about running the app itself, such as a status page. The client accepts, removes or adds pages."
+      }
+    ],
+    "not_asked": [
+      {
+        "sets": "look",
+        "why": "Every admin page has the same Workbench look, so the business's people learn it once. Restyle it in project.css (see Restyling) if the client wants their colours."
+      },
+      {
+        "sets": "formats",
+        "why": "Times, amounts and durations on these pages come from workbench-ui's `when`, `money` and `duration`. What customers see uses the readers' formats (the workbench-country skill)."
+      }
+    ]
   }
 }