@mccaskie-labs/workbench-config 0.2.5 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @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

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/dist/capabilities.gen.d.ts

@@ -1,4 +1,4 @@
-export declare const MANIFEST_VERSION: "b74fc43c59b7";
+export declare const MANIFEST_VERSION: "de365af27674";
 export declare const capabilities: {
     readonly ai: {
         readonly $schema: "./schema.json";
@@ -909,10 +909,33 @@ export declare const capabilities: {
             readonly cost_hint_usd: 0;
             readonly 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";
         }];
+        readonly offer: {
+            readonly pattern: "settings";
+            readonly 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.";
+            readonly 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.";
+            readonly answers_file: "workbench/database.json";
+            readonly 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`.";
+            readonly questions: readonly [{
+                readonly id: "database.tables";
+                readonly sets: "tables";
+                readonly ask: "What should the app store, and who can see and change it?";
+                readonly style: "table";
+                readonly 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.";
+            }];
+            readonly not_asked: readonly [{
+                readonly sets: "keys";
+                readonly 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.";
+            }, {
+                readonly sets: "hosting";
+                readonly why: "Each project has its own staging and production databases, made by Workbench Control in the region set for the install.";
+            }, {
+                readonly sets: "sign_in_settings";
+                readonly why: "The database's sign-in settings follow the Workbench baseline (the workbench-sign-in skill).";
+            }];
+        };
         readonly delivery: {
             readonly choice: "built_in";
             readonly intro: "The app's own database, one for testing and one for the live site.";
-            readonly 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.";
         };
     };
     readonly email: {
@@ -1157,13 +1180,67 @@ export declare const capabilities: {
             readonly cost_hint_usd: 0;
             readonly note: "GET brand.json's logo.url from outside with no sign-in answers 200 with an image content type";
         }];
+        readonly offer: {
+            readonly pattern: "settings";
+            readonly when: "The app needs to send an email: a confirmation, receipt, notification, invitation or sign-in code.";
+            readonly 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.";
+            readonly answers_file: "workbench/email.json";
+            readonly 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.";
+            readonly questions: readonly [{
+                readonly id: "email.emails";
+                readonly sets: "emails";
+                readonly ask: "Which emails should the app send?";
+                readonly style: "table";
+                readonly 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.";
+            }, {
+                readonly id: "email.reply-to";
+                readonly sets: "reply_to";
+                readonly ask: "Where should a reply to these emails go?";
+                readonly style: "cards";
+                readonly answers: readonly [{
+                    readonly label: "Nowhere";
+                    readonly value: null;
+                    readonly means: "The emails come from an address that isn't read. Say so in the small print, with where to get help instead.";
+                }, {
+                    readonly label: "To the app";
+                    readonly value: "app";
+                    readonly means: "Replies go to an address the app reads itself (Workbench inbound email).";
+                }];
+                readonly other: {
+                    readonly kind: "text";
+                    readonly min: 6;
+                    readonly max: 254;
+                    readonly description: "An email address someone at the business reads.";
+                };
+                readonly must_ask: true;
+                readonly 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.";
+            }];
+            readonly not_asked: readonly [{
+                readonly sets: "sender";
+                readonly 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.";
+            }, {
+                readonly sets: "marketing";
+                readonly why: "Only transactional email exists: newsletters and other bulk mail are refused until Workbench has a sender for them, so offer none.";
+            }, {
+                readonly sets: "look";
+                readonly why: "Emails take the brand's name, colour and logo, and the project's `project.css` (see Restyling).";
+            }];
+            readonly drafts: {
+                readonly of: "wording for one email";
+                readonly surface: "ai";
+                readonly alias: "claude-default";
+                readonly count: 3;
+                readonly max_rounds: 3;
+                readonly job: "ai.drafts";
+                readonly command: "npx workbench-ai drafts text email_<id> --about \"<what the email is for, who gets it and its parts>\"";
+            };
+        };
         readonly styles: {
             readonly prefix: "wb-email-";
         };
         readonly delivery: {
             readonly choice: "built_in";
             readonly intro: "The emails the app sends, such as confirmations, receipts and sign-in codes.";
-            readonly when: "The app needs to send an email: a confirmation, receipt, notification, invitation or sign-in code.";
         };
     };
     readonly "email-inbound": {
@@ -1266,10 +1343,45 @@ export declare const capabilities: {
             readonly two_step: true;
             readonly note: "cf_email_routing_rule_delete returns a confirmation and changes nothing until Robert approves";
         }];
+        readonly offer: {
+            readonly pattern: "switch_on";
+            readonly when: "The client wants the app to receive email: replies to its messages, or an address such as hello@ that the app handles.";
+            readonly 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.";
+            readonly answers_file: "workbench/email-inbound.json";
+            readonly 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).";
+            readonly questions: readonly [{
+                readonly id: "email-inbound.addresses";
+                readonly sets: "addresses";
+                readonly ask: "Which addresses should the app receive, and what should it do with each message?";
+                readonly style: "table";
+                readonly 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.";
+            }, {
+                readonly id: "email-inbound.attachments";
+                readonly sets: "attachments";
+                readonly ask: "What should happen to files attached to these emails?";
+                readonly style: "cards";
+                readonly answers: readonly [{
+                    readonly label: "Leave them out";
+                    readonly value: "drop";
+                    readonly means: "The app keeps the words of each email, not its files. Nothing extra to store or check.";
+                }, {
+                    readonly label: "Keep them";
+                    readonly value: "keep";
+                    readonly means: "The app stores each file for the admins. Files can be large or unsafe, so keep only the types the job needs.";
+                }];
+                readonly 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`.";
+            }];
+            readonly not_asked: readonly [{
+                readonly sets: "domain";
+                readonly 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`).";
+            }, {
+                readonly sets: "forwarding";
+                readonly why: "Workbench never forwards mail outside the project or catches every address: each literal address goes to the app.";
+            }];
+        };
         readonly delivery: {
             readonly choice: "optional";
             readonly intro: "Receiving email at the project's own addresses, for the app to act on.";
-            readonly when: "The client wants the app to receive email: replies to its messages, or an address such as hello@ that the app handles.";
         };
     };
     readonly "email-sending": {
@@ -2729,10 +2841,45 @@ export declare const capabilities: {
             readonly cost_hint_usd: 0;
             readonly note: "The app's own checkStrings run passes in its tests, and npx workbench-strings check passes in CI";
         }];
+        readonly offer: {
+            readonly pattern: "project";
+            readonly 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.";
+            readonly 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.";
+            readonly answers_file: "workbench/strings.json";
+            readonly 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.";
+            readonly questions: readonly [{
+                readonly id: "strings.languages";
+                readonly sets: "languages";
+                readonly ask: "Does the site need to be in any language besides English?";
+                readonly style: "cards";
+                readonly answers: readonly [{
+                    readonly label: "English only";
+                    readonly value: "none";
+                    readonly means: "Every page and email is in English.";
+                }, {
+                    readonly label: "Another language later";
+                    readonly value: "later";
+                    readonly means: "English now. The words are kept so a translation can be added, checked by a native speaker, without changing the code.";
+                }];
+                readonly other: {
+                    readonly kind: "text";
+                    readonly min: 2;
+                    readonly max: 120;
+                    readonly description: "The languages, such as Filipino or Spanish.";
+                };
+                readonly 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.";
+            }];
+            readonly not_asked: readonly [{
+                readonly sets: "base";
+                readonly why: "The site is written first in English, in the readers' spelling from the country answers, so it isn't asked again.";
+            }, {
+                readonly sets: "wording";
+                readonly 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.";
+            }];
+        };
         readonly delivery: {
             readonly choice: "built_in";
             readonly intro: "The words on the app's screens and in its emails, kept in one place for each language.";
-            readonly 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.";
         };
     };
     readonly ui: {

package/dist/capabilities.gen.js

@@ -1,6 +1,6 @@
 // Generated by `npm run capabilities:build` from capabilities/*.json. Do not edit.
 // check:capabilities fails in Checks when this file is stale.
-export const MANIFEST_VERSION = "b74fc43c59b7";
+export const MANIFEST_VERSION = "de365af27674";
 export const capabilities = {
     "ai": {
         "$schema": "./schema.json",
@@ -1238,10 +1238,39 @@ export const capabilities = {
                 "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)."
+                }
+            ]
+        },
         "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."
         }
     },
     "email": {
@@ -1546,13 +1575,77 @@ export const capabilities = {
                 "note": "GET brand.json's logo.url from outside with no sign-in answers 200 with an image content type"
             }
         ],
+        "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>\""
+            }
+        },
         "styles": {
             "prefix": "wb-email-"
         },
         "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."
         }
     },
     "email-inbound": {
@@ -1682,10 +1775,54 @@ export const capabilities = {
                 "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."
+                }
+            ]
+        },
         "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."
         }
     },
     "email-sending": {
@@ -3610,10 +3747,53 @@ export const capabilities = {
                 "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."
+                }
+            ]
+        },
         "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."
         }
     },
     "ui": {

package/dist/capability-schema.d.ts

@@ -391,17 +391,10 @@ export declare const capabilitySchema: z.ZodObject<{
             optional: "optional";
         }>;
         intro: z.ZodString;
-        when: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type Capability = z.infer<typeof capabilitySchema>;
 export type Offer = z.infer<typeof offer>;
-/**
- * Components whose client questions are still being written (Robert,
- * 11 November 2026: every shared tool ships its questions). The list only
- * shrinks; a new component can't join it.
- */
-export declare const OFFER_PENDING: readonly ["database", "email", "email-inbound", "strings"];
 export interface ManifestProblem {
     file: string;
     check: "schema" | "proof" | "ids" | "surfaces" | "errors" | "generated";

package/dist/capability-schema.js

@@ -203,8 +203,6 @@ const delivery = z.strictObject({
     choice: z.enum(["built_in", "optional"]),
     /** One plain sentence for the owner, shown when Claude introduces the tools. */
     intro: z.string().min(1).max(160),
-    /** When the tool applies, in the client's words. Only for a component with no `offer`, whose `offer.when` says it. */
-    when: z.string().min(1).optional(),
 });
 const baseShape = {
     $schema: z.literal("./schema.json"),
@@ -262,12 +260,6 @@ export const capabilitySchema = z.strictObject(baseShape).superRefine((m, ctx) =
         }
     }
 });
-/**
- * Components whose client questions are still being written (Robert,
- * 11 November 2026: every shared tool ships its questions). The list only
- * shrinks; a new component can't join it.
- */
-export const OFFER_PENDING = ["database", "email", "email-inbound", "strings"];
 function checkOffer(file, component, o, seen) {
     const problems = [];
     const named = new Map();
@@ -381,21 +373,14 @@ export function checkManifests(files) {
             problems.push(...checkOffer(file, m.component, m.offer, seen));
         if (m.offer && m.no_offer)
             problems.push({ file, check: "schema", message: "has both offer and no_offer" });
-        const pending = OFFER_PENDING.includes(m.component);
-        if (!m.offer && !m.no_offer && !pending) {
+        if (!m.offer && !m.no_offer) {
             problems.push({ file, check: "schema", message: "every component ships its client questions: add an offer, or no_offer with the reason a client has nothing to answer" });
         }
-        if ((m.offer || m.no_offer) && pending)
-            problems.push({ file, check: "schema", message: `remove ${m.component} from OFFER_PENDING` });
         // §9.6: every component a client's Claude Code works with says how it reaches the project.
         if (m.no_offer && m.delivery)
             problems.push({ file, check: "schema", message: "has both no_offer and delivery: plumbing gets no skill of its own" });
         if (!m.no_offer && !m.delivery)
             problems.push({ file, check: "schema", message: "add delivery: whether the tool is built in or optional, and one sentence that introduces it to the owner" });
-        if (m.delivery && m.offer && m.delivery.when)
-            problems.push({ file, check: "schema", message: "delivery.when repeats offer.when: remove it" });
-        if (m.delivery && !m.offer && !m.delivery.when)
-            problems.push({ file, check: "schema", message: "delivery needs when, because there is no offer to say when the tool applies" });
     }
     const byComponent = new Map(manifests.map((m) => [m.component, m]));
     for (const { file, m, own } of deferred) {

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { WORKBENCH_ENVS, workbenchEnv, type WorkbenchEnv } from "./env.ts";
 export { defineConfig, type Config } from "./define-config.ts";
 export { sharedSecret, workerSecret, redact, redactAll, type SecretsStoreSecretLike } from "./secrets.ts";
 export { WorkbenchConfigError, type ConfigErrorCode, type ConfigProblem } from "./errors.ts";
-export { capabilitySchema, checkManifests, allowedSchemas, COMPONENTS, type Capability, type Component, type ManifestProblem, type Offer, OFFER_PATTERNS, OFFER_PENDING, } from "./capability-schema.ts";
+export { capabilitySchema, checkManifests, allowedSchemas, COMPONENTS, type Capability, type Component, type ManifestProblem, type Offer, OFFER_PATTERNS, } from "./capability-schema.ts";
 export { projectNotes, renderSkill, renderSkills, renderStart, skillName, SKILLS_DIR, START_SKILL, TOOLS_FILE } from "./skills.ts";
 export { toolsState } from "./tools.ts";
 export type { ToolChoices, ToolsState } from "./tools.ts";

package/dist/index.js

@@ -2,7 +2,7 @@ export { WORKBENCH_ENVS, workbenchEnv } from "./env.js";
 export { defineConfig } from "./define-config.js";
 export { sharedSecret, workerSecret, redact, redactAll } from "./secrets.js";
 export { WorkbenchConfigError } from "./errors.js";
-export { capabilitySchema, checkManifests, allowedSchemas, COMPONENTS, OFFER_PATTERNS, OFFER_PENDING, } from "./capability-schema.js";
+export { capabilitySchema, checkManifests, allowedSchemas, COMPONENTS, OFFER_PATTERNS, } from "./capability-schema.js";
 export { projectNotes, renderSkill, renderSkills, renderStart, skillName, SKILLS_DIR, START_SKILL, TOOLS_FILE } from "./skills.js";
 export { toolsState } from "./tools.js";
 export { capabilities, MANIFEST_VERSION } from "./capabilities.gen.js";

package/dist/skills.d.ts

@@ -6,7 +6,7 @@ export declare const TOOLS_FILE = "workbench/tools.json";
 export declare const START_SKILL = "workbench-start";
 /** The project's own notes on a tool, beside its generated skill: where this project wires it in. Never generated. */
 export declare const projectNotes: (component: string) => string;
-/** The SKILL.md for one manifest, or undefined when it has no `delivery` (plumbing). `guide` is its `capabilities/<component>.md`, when there is one. */
+/** The SKILL.md for one manifest, or undefined for plumbing (no `delivery` or no `offer`). `guide` is its `capabilities/<component>.md`, when there is one. */
 export declare function renderSkill(m: Capability, guide?: string): string | undefined;
 /** The `workbench-start` skill: every tool introduced to the owner, and how their choices are recorded (§9.6). */
 export declare function renderStart(manifests: readonly Capability[]): string;

package/dist/skills.js

@@ -120,14 +120,14 @@ function useBlock(m, guide) {
     out.push(`Read \`${projectNotes(m.component)}\` next, if it is there: it is this project's own note on where the tool is already wired in and how to call it here. It is the project's to edit; add to it when the wiring changes. Its limits, rules and error codes are in ${manifest}, and each package's API is in its \`README.md\` under \`node_modules/@mccaskie-labs/\`.`);
     return out;
 }
