@mccaskie-labs/workbench-config 0.1.35 → 0.1.37

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @mccaskie-labs/workbench-config
 
+## 0.1.37
+
+### Patch Changes
+
+- Every tool reaches a client's Claude Code (docs/capabilities-manifest.md §9.6). Manifests gain `delivery`: whether a tool is built in or optional, one sentence that introduces it to the owner, and when it applies if it has no questions yet. `workbench-config skills` now writes a skill for every component with a `delivery`, not only those with an `offer`, with the component's guide under "How to use it", plus `workbench-start`, which introduces the tools and records the owner's choices of optional ones in `workbench/tools.json`. New: `workbench-config status`, which tells Claude Code at the start of a session what is undecided, unfinished or out of date, and `toolsState`. A project must run `npx workbench-config skills` after this update.
+
+## 0.1.36
+
+### Patch Changes
+
+- A manifest may say `styles: { prefix }` for a component that draws on a project's pages. Its generated skill then has a "Restyling" section: every class and variable is listed in `public/styles/workbench.css`, and the project restyles them in `public/styles/project.css`. The forms manifest has `styles: { prefix: "wb-form-" }`.
+
 ## 0.1.35
 
 ### Patch Changes

package/README.md

@@ -34,4 +34,8 @@ const { WORKBENCH_GATEWAY_KEY } = config.parse(env)
 
 `npx workbench-config check [dir]` compares the variable names in `.dev.vars` with `.dev.vars.example` and prints names only.
 
+`npx workbench-config skills [--check] [dir]` writes a project's `.claude/skills`: one skill for each Workbench tool a client's Claude Code works with, and `workbench-start`, which introduces them to the owner. `--check` fails when a file differs from what the installed version writes.
+
+`npx workbench-config status [dir]` prints what Claude Code needs to know at the start of a session: optional tools the owner hasn't decided on (`workbench/tools.json`), answers files still a draft, and skills that are out of date. It prints nothing when all is settled and always exits 0, so it can run from a `SessionStart` hook.
+
 Runs on Node 24 and the Cloudflare Workers runtime. `zod` 4 is a peer dependency.

package/capabilities/ai.json

@@ -5,6 +5,11 @@
   "title": "Claude through the Gateway",
   "summary": "Text, structured output and streaming from Claude, metered against the project's budget. Apps never hold an Anthropic key.",
   "status": "built",
+  "delivery": {
+    "choice": "built_in",
+    "intro": "Writing, summarising and answering questions with Claude, with a monthly spending cap.",
+    "when": "The client wants the app to write, summarise, sort, answer questions or pull details out of text with AI, as a feature visitors use or as something made once for the site."
+  },
   "surfaces": {
     "gateway": ["POST /anthropic/v1/messages", "POST /anthropic/v1/messages/count_tokens"],
     "package": ["createAi", "Ai.text", "Ai.structured", "Ai.stream", "Ai.countTokens", "Ai.budget", "createFakeAi", "checkWriting", "writingStops", "writingNotes", "writingFixNote"]

package/capabilities/analytics.json

@@ -5,6 +5,11 @@
   "title": "Page views and product events",
   "summary": "Cloudflare Web Analytics counts page views through a beacon on every page; product events go into the app's own database through workbench-analytics. Apps hold no Cloudflare token: Claude reads page views through Control.",
   "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."
+  },
   "surfaces": {
     "package": [
       "beaconScript",

package/capabilities/country.json

@@ -5,6 +5,11 @@
   "title": "Country packs and the one formatter",
   "summary": "workbench-country writes dates, times, numbers and money the way readers in the Philippines, Australia, the UK and the US expect, from one pack per country, and gives each pack's spelling for the Gateway. It runs in the app itself, with no Gateway call and no cost.",
   "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."
+  },
   "surfaces": {
     "package": [
       "COUNTRY_PACKS",

package/capabilities/database.json

@@ -5,6 +5,11 @@
   "title": "The app's own Supabase database",
   "summary": "Each project has its own Supabase projects, <id>-staging and <id>-production. Apps use them natively through workbench-supabase; Control creates them, writes their URL and keys onto the Workers, and applies migrations read from the repo.",
   "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."
+  },
   "surfaces": {
     "package": [
       "supabaseConfig",

package/capabilities/email-inbound.json

@@ -5,6 +5,11 @@
   "title": "Inbound email to the project's own Worker",
   "summary": "Email Routing receives mail on a domain in the project's namespace and runs one routing rule per address, each sending the mail to one of the project's own Workers. The Worker's email() handler parses it with postal-mime and the app stores or rejects it. Mail is never forwarded outside the project.",
   "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."
+  },
   "surfaces": {
     "tools": [
       "cf_email_routing_enable",

package/capabilities/email.json

@@ -5,6 +5,11 @@
   "title": "Transactional email through the Gateway",
   "summary": "Apps send transactional mail with workbench-email, or POST /v1/email/send directly. The Gateway checks the sender and recipients, keeps idempotency keys for 24 hours, meters every send, and hands the message to Cloudflare Email Sending. Apps hold no email credential.",
   "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."
+  },
   "surfaces": {
     "gateway": ["POST /v1/email/send"],
     "package": ["createMailer", "selectTransport", "Mailer.send", "captureSink", "WorkbenchEmailError"]

package/capabilities/forms.json

@@ -5,6 +5,10 @@
   "title": "Form validation",
   "summary": "workbench-forms checks what people type into a form with one validator that runs the same on the page and at the endpoint. It returns every problem at once as permanent codes, the tidied value to show back in each field and the value to store, with limits from the app's own register and country shapes from workbench-country. It runs in the app itself, with no Gateway call and no cost.",
   "status": "built",
+  "delivery": {
+    "choice": "built_in",
+    "intro": "Forms people fill in, checked the same way on the page and when they are sent."
+  },
   "surfaces": {
     "package": [
       "defineForm",
@@ -327,5 +331,8 @@
         "why": "The client's own words for an answered limit, otherwise \"Workbench default, not yet confirmed\"."
       }
     ]
+  },
+  "styles": {
+    "prefix": "wb-form-"
   }
 }

package/capabilities/image-search.json

@@ -5,6 +5,11 @@
   "title": "Image search through the Gateway",
   "summary": "Web image search through Serper, normalised to one result shape and metered against the project's budget. Apps never hold a Serper key.",
   "status": "built",
+  "delivery": {
+    "choice": "built_in",
+    "intro": "Finding existing pictures on the web.",
+    "when": "The client wants to find existing pictures on the web, for the site itself or as a search visitors use."
+  },
   "surfaces": {
     "gateway": [
       "POST /v1/images/search"

package/capabilities/images.json

@@ -5,6 +5,11 @@
   "title": "Image generation through the Gateway",
   "summary": "One image per call from Gemini or OpenAI, chosen by a Workbench alias and metered against the project's budget. Apps never hold a Google or OpenAI key, and the Gateway never falls back to another provider.",
   "status": "built",
+  "delivery": {
+    "choice": "built_in",
+    "intro": "Pictures made by AI from a description.",
+    "when": "The client wants a picture made by AI, such as an illustration, a hero image or a product mock-up, as a feature visitors use or once for the site."
+  },
   "surfaces": {
     "gateway": [
       "POST /v1/images/generate"

package/capabilities/pdf.json

@@ -5,6 +5,11 @@
   "title": "Branded PDFs",
   "summary": "workbench-pdf prints an app's content as a PDF with its brand.json logo, colours and fonts, in the app's own Worker through its Browser Rendering binding (BROWSER). Nothing goes through the Gateway and the app holds no Cloudflare token. The standard layout takes plain-text blocks; html() takes the app's own markup.",
   "status": "built",
+  "delivery": {
+    "choice": "optional",
+    "intro": "PDFs such as invoices and receipts, printed with the project's logo and colours.",
+    "when": "The client wants a PDF: an invoice, receipt, quote, certificate, report or anything else to download or print."
+  },
   "surfaces": {
     "package": [
       "createPdfMaker",

package/capabilities/schema.json

@@ -685,6 +685,45 @@
     "no_offer": {
       "type": "string",
       "minLength": 1
+    },
+    "styles": {
+      "type": "object",
+      "properties": {
+        "prefix": {
+          "type": "string",
+          "pattern": "^wb-[a-z]+-$"
+        }
+      },
+      "required": [
+        "prefix"
+      ],
+      "additionalProperties": false
+    },
+    "delivery": {
+      "type": "object",
+      "properties": {
+        "choice": {
+          "type": "string",
+          "enum": [
+            "built_in",
+            "optional"
+          ]
+        },
+        "intro": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 160
+        },
+        "when": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "choice",
+        "intro"
+      ],
+      "additionalProperties": false
     }
   },
   "required": [

package/capabilities/strings.json

@@ -5,6 +5,11 @@
   "title": "Words on screens and in emails",
   "summary": "workbench-strings holds the words an app's own screens and emails say: one file per language in the app's repository, looked up on the server with named placeholders and plurals, one fallback chain to the base language, language detection with country before the browser's language, back-translation notes stripped at build, and a review gate so no unreviewed translation is inferred for anyone. The standard's tests ship as a kit.",
   "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."
+  },
   "surfaces": {
     "package": [
       "defineStrings",

package/capabilities/ui.json

@@ -5,6 +5,11 @@
   "title": "One look for every page",
   "summary": "workbench-ui gives every Workbench page the same dark look: the page shell, a top bar with the environment tag, cards that fold, jump pills, outcome pills, and one way to write times, money and durations. It returns HTML text in the app's own Worker, with no Gateway call and no cost.",
   "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."
+  },
   "surfaces": {
     "package": [
       "shell",

package/dist/capabilities.gen.d.ts

@@ -1,4 +1,4 @@
-export declare const MANIFEST_VERSION: "d5366f2127fb";
+export declare const MANIFEST_VERSION: "8e65a2fda0b3";
 export declare const capabilities: {
     readonly ai: {
         readonly $schema: "./schema.json";
@@ -194,6 +194,11 @@ export declare const capabilities: {
             readonly expect: "pass";
             readonly cost_hint_usd: 0.008;
         }];
+        readonly delivery: {
+            readonly choice: "built_in";
+            readonly intro: "Writing, summarising and answering questions with Claude, with a monthly spending cap.";
+            readonly when: "The client wants the app to write, summarise, sort, answer questions or pull details out of text with AI, as a feature visitors use or as something made once for the site.";
+        };
     };
     readonly analytics: {
         readonly $schema: "./schema.json";
@@ -266,6 +271,11 @@ export declare const capabilities: {
             readonly cost_hint_usd: 0;
             readonly note: "Create the site, drive page views, query them back (cf_analytics_query, later)";
         }];
+        readonly delivery: {
+            readonly choice: "optional";
+            readonly intro: "Counting page views and the things visitors do on the site.";
+            readonly 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.";
+        };
     };
     readonly config: {
         readonly $schema: "./schema.json";
@@ -413,6 +423,11 @@ export declare const capabilities: {
             readonly cost_hint_usd: 0;
             readonly 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";
         }];
+        readonly delivery: {
+            readonly choice: "optional";
+            readonly intro: "Dates, times, numbers and money written the way readers in your country expect.";
+            readonly 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.";
+        };
     };
     readonly database: {
         readonly $schema: "./schema.json";
@@ -634,6 +649,11 @@ 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 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: {
         readonly $schema: "./schema.json";
@@ -877,6 +897,11 @@ 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 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": {
         readonly $schema: "./schema.json";
@@ -978,6 +1003,11 @@ 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 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": {
         readonly $schema: "./schema.json";
@@ -1316,6 +1346,13 @@ export declare const capabilities: {
                 readonly why: "The client's own words for an answered limit, otherwise \"Workbench default, not yet confirmed\".";
             }];
         };
+        readonly styles: {
+            readonly prefix: "wb-form-";
+        };
+        readonly delivery: {
+            readonly choice: "built_in";
+            readonly intro: "Forms people fill in, checked the same way on the page and when they are sent.";
+        };
     };
     readonly gateway: {
         readonly $schema: "./schema.json";
@@ -1649,6 +1686,11 @@ export declare const capabilities: {
             readonly smoke: true;
             readonly cost_hint_usd: 0.001;
         }];
+        readonly delivery: {
+            readonly choice: "built_in";
+            readonly intro: "Finding existing pictures on the web.";
+            readonly when: "The client wants to find existing pictures on the web, for the site itself or as a search visitors use.";
+        };
     };
     readonly images: {
         readonly $schema: "./schema.json";
@@ -1801,6 +1843,11 @@ export declare const capabilities: {
             readonly refusal: "invalid_request";
             readonly cost_hint_usd: 0;
         }];
+        readonly delivery: {
+            readonly choice: "built_in";
+            readonly intro: "Pictures made by AI from a description.";
+            readonly when: "The client wants a picture made by AI, such as an illustration, a hero image or a product mock-up, as a feature visitors use or once for the site.";
+        };
     };
     readonly pdf: {
         readonly $schema: "./schema.json";
@@ -1877,6 +1924,11 @@ export declare const capabilities: {
             readonly cost_hint_usd: 0;
             readonly note: "Prints the app's own HTML holding an image from a host not in allowOrigins; the PDF is made and the browser reports that image's request as blocked";
         }];
+        readonly delivery: {
+            readonly choice: "optional";
+            readonly intro: "PDFs such as invoices and receipts, printed with the project's logo and colours.";
+            readonly when: "The client wants a PDF: an invoice, receipt, quote, certificate, report or anything else to download or print.";
+        };
     };
     readonly strings: {
         readonly $schema: "./schema.json";
@@ -1984,6 +2036,11 @@ 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 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: {
         readonly $schema: "./schema.json";
@@ -2048,6 +2105,11 @@ export declare const capabilities: {
             readonly cost_hint_usd: 0;
             readonly note: "In the Worker itself: compares money (US$0.0042, US$12.50, and an en dash for nothing), duration (640 ms, 2.35 s, 3 min 5 s) and timeLeft against a fixed now (42 minutes left) with the expected text, and checks when and shortWhen write one fixed moment as its Manila day and hour with UTC beside it";
         }];
+        readonly delivery: {
+            readonly choice: "optional";
+            readonly intro: "A ready-made look for the pages only you and your admins see.";
+            readonly 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.";
+        };
     };
 };
 export type Alias = (typeof capabilities)["ai"]["allowed"]["aliases"][number]["alias"];

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 = "d5366f2127fb";
+export const MANIFEST_VERSION = "8e65a2fda0b3";
 export const capabilities = {
     "ai": {
         "$schema": "./schema.json",
@@ -293,7 +293,12 @@ export const capabilities = {
                 "expect": "pass",
                 "cost_hint_usd": 0.008
             }
-        ]
+        ],
+        "delivery": {
+            "choice": "built_in",
+            "intro": "Writing, summarising and answering questions with Claude, with a monthly spending cap.",
+            "when": "The client wants the app to write, summarise, sort, answer questions or pull details out of text with AI, as a feature visitors use or as something made once for the site."
+        }
     },
     "analytics": {
         "$schema": "./schema.json",
@@ -391,7 +396,12 @@ export const capabilities = {
                 "cost_hint_usd": 0,
                 "note": "Create the site, drive page views, query them back (cf_analytics_query, later)"
             }
-        ]
+        ],
+        "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."
+        }
     },
     "config": {
         "$schema": "./schema.json",
@@ -605,7 +615,12 @@ export const capabilities = {
                 "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"
             }
-        ]
+        ],
+        "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."
+        }
     },
     "database": {
         "$schema": "./schema.json",
@@ -910,7 +925,12 @@ export const capabilities = {
                 "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"
             }
-        ]
+        ],
+        "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."
+        }
     },
     "email": {
         "$schema": "./schema.json",
@@ -1213,7 +1233,12 @@ export const capabilities = {
                 "cost_hint_usd": 0,
                 "note": "GET brand.json's logo.url from outside with no sign-in answers 200 with an image content type"
             }
-        ]
+        ],
+        "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."
+        }
     },
     "email-inbound": {
         "$schema": "./schema.json",
@@ -1341,7 +1366,12 @@ export const capabilities = {
                 "two_step": true,
                 "note": "cf_email_routing_rule_delete returns a confirmation and changes nothing until Robert approves"
             }
-        ]
+        ],
+        "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."
+        }
     },
     "email-sending": {
         "$schema": "./schema.json",
@@ -1806,6 +1836,13 @@ export const capabilities = {
                     "why": "The client's own words for an answered limit, otherwise \"Workbench default, not yet confirmed\"."
                 }
             ]