-/** The SKILL.md for one manifest, or undefined when it has no `delivery` (plumbing). `guide` is its `capabilities/<component>.md`, when there is one. */
+/** The SKILL.md for one manifest, or undefined for plumbing (no `delivery` or no `offer`). `guide` is its `capabilities/<component>.md`, when there is one. */
 export function renderSkill(m, guide) {
     const o = m.offer;
     const d = m.delivery;
-    if (!d)
+    if (!d || !o)
         return undefined;
-    const when = o?.when ?? d.when ?? m.summary;
-    const description = (o ? `${when} Offers Workbench ${m.title} and asks the client for its settings.` : `${when} Use Workbench ${m.title} for it.`).replaceAll("\n", " ");
+    const when = o.when;
+    const description = `${when} Offers Workbench ${m.title} and asks the client for its settings.`.replaceAll("\n", " ");
     const out = [
         "---",
         `name: ${skillName(m.component)}`,
@@ -146,10 +146,6 @@ export function renderSkill(m, guide) {
         "",
         ...beforeBlock(m),
     ];
-    if (!o) {
-        out.push("", "## Questions", "", "This tool's questions for the client aren't written yet. Use it with its defaults, tell the client that is what you did, and invent no setting. A choice only the client can make goes to them as a plain question.", ...(m.styles ? ["", "## Restyling", "", restyleLine(m.styles.prefix)] : []), "", ...useBlock(m, guide));
-        return `${out.join("\n")}\n`;
-    }
     out.push("", "## What to say", "", d.choice === "optional"
         ? `Once the owner's choice is yes, say: "${o.say}"`
         : `Say: "${o.say}" Don't ask whether to use Workbench or something of the client's own. If the client says they don't want it, stop and say what they give up.`, "", "## How to ask", "", ...(o.needs?.length ? [`- First check the project setup this needs: ${o.needs.map((n) => `\`workbench/${n}.json\``).join(", ")}. If one is missing, use that component's \`workbench-<component>\` skill first.`] : []), ...PATTERN_STEPS[o.pattern].map((step) => `- ${step}`), "- Ask with the AskUserQuestion tool, up to four questions per call. Give each question's answers in the order below; the first is recommended, so label it \"(Recommended)\", unless the question says none is. The tool adds \"Other\" itself.", "- Where the client accepts every recommendation, still ask each \"Must ask\" question.", "- An \"Other\" answer must meet the rule under its question. When it doesn't, say why and ask again. Never store a value outside it.", "- Ask nothing that isn't listed here, and invent no setting. A need the questions don't cover goes back to the client as a plain question, and isn't written to the answers file.", `- Write the answers to \`${o.answers_file}\`${o.per ? `, one entry per ${o.per}` : ""}: ${o.answers_format ?? `for each question its id, the value, and the client's own words when they typed "Other" or changed a recommendation.`}${o.generator ? ` Then run \`${o.generator}\`, which writes the code and refuses anything the package can't apply (it doesn't check the "Other" rules: you do). It builds nothing while an answers file is a draft. Never edit what it writes; change the answers file and run it again.` : ""}`, "", "## Questions", "", o.questions.map((q, i) => questionBlock(q, i + 1)).join("\n\n"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-config",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Workbench app configuration: WORKBENCH_ENV, typed variables that fail by name, secrets that are never printed, and the capabilities manifest.",
   "license": "UNLICENSED",
   "type": "module",