+        },
+        "styles": {
+            "prefix": "wb-form-"
+        },
+        "delivery": {
+            "choice": "built_in",
+            "intro": "Forms people fill in, checked the same way on the page and when they are sent."
         }
     },
     "gateway": {
@@ -2250,7 +2287,12 @@ export const capabilities = {
                 "smoke": true,
                 "cost_hint_usd": 0.001
             }
-        ]
+        ],
+        "delivery": {
+            "choice": "built_in",
+            "intro": "Finding existing pictures on the web.",
+            "when": "The client wants to find existing pictures on the web, for the site itself or as a search visitors use."
+        }
     },
     "images": {
         "$schema": "./schema.json",
@@ -2458,7 +2500,12 @@ export const capabilities = {
                 "refusal": "invalid_request",
                 "cost_hint_usd": 0
             }
-        ]
+        ],
+        "delivery": {
+            "choice": "built_in",
+            "intro": "Pictures made by AI from a description.",
+            "when": "The client wants a picture made by AI, such as an illustration, a hero image or a product mock-up, as a feature visitors use or once for the site."
+        }
     },
     "pdf": {
         "$schema": "./schema.json",
@@ -2551,7 +2598,12 @@ export const capabilities = {
                 "cost_hint_usd": 0,
                 "note": "Prints the app's own HTML holding an image from a host not in allowOrigins; the PDF is made and the browser reports that image's request as blocked"
             }
-        ]
+        ],
+        "delivery": {
+            "choice": "optional",
+            "intro": "PDFs such as invoices and receipts, printed with the project's logo and colours.",
+            "when": "The client wants a PDF: an invoice, receipt, quote, certificate, report or anything else to download or print."
+        }
     },
     "strings": {
         "$schema": "./schema.json",
@@ -2682,7 +2734,12 @@ export const capabilities = {
                 "cost_hint_usd": 0,
                 "note": "The app's own checkStrings run passes in its tests, and npx workbench-strings check passes in CI"
             }
-        ]
+        ],
+        "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."
+        }
     },
     "ui": {
         "$schema": "./schema.json",
@@ -2773,6 +2830,11 @@ export const capabilities = {
                 "cost_hint_usd": 0,
                 "note": "In the Worker itself: compares money (US$0.0042, US$12.50, and an en dash for nothing), duration (640 ms, 2.35 s, 3 min 5 s) and timeLeft against a fixed now (42 minutes left) with the expected text, and checks when and shortWhen write one fixed moment as its Manila day and hour with UTC beside it"
             }
-        ]
+        ],
+        "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."
+        }
     }
 };

package/dist/capability-schema.d.ts

@@ -356,6 +356,17 @@ export declare const capabilitySchema: z.ZodObject<{
         needs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     no_offer: z.ZodOptional<z.ZodString>;
+    styles: z.ZodOptional<z.ZodObject<{
+        prefix: z.ZodString;
+    }, z.core.$strict>>;
+    delivery: z.ZodOptional<z.ZodObject<{
+        choice: z.ZodEnum<{
+            built_in: "built_in";
+            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>;

package/dist/capability-schema.js

@@ -192,6 +192,19 @@ const offer = z.strictObject({
     /** Project setup answers that must exist first: their components' answers files. */
     needs: z.array(z.string().regex(/^[a-z][a-z0-9-]*$/)).min(1).optional(),
 });
+/**
+ * How the tool reaches a client's project (docs/capabilities-manifest.md §9.6).
+ * Every component a client's Claude Code works with has one; plumbing
+ * (`no_offer`) has none.
+ */
+const delivery = z.strictObject({
+    /** `built_in`: stated to the owner, never asked. `optional`: asked once and recorded in workbench/tools.json. */
+    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"),
     format: z.literal(1),
@@ -217,6 +230,13 @@ const baseShape = {
     offer: offer.optional(),
     /** Why a client has nothing to answer for this component (plumbing). A manifest has `offer` or `no_offer`. */
     no_offer: z.string().min(1).optional(),
+    /**
+     * For a component that draws on a project's pages: the prefix of its classes
+     * and variables (docs/capabilities-manifest.md §10). Its skill then says how to
+     * restyle them through public/styles/project.css.
+     */
+    styles: z.strictObject({ prefix: z.string().regex(/^wb-[a-z]+-$/) }).optional(),
+    delivery: delivery.optional(),
 };
 /** One file in `capabilities/`. Parsing checks shape only; cross-references are checked by `checkManifests`. */
 export const capabilitySchema = z.strictObject(baseShape).superRefine((m, ctx) => {
@@ -358,6 +378,15 @@ export function checkManifests(files) {
         }
         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" });
     }
     return { manifests, problems };
 }

package/dist/cli.js

@@ -4,12 +4,15 @@
 // `npx workbench-config skills [--check] [dir]`: writes (or, with --check,
 // compares) the project skills generated from the manifests' offer sections
 // (docs/capabilities-manifest.md §9).
+// `npx workbench-config status [dir]`: tells Claude Code, at the start of a
+// session, which tools the owner hasn't decided on, which answers are
+// unfinished and whether the skills are current (§9.6). Always exits 0.
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { compareDevVars } from "./dev-vars.js";
-import { planSkills } from "./skills-plan.js";
-const USAGE = "Usage: workbench-config check [dir]\n       workbench-config skills [--check] [dir]";
+import { planSkills, statusLines } from "./skills-plan.js";
+const USAGE = "Usage: workbench-config check [dir]\n       workbench-config skills [--check] [dir]\n       workbench-config status [dir]";
 function checkDevVars(dir) {
     const examplePath = join(dir, ".dev.vars.example");
     const devVarsPath = join(dir, ".dev.vars");
@@ -69,12 +72,28 @@ function skills(args) {
     }
     return 0;
 }
+function status(dir) {
+    const pkg = join(dirname(fileURLToPath(import.meta.url)), "..");
+    const version = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8")).version;
+    // Runs from a SessionStart hook, so it never fails the session: a problem is one more line.
+    try {
+        const lines = statusLines(join(pkg, "capabilities"), dir);
+        if (lines.length)
+            console.log([`Workbench status (workbench-config ${version}):`, ...lines].join("\n"));
+    }
+    catch (e) {
+        console.log(`Workbench status (workbench-config ${version}) couldn't be read: ${e instanceof Error ? e.message : String(e)}. Run \`npx workbench-config skills --check\` to see why.`);
+    }
+    return 0;
+}
 function main(argv) {
     const [command, ...rest] = argv;
     if (command === "check")
         return checkDevVars(rest[0] ?? ".");
     if (command === "skills")
         return skills(rest);
+    if (command === "status")
+        return status(rest[0] ?? ".");
     console.error(USAGE);
     return 2;
 }

package/dist/index.d.ts

@@ -3,7 +3,9 @@ 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 { renderSkill, renderSkills, skillName, SKILLS_DIR } from "./skills.ts";
+export { 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";
 export { capabilities, MANIFEST_VERSION, type Alias, type GatewayScope } from "./capabilities.gen.ts";
 export { compareDevVars, parseDevVarNames } from "./dev-vars.ts";
 export { brandSchema, defineBrand, BRAND_FILE, resolveBrand, BRAND_DEFAULTS, type Brand, type ResolvedBrand } from "./brand.ts";

package/dist/index.js

@@ -3,7 +3,8 @@ 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 { renderSkill, renderSkills, skillName, SKILLS_DIR } from "./skills.js";
+export { 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";
 export { compareDevVars, parseDevVarNames } from "./dev-vars.js";
 export { brandSchema, defineBrand, BRAND_FILE, resolveBrand, BRAND_DEFAULTS } from "./brand.js";

package/dist/skills-plan.d.ts

@@ -1,7 +1,15 @@
+import { type Capability } from "./capability-schema.ts";
 export declare const GENERATED_MARK = "Generated by `npx workbench-config skills`";
 /** Skill files the manifests in `manifestDir` produce, and the generated ones in `projectDir` they don't. */
 export declare function planSkills(manifestDir: string, projectDir: string): {
     files: Record<string, string>;
     stale: string[];
+    manifests: Capability[];
     problems: string[];
 };
+/**
+ * What Claude Code is told at the start of a session (§9.6): tools the owner
+ * hasn't decided on, unfinished answers and skills out of date. No lines when
+ * everything is settled.
+ */
+export declare function statusLines(manifestDir: string, projectDir: string): string[];

package/dist/skills-plan.js

@@ -3,7 +3,8 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { checkManifests } from "./capability-schema.js";
-import { renderSkills, SKILLS_DIR } from "./skills.js";
+import { renderSkills, SKILLS_DIR, START_SKILL, TOOLS_FILE } from "./skills.js";
+import { toolsState } from "./tools.js";
 export const GENERATED_MARK = "Generated by `npx workbench-config skills`";
 /** Skill files the manifests in `manifestDir` produce, and the generated ones in `projectDir` they don't. */
 export function planSkills(manifestDir, projectDir) {
@@ -11,8 +12,11 @@ export function planSkills(manifestDir, projectDir) {
     for (const f of readdirSync(manifestDir).filter((f) => f.endsWith(".json") && f !== "schema.json")) {
         json[f] = JSON.parse(readFileSync(join(manifestDir, f), "utf8"));
     }
+    const guides = {};
+    for (const f of readdirSync(manifestDir).filter((f) => f.endsWith(".md")))
+        guides[f.slice(0, -3)] = readFileSync(join(manifestDir, f), "utf8");
     const { manifests, problems } = checkManifests(json);
-    const files = renderSkills(manifests);
+    const files = renderSkills(manifests, guides);
     const stale = [];
     const skillsDir = join(projectDir, SKILLS_DIR);
     if (existsSync(skillsDir)) {
@@ -22,5 +26,58 @@ export function planSkills(manifestDir, projectDir) {
                 stale.push(path);
         }
     }
-    return { files, stale, problems: problems.map((p) => `${p.file}: [${p.check}] ${p.message}`) };
+    return { files, stale, manifests, problems: problems.map((p) => `${p.file}: [${p.check}] ${p.message}`) };
+}
+/** Answers files under `workbench/` still marked `"status": "draft"`, as project paths. */
+function drafts(projectDir, dir = "workbench") {
+    const found = [];
+    if (!existsSync(join(projectDir, dir)))
+        return found;
+    for (const entry of readdirSync(join(projectDir, dir), { withFileTypes: true })) {
+        const path = `${dir}/${entry.name}`;
+        if (entry.isDirectory())
+            found.push(...drafts(projectDir, path));
+        else if (entry.name.endsWith(".json") && path !== TOOLS_FILE) {
+            try {
+                if (JSON.parse(readFileSync(join(projectDir, path), "utf8")).status === "draft")
+                    found.push(path);
+            }
+            catch {
+                // Not JSON: the tool that owns the file reports it.
+            }
+        }
+    }
+    return found.sort();
+}
+/**
+ * What Claude Code is told at the start of a session (§9.6): tools the owner
+ * hasn't decided on, unfinished answers and skills out of date. No lines when
+ * everything is settled.
+ */
+export function statusLines(manifestDir, projectDir) {
+    const { files, stale, manifests, problems } = planSkills(manifestDir, projectDir);
+    if (problems.length)
+        return ["The installed Workbench manifests don't check out, so nothing else was looked at:", ...problems.map((p) => `- ${p}`)];
+    const lines = [];
+    const toolsPath = join(projectDir, TOOLS_FILE);
+    const state = toolsState(manifests, existsSync(toolsPath) ? readFileSync(toolsPath, "utf8") : undefined);
+    const list = state.undecided.map((t) => `${t.component} (${t.title})`).join(", ");
+    if (state.problems.length) {
+        lines.push(`- \`${TOOLS_FILE}\` can't be used: ${state.problems.join("; ")}. Fix it with the owner before relying on it.`);
+    }
+    else if (!state.exists) {
+        lines.push(`- The owner hasn't been introduced to the Workbench tools yet (no \`${TOOLS_FILE}\`). Before other work, use the \`${START_SKILL}\` skill: introduce the tools and ask about the optional ones: ${list}.`);
+    }
+    else if (state.undecided.length) {
+        lines.push(`- New since the owner last chose, and not yet decided: ${list}. Use the \`${START_SKILL}\` skill to introduce and ask about ${state.undecided.length === 1 ? "it" : "them"}.`);
+    }
+    if (state.declined.length)
+        lines.push(`- The owner turned down: ${state.declined.join(", ")}. Don't use ${state.declined.length === 1 ? "it" : "them"} without asking.`);
+    const unfinished = drafts(projectDir);
+    if (unfinished.length)
+        lines.push(`- Unfinished answers: ${unfinished.map((p) => `\`${p}\``).join(", ")}. Show the owner what each holds and offer to carry on or start again, as its tool's skill says.`);
+    const wrong = Object.entries(files).filter(([path, text]) => !existsSync(join(projectDir, path)) || readFileSync(join(projectDir, path), "utf8") !== text);
+    if (wrong.length || stale.length)
+        lines.push("- The skills in `.claude/skills` don't match the installed workbench-config. Run `npx workbench-config skills` and commit the result before relying on them.");
+    return lines;
 }

package/dist/skills.d.ts

@@ -1,7 +1,12 @@
 import type { Capability } from "./capability-schema.ts";
 export declare const SKILLS_DIR = ".claude/skills";
 export declare const skillName: (component: string) => string;
-/** The SKILL.md for one manifest, or undefined when it has no offer. */
-export declare function renderSkill(m: Capability): string | undefined;
-/** Every skill the manifests produce, keyed by its path in a project. */
-export declare function renderSkills(manifests: readonly Capability[]): Record<string, string>;
+/** The owner's choices: which optional tools this project uses (§9.6). */
+export declare const TOOLS_FILE = "workbench/tools.json";
+export declare const START_SKILL = "workbench-start";
+/** The SKILL.md for one manifest, or undefined when it has no `delivery` (plumbing). `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;
+/** Every skill the manifests produce, keyed by its path in a project. `guides` holds each `capabilities/<component>.md` by component. */
+export declare function renderSkills(manifests: readonly Capability[], guides?: Readonly<Record<string, string>>): Record<string, string>;

package/dist/skills.js

@@ -1,10 +1,15 @@
-// Project skills generated from the manifests' `offer` sections
-// (docs/capabilities-manifest.md §9). `workbench-config skills` writes one
-// `.claude/skills/workbench-<component>/SKILL.md` per offer into a project,
-// and `--check` fails when a file differs, so the questions Claude Code asks
-// a client never drift from what the package accepts.
+// Project skills generated from the manifests (docs/capabilities-manifest.md
+// §9, §9.6). `workbench-config skills` writes one
+// `.claude/skills/workbench-<component>/SKILL.md` into a project for every
+// component with a `delivery`, plus `workbench-start`, which introduces them
+// to the owner. `--check` fails when a file differs, so what Claude Code
+// knows and asks never drifts from what the installed packages accept.
 export const SKILLS_DIR = ".claude/skills";
 export const skillName = (component) => `workbench-${component}`;
+/** The owner's choices: which optional tools this project uses (§9.6). */
+export const TOOLS_FILE = "workbench/tools.json";
+export const START_SKILL = "workbench-start";
+const GENERATED = (from) => `<!-- Generated by \`npx workbench-config skills\` from @mccaskie-labs/workbench-config, ${from}. Don't edit: \`npx workbench-config skills --check\` fails when this file differs. -->`;
 const show = (v) => (v === null ? "none" : `\`${JSON.stringify(v)}\``);
 const cell = (s) => s.replaceAll("|", "\\|").replaceAll("\n", " ");
 const sets = (q) => (typeof q.sets === "string" ? [q.sets] : q.sets).map((s) => `\`${s}\``).join(", ");
@@ -72,19 +77,59 @@ function draftsBlock(d) {
         "Never write drafts yourself and never call a vendor directly. If the command says there is no development key, say so and offer the standard version instead; never ask for a key in chat. Record the picked draft's request id, model and cost in the answers file.",
     ].join("\n");
 }
-/** The SKILL.md for one manifest, or undefined when it has no offer. */
-export function renderSkill(m) {
+/** A guide's text as a section of a skill: its title dropped, its headings one level down. */
+function guideSection(guide) {
+    let fenced = false;
+    const lines = guide.trim().split("\n").map((line) => {
+        if (line.startsWith("```"))
+            fenced = !fenced;
+        return !fenced && line.startsWith("#") ? `#${line}` : line;
+    });
+    if (lines[0]?.startsWith("## "))
+        lines.shift();
+    return lines.join("\n").trim();
+}
+function beforeBlock(m) {
+    if (m.delivery?.choice === "optional") {
+        return [
+            "## Before you use it",
+            "",
+            `This tool is the owner's choice. Read \`${TOOLS_FILE}\` first and find \`${m.component}\` under \`tools\`:`,
+            "",
+            "- `\"use\": true`: carry on.",
+            "- `\"use\": false`: the owner turned it down. Say so, with the date, and ask whether to use it this time before doing anything with it. If they say yes, update the file.",
+            `- Not there, or no file: ask now, with the AskUserQuestion tool: "Use Workbench ${m.title} for this? (Recommended)" or "No, do it another way". Record the answer the way the \`${START_SKILL}\` skill says, then carry on.`,
+        ];
+    }
+    return [
+        "## Before you use it",
+        "",
+        "This tool is built in to every Workbench project. Use it whenever this applies and say that you are. Don't ask whether to use Workbench or something of the client's own. The client chooses whether the app has the feature, not how it is built.",
+    ];
+}
+function useBlock(m, guide) {
+    const manifest = `\`node_modules/@mccaskie-labs/workbench-config/capabilities/${m.component}.json\``;
+    const out = ["## How to use it", ""];
+    if (guide)
+        out.push(guideSection(guide), "");
+    out.push(`Its limits, rules and error codes are in ${manifest}. Where the project already wires it in is in the project's \`CLAUDE.md\`, 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. */
+export function renderSkill(m, guide) {
     const o = m.offer;
-    if (!o)
+    const d = m.delivery;
+    if (!d)
         return undefined;
-    const description = `${o.when} Offers Workbench ${m.title} and asks the client for its settings.`.replaceAll("\n", " ");
+    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 out = [
         "---",
         `name: ${skillName(m.component)}`,
         `description: ${JSON.stringify(description)}`,
         "---",
         "",
-        `<!-- Generated by \`npx workbench-config skills\` from @mccaskie-labs/workbench-config, capabilities/${m.component}.json. Don't edit: \`npx workbench-config skills --check\` fails when this file differs. -->`,
+        GENERATED(`capabilities/${m.component}.json`),
         "",
         `# ${m.title}`,
         "",
@@ -92,40 +137,102 @@ export function renderSkill(m) {
         "",
         "## When this applies",
         "",
-        o.when,
-        "",
-        "## What to 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.`,
+        when,
         "",
-        "## 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)\". 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"),
+        ...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.", "", ...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)\". 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"));
     if (o.drafts)
         out.push("", draftsBlock(o.drafts));
     if (o.not_asked?.length) {
         out.push("", "## Not asked", "", ...o.not_asked.map((n) => `- \`${n.sets}\`: ${n.why}`));
     }
+    if (m.styles)
+        out.push("", "## Restyling", "", restyleLine(m.styles.prefix));
+    out.push("", ...useBlock(m, guide));
+    return `${out.join("\n")}\n`;
+}
+/** How a project restyles what a component draws (docs/capabilities-manifest.md §10). */
+function restyleLine(prefix) {
+    return `Everything this tool draws on a page has a \`${prefix}\` class with a default Workbench style, and its colours and sizes are \`--${prefix}*\` variables. All of them are listed, each with what it is, in \`public/styles/workbench.css\`, which \`npx workbench-ui styles\` generates: never edit it. To match the project's own look, write rules for those classes, or set the variables to the project's own colours, in \`public/styles/project.css\`. It loads after workbench.css and always wins. When the client asks for a different look, change project.css, never the tool's markup.`;
+}
+/** The `workbench-start` skill: every tool introduced to the owner, and how their choices are recorded (§9.6). */
+export function renderStart(manifests) {
+    const live = manifests.filter((m) => m.status !== "deprecated");
+    const row = (m) => `| ${cell(m.delivery.intro)} | \`${m.component}\` | \`${skillName(m.component)}\` |`;
+    const group = (choice) => live.filter((m) => m.delivery?.choice === choice).map(row);
+    const plumbing = live.filter((m) => !m.delivery).map((m) => m.title);
+    const description = "Use at the start of the first session in a Workbench project, whenever workbench/tools.json is missing or the session-start status lists tools the owner hasn't decided on, and when the owner asks what Workbench can do. Introduces every Workbench tool in plain words and records which optional ones the owner wants.";
+    const out = [
+        "---",
+        `name: ${START_SKILL}`,
+        `description: ${JSON.stringify(description)}`,
+        "---",
+        "",
+        GENERATED("every manifest in capabilities/"),
+        "",
+        "# Introduce the Workbench tools",
+        "",
+        "This project was made by Workbench, so it comes with tools that are already wired in. The owner may never have heard of them. Before other work, tell them what is here and ask which of the optional ones they want. Each tool has its own skill, named in the tables, which says how to use it and what to ask.",
+        "",
+        "## What to do",
+        "",
+        `1. Read \`${TOOLS_FILE}\`. A tool listed there is decided: don't ask about it again.`,
+        "2. If the file is missing, this is the first session. Introduce everything: say in two or three sentences that the project comes with Workbench tools, then show the two lists below in the owner's words (the first column), without package names.",
+        "3. If the file is there and only some optional tools are missing from it, they arrived in an update. Introduce only those.",
+        "4. Say the built-in tools are simply there. Don't ask about them.",
+        "5. Ask about each undecided optional tool with the AskUserQuestion tool, one question per tool, up to four questions per call: \"Use it (Recommended)\" or \"Not now\". Put what the tool does in the question, in plain words.",
+        "6. Write every answer to the file at once (the format is below), and tell the owner they can change any choice later by asking.",
+        "7. Then carry on with what the owner came to do. A tool with unanswered settings asks them when it is first used, through its own skill.",
+        "",
+        "Never use an optional tool the owner hasn't decided on, and never treat \"Not now\" as permanent: if they later ask for something it covers, its skill says to ask again.",
+        "",
+        "## Built in: say these are here, don't ask",
+        "",
+        "| What it does for the owner | Tool | Skill |",
+        "| --- | --- | --- |",
+        ...group("built_in"),
+        "",
+        "## Optional: ask about each one once",
+        "",
+        "| What it does for the owner | Tool | Skill |",
+        "| --- | --- | --- |",
+        ...group("optional"),
+        "",
+        ...(plumbing.length ? [`Underneath, with nothing for the owner to decide: ${plumbing.join("; ")}.`, ""] : []),
+        `## The choices file, \`${TOOLS_FILE}\``,
+        "",
+        "```json",
+        "{",
+        '  "format": 1,',
+        '  "tools": {',
+        '    "pdf": { "use": true, "decided": "2026-11-12" },',
+        '    "analytics": { "use": false, "decided": "2026-11-12", "reason": "We already count visits another way." }',
+        "  }",
+        "}",
+        "```",
+        "",
+        "- One entry per optional tool, keyed by the name in the Tool column. Built-in tools are never listed.",
+        "- `decided` is today's date. `reason` is the owner's own words, when they gave any.",
+        "- Commit it with the rest of the work. `npx workbench-config status` reads it at the start of every session and names anything still undecided.",
+    ];
     return `${out.join("\n")}\n`;
 }
-/** Every skill the manifests produce, keyed by its path in a project. */
-export function renderSkills(manifests) {
+/** Every skill the manifests produce, keyed by its path in a project. `guides` holds each `capabilities/<component>.md` by component. */
+export function renderSkills(manifests, guides = {}) {
     const files = {};
     for (const m of manifests) {
-        const text = renderSkill(m);
+        const text = renderSkill(m, guides[m.component]);
         if (text)
             files[`${SKILLS_DIR}/${skillName(m.component)}/SKILL.md`] = text;
     }
+    if (Object.keys(files).length)
+        files[`${SKILLS_DIR}/${START_SKILL}/SKILL.md`] = renderStart(manifests);
     return files;
 }

package/dist/tools.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { Capability } from "./capability-schema.ts";
+declare const toolsFile: z.ZodObject<{
+    format: z.ZodLiteral<1>;
+    tools: z.ZodRecord<z.ZodString, z.ZodObject<{
+        use: z.ZodBoolean;
+        decided: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ToolChoices = z.infer<typeof toolsFile>;
+export interface ToolsState {
+    /** False when the project has no choices file yet: the first session. */
+    exists: boolean;
+    /** Optional tools with no entry, as `{ component, title }`. */
+    undecided: {
+        component: string;
+        title: string;
+    }[];
+    /** Optional tools the owner said yes to, and no to. */
+    using: string[];
+    declined: string[];
+    /** What is wrong with the file: bad JSON, a bad shape, or a name that isn't an optional tool. */
+    problems: string[];
+}
+/** Compares a project's choices file (its text, or undefined when missing) with the installed manifests. */
+export declare function toolsState(manifests: readonly Capability[], text: string | undefined): ToolsState;
+export {};

package/dist/tools.js

@@ -0,0 +1,47 @@
+// The owner's choices of optional tools, `workbench/tools.json` in a project
+// (docs/capabilities-manifest.md §9.6). Pure: the file is read by the caller.
+import { z } from "zod";
+const toolsFile = z.strictObject({
+    format: z.literal(1),
+    tools: z.record(z.string(), z.strictObject({
+        use: z.boolean(),
+        decided: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "a date, YYYY-MM-DD"),
+        reason: z.string().min(1).optional(),
+    })),
+});
+/** Compares a project's choices file (its text, or undefined when missing) with the installed manifests. */
+export function toolsState(manifests, text) {
+    const optional = manifests.filter((m) => m.delivery?.choice === "optional" && m.status !== "deprecated");
+    const state = { exists: text !== undefined, undecided: [], using: [], declined: [], problems: [] };
+    let tools = {};
+    if (text !== undefined) {
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            state.problems.push("it isn't valid JSON");
+        }
+        if (json !== undefined) {
+            const parsed = toolsFile.safeParse(json);
+            if (parsed.success)
+                tools = parsed.data.tools;
+            else
+                state.problems.push(...parsed.error.issues.map((i) => `${i.path.join(".") || "file"}: ${i.message}`));
+        }
+    }
+    // A deprecated tool's entry stays valid: the owner chose it while it was offered.
+    const names = new Set(manifests.filter((m) => m.delivery?.choice === "optional").map((m) => m.component));
+    for (const name of Object.keys(tools)) {
+        if (!names.has(name))
+            state.problems.push(`${name} isn't an optional Workbench tool`);
+    }
+    for (const m of optional) {
+        const choice = tools[m.component];
+        if (!choice)
+            state.undecided.push({ component: m.component, title: m.title });
+        else
+            (choice.use ? state.using : state.declined).push(m.component);
+    }
+    return state;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-config",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "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",