@mccaskie-labs/workbench-config 0.1.27 → 0.1.29

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @mccaskie-labs/workbench-config
 
+## 0.1.29
+
+### Patch Changes
+
+- Offer patterns (docs/capabilities-manifest.md §9.5): `offer.pattern` (settings, drafts, feature_or_content, project, switch_on), `question.when`, `offer.drafts`, `offer.needs` and a top-level `no_offer`. Every manifest needs an offer or a no_offer reason, except components in `OFFER_PENDING`. gateway, config and email-sending state why a client has nothing to answer. Generated skills gain per-pattern steps, branches and a Drafts section.
+
+## 0.1.28
+
+### Patch Changes
+
+- Client questions: manifests gain an optional `offer` section (docs/capabilities-manifest.md §9), checked for unique question ids, two to four answers on a cards question, no written "Other", and each package option set once. `renderSkill` and `npx workbench-config skills [--check] [dir]` write or compare the project skills `.claude/skills/workbench-<component>/SKILL.md` generated from them. No manifest has an offer yet.
+
 ## 0.1.27
 
 ### Patch Changes

package/capabilities/config.json

@@ -59,5 +59,6 @@
     { "id": "config.env-required", "half": "runtime", "expect": "pass", "cost_hint_usd": 0 },
     { "id": "config.brand-file", "half": "runtime", "expect": "pass", "cost_hint_usd": 0, "note": "The app's brand.json passes defineBrand and a bad one is refused with every bad field named" },
     { "id": "config.dev-vars-check", "half": "runtime", "expect": "pass", "cost_hint_usd": 0, "note": "Manual: run npx workbench-config check in the project" }
-  ]
+  ],
+  "no_offer": "Plumbing: WORKBENCH_ENV and typed variables. The template sets them; there is nothing for a client to choose."
 }

package/capabilities/email-sending.json

@@ -34,5 +34,6 @@
     { "id": "email-sending.status", "half": "drill", "expect": "pass", "cost_hint_usd": 0 },
     { "id": "email-sending.sender-add", "half": "drill", "expect": "pass", "cost_hint_usd": 0, "note": "Then a runtime send from the new address (email.send.transactional)" },
     { "id": "email-sending.out-of-scope", "half": "drill", "expect": "refused_as_expected", "refusal": "out_of_scope", "cost_hint_usd": 0, "note": "Another project's namespace" }
-  ]
+  ],
+  "no_offer": "Plumbing: sender domain onboarding is done through Control by the owner. The client's sender address is asked by the email component."
 }

package/capabilities/gateway.json

@@ -79,5 +79,6 @@
     { "id": "gateway.revoked-key", "half": "runtime", "expect": "refused_as_expected", "refusal": "unauthorised", "cost_hint_usd": 0, "note": "Stops within 60 seconds of revocation" },
     { "id": "gateway.budget-enforced", "half": "runtime", "expect": "refused_as_expected", "refusal": "budget_exceeded", "cost_hint_usd": 0, "note": "Uses the development key's US$0 enforce budget, so it is refused before any spend (docs/phase-4-plan.md §3 Q10)" },
     { "id": "gateway.no-vendor-keys.scan", "half": "runtime", "expect": "pass", "cost_hint_usd": 0, "note": "Manual: grep of the repo and cf_worker_secret_list show only WORKBENCH_GATEWAY_* secrets" }
-  ]
+  ],
+  "no_offer": "Plumbing: keys, scopes, headers and budgets shared by every Gateway endpoint. Budgets are set through Control, not by the client's answers."
 }

package/capabilities/schema.json

@@ -401,6 +401,286 @@
         ],
         "additionalProperties": false
       }
+    },
+    "offer": {
+      "type": "object",
+      "properties": {
+        "pattern": {
+          "type": "string",
+          "enum": [
+            "settings",
+            "drafts",
+            "feature_or_content",
+            "project",
+            "switch_on"
+          ]
+        },
+        "when": {
+          "type": "string",
+          "minLength": 1
+        },
+        "say": {
+          "type": "string",
+          "minLength": 1
+        },
+        "answers_file": {
+          "type": "string",
+          "pattern": "^workbench\\/[a-z0-9<>/._-]+\\.json$"
+        },
+        "per": {
+          "type": "string",
+          "minLength": 1
+        },
+        "generator": {
+          "type": "string",
+          "minLength": 1
+        },
+        "questions": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9.-]*$"
+              },
+              "sets": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  {
+                    "minItems": 1,
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                ]
+              },
+              "ask": {
+                "type": "string",
+                "minLength": 1
+              },
+              "style": {
+                "type": "string",
+                "enum": [
+                  "cards",
+                  "table"
+                ]
+              },
+              "answers": {
+                "minItems": 2,
+                "maxItems": 4,
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "label": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 40
+                    },
+                    "value": {
+                      "type": [
+                        "string",
+                        "number",
+                        "boolean",
+                        "null"
+                      ]
+                    },
+                    "means": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  },
+                  "required": [
+                    "label",
+                    "value"
+                  ],
+                  "additionalProperties": false
+                }
+              },
+              "other": {
+                "type": "object",
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "enum": [
+                      "text",
+                      "whole",
+                      "money",
+                      "date",
+                      "list"
+                    ]
+                  },
+                  "min": {
+                    "type": [
+                      "number",
+                      "string"
+                    ]
+                  },
+                  "max": {
+                    "type": [
+                      "number",
+                      "string"
+                    ]
+                  },
+                  "description": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "required": [
+                  "kind"
+                ],
+                "additionalProperties": false
+              },
+              "for": {
+                "minItems": 1,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "must_ask": {
+                "type": "boolean"
+              },
+              "when": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "pattern": "^[a-z0-9][a-z0-9.-]*$"
+                  },
+                  "is": {
+                    "minItems": 1,
+                    "type": "array",
+                    "items": {
+                      "type": [
+                        "string",
+                        "number",
+                        "boolean",
+                        "null"
+                      ]
+                    }
+                  }
+                },
+                "required": [
+                  "id",
+                  "is"
+                ],
+                "additionalProperties": false
+              },
+              "note": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "id",
+              "sets",
+              "ask",
+              "style"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "not_asked": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "sets": {
+                "type": "string",
+                "minLength": 1
+              },
+              "why": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "sets",
+              "why"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "drafts": {
+          "type": "object",
+          "properties": {
+            "of": {
+              "type": "string",
+              "minLength": 1
+            },
+            "surface": {
+              "type": "string",
+              "enum": [
+                "ai",
+                "images",
+                "image-search"
+              ]
+            },
+            "alias": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9-]*$"
+            },
+            "count": {
+              "type": "integer",
+              "minimum": 2,
+              "maximum": 4
+            },
+            "max_rounds": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 5
+            },
+            "job": {
+              "type": "string",
+              "pattern": "^[a-z0-9._-]{1,64}$"
+            },
+            "command": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "required": [
+            "of",
+            "surface",
+            "count",
+            "max_rounds",
+            "job",
+            "command"
+          ],
+          "additionalProperties": false
+        },
+        "needs": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          }
+        }
+      },
+      "required": [
+        "pattern",
+        "when",
+        "say",
+        "answers_file",
+        "questions"
+      ],
+      "additionalProperties": false
+    },
+    "no_offer": {
+      "type": "string",
+      "minLength": 1
     }
   },
   "required": [

package/dist/capabilities.gen.d.ts

@@ -1,4 +1,4 @@
-export declare const MANIFEST_VERSION: "c83a7c612319";
+export declare const MANIFEST_VERSION: "4538a59cfe87";
 export declare const capabilities: {
     readonly ai: {
         readonly $schema: "./schema.json";
@@ -355,6 +355,7 @@ export declare const capabilities: {
             readonly cost_hint_usd: 0;
             readonly note: "Manual: run npx workbench-config check in the project";
         }];
+        readonly no_offer: "Plumbing: WORKBENCH_ENV and typed variables. The template sets them; there is nothing for a client to choose.";
     };
     readonly country: {
         readonly $schema: "./schema.json";
@@ -1083,6 +1084,7 @@ export declare const capabilities: {
             readonly cost_hint_usd: 0;
             readonly note: "Another project's namespace";
         }];
+        readonly no_offer: "Plumbing: sender domain onboarding is done through Control by the owner. The client's sender address is asked by the email component.";
     };
     readonly forms: {
         readonly $schema: "./schema.json";
@@ -1380,6 +1382,7 @@ export declare const capabilities: {
             readonly cost_hint_usd: 0;
             readonly note: "Manual: grep of the repo and cf_worker_secret_list show only WORKBENCH_GATEWAY_* secrets";
         }];
+        readonly no_offer: "Plumbing: keys, scopes, headers and budgets shared by every Gateway endpoint. Budgets are set through Control, not by the client's answers.";
     };
     readonly "image-search": {
         readonly $schema: "./schema.json";

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 = "c83a7c612319";
+export const MANIFEST_VERSION = "4538a59cfe87";
 export const capabilities = {
     "ai": {
         "$schema": "./schema.json",
@@ -521,7 +521,8 @@ export const capabilities = {
                 "cost_hint_usd": 0,
                 "note": "Manual: run npx workbench-config check in the project"
             }
-        ]
+        ],
+        "no_offer": "Plumbing: WORKBENCH_ENV and typed variables. The template sets them; there is nothing for a client to choose."
     },
     "country": {
         "$schema": "./schema.json",
@@ -1473,7 +1474,8 @@ export const capabilities = {
                 "cost_hint_usd": 0,
                 "note": "Another project's namespace"
             }
-        ]
+        ],
+        "no_offer": "Plumbing: sender domain onboarding is done through Control by the owner. The client's sender address is asked by the email component."
     },
     "forms": {
         "$schema": "./schema.json",
@@ -1872,7 +1874,8 @@ export const capabilities = {
                 "cost_hint_usd": 0,
                 "note": "Manual: grep of the repo and cf_worker_secret_list show only WORKBENCH_GATEWAY_* secrets"
             }
-        ]
+        ],
+        "no_offer": "Plumbing: keys, scopes, headers and budgets shared by every Gateway endpoint. Budgets are set through Control, not by the client's answers."
     },
     "image-search": {
         "$schema": "./schema.json",

package/dist/capability-schema.d.ts

@@ -87,6 +87,73 @@ export declare const allowedSchemas: {
         }>>;
     }, z.core.$strict>;
 };
+/** How Claude works with the client (docs/capabilities-manifest.md §9.5). */
+export declare const OFFER_PATTERNS: readonly ["settings", "drafts", "feature_or_content", "project", "switch_on"];
+declare const offer: z.ZodObject<{
+    pattern: z.ZodEnum<{
+        drafts: "drafts";
+        feature_or_content: "feature_or_content";
+        project: "project";
+        settings: "settings";
+        switch_on: "switch_on";
+    }>;
+    when: z.ZodString;
+    say: z.ZodString;
+    answers_file: z.ZodString;
+    per: z.ZodOptional<z.ZodString>;
+    generator: z.ZodOptional<z.ZodString>;
+    questions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        sets: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+        ask: z.ZodString;
+        style: z.ZodEnum<{
+            cards: "cards";
+            table: "table";
+        }>;
+        answers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+            means: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        other: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                date: "date";
+                list: "list";
+                money: "money";
+                text: "text";
+                whole: "whole";
+            }>;
+            min: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+            max: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        for: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        must_ask: z.ZodOptional<z.ZodBoolean>;
+        when: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            is: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+        }, z.core.$strict>>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    not_asked: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        sets: z.ZodString;
+        why: z.ZodString;
+    }, z.core.$strict>>>;
+    drafts: z.ZodOptional<z.ZodObject<{
+        of: z.ZodString;
+        surface: z.ZodEnum<{
+            ai: "ai";
+            "image-search": "image-search";
+            images: "images";
+        }>;
+        alias: z.ZodOptional<z.ZodString>;
+        count: z.ZodNumber;
+        max_rounds: z.ZodNumber;
+        job: z.ZodString;
+        command: z.ZodString;
+    }, z.core.$strict>>;
+    needs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
 /** One file in `capabilities/`. Parsing checks shape only; cross-references are checked by `checkManifests`. */
 export declare const capabilitySchema: z.ZodObject<{
     $schema: z.ZodLiteral<"./schema.json">;
@@ -221,8 +288,81 @@ export declare const capabilitySchema: z.ZodObject<{
         two_step: z.ZodOptional<z.ZodBoolean>;
         note: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
+    offer: z.ZodOptional<z.ZodObject<{
+        pattern: z.ZodEnum<{
+            drafts: "drafts";
+            feature_or_content: "feature_or_content";
+            project: "project";
+            settings: "settings";
+            switch_on: "switch_on";
+        }>;
+        when: z.ZodString;
+        say: z.ZodString;
+        answers_file: z.ZodString;
+        per: z.ZodOptional<z.ZodString>;
+        generator: z.ZodOptional<z.ZodString>;
+        questions: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            sets: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+            ask: z.ZodString;
+            style: z.ZodEnum<{
+                cards: "cards";
+                table: "table";
+            }>;
+            answers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+                means: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+            other: z.ZodOptional<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    date: "date";
+                    list: "list";
+                    money: "money";
+                    text: "text";
+                    whole: "whole";
+                }>;
+                min: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                max: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            for: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            must_ask: z.ZodOptional<z.ZodBoolean>;
+            when: z.ZodOptional<z.ZodObject<{
+                id: z.ZodString;
+                is: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+            }, z.core.$strict>>;
+            note: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        not_asked: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            sets: z.ZodString;
+            why: z.ZodString;
+        }, z.core.$strict>>>;
+        drafts: z.ZodOptional<z.ZodObject<{
+            of: z.ZodString;
+            surface: z.ZodEnum<{
+                ai: "ai";
+                "image-search": "image-search";
+                images: "images";
+            }>;
+            alias: z.ZodOptional<z.ZodString>;
+            count: z.ZodNumber;
+            max_rounds: z.ZodNumber;
+            job: z.ZodString;
+            command: z.ZodString;
+        }, z.core.$strict>>;
+        needs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    no_offer: z.ZodOptional<z.ZodString>;
 }, 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 ["ai", "analytics", "country", "database", "email", "email-inbound", "forms", "image-search", "images", "pdf", "strings", "ui"];
 export interface ManifestProblem {
     file: string;
     check: "schema" | "proof" | "ids" | "surfaces" | "errors" | "generated";
@@ -236,3 +376,4 @@ export declare function checkManifests(files: Record<string, unknown>): {
     manifests: Capability[];
     problems: ManifestProblem[];
 };
+export {};

package/dist/capability-schema.js

@@ -136,6 +136,60 @@ export const allowedSchemas = {
         environments: z.array(envName).min(1),
     }),
 };
+// Client questions (docs/capabilities-manifest.md §9): what Claude Code asks
+// the client when it builds with this component. A project skill is
+// generated from it (`workbench-config skills`).
+const answerValue = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+const otherRule = z.strictObject({
+    kind: z.enum(["text", "whole", "money", "date", "list"]),
+    min: z.union([z.number(), z.string()]).optional(),
+    max: z.union([z.number(), z.string()]).optional(),
+    description: z.string().min(1).optional(),
+});
+const question = z.strictObject({
+    id,
+    sets: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]),
+    ask: z.string().min(1),
+    /** `cards`: two to four answers, recommended first. `table`: a table of proposed values to accept or correct. */
+    style: z.enum(["cards", "table"]),
+    answers: z
+        .array(z.strictObject({ label: z.string().min(1).max(40), value: answerValue, means: z.string().min(1).optional() }))
+        .min(2)
+        .max(4)
+        .optional(),
+    /** Absent: "Other" isn't allowed. Present: what a typed answer must satisfy. */
+    other: otherRule.optional(),
+    for: z.array(z.string().min(1)).min(1).optional(),
+    must_ask: z.boolean().optional(),
+    /** Ask only when an earlier question's answer is one of `is` (the branch, e.g. feature or one-off). */
+    when: z.strictObject({ id, is: z.array(answerValue).min(1) }).optional(),
+    note: z.string().min(1).optional(),
+});
+/** How Claude works with the client (docs/capabilities-manifest.md §9.5). */
+export const OFFER_PATTERNS = ["settings", "drafts", "feature_or_content", "project", "switch_on"];
+const drafts = z.strictObject({
+    /** What is drafted, in plain words: "invoice layouts", "a hero image". */
+    of: z.string().min(1),
+    surface: z.enum(["ai", "images", "image-search"]),
+    alias: z.string().regex(/^[a-z][a-z0-9-]*$/).optional(),
+    count: z.number().int().min(2).max(4),
+    max_rounds: z.number().int().min(1).max(5),
+    job: z.string().regex(/^[a-z0-9._-]{1,64}$/),
+    command: z.string().min(1),
+});
+const offer = z.strictObject({
+    pattern: z.enum(OFFER_PATTERNS),
+    when: z.string().min(1),
+    say: z.string().min(1),
+    answers_file: z.string().regex(/^workbench\/[a-z0-9<>/._-]+\.json$/, "a JSON file under workbench/"),
+    per: z.string().min(1).optional(),
+    generator: z.string().min(1).optional(),
+    questions: z.array(question).min(1),
+    not_asked: z.array(z.strictObject({ sets: z.string().min(1), why: z.string().min(1) })).min(1).optional(),
+    drafts: drafts.optional(),
+    /** 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(),
+});
 const baseShape = {
     $schema: z.literal("./schema.json"),
     format: z.literal(1),
@@ -158,6 +212,9 @@ const baseShape = {
     rules: z.array(rule).min(1),
     examples: z.array(example).min(1).optional(),
     probes: z.array(probe).min(1),
+    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(),
 };
 /** One file in `capabilities/`. Parsing checks shape only; cross-references are checked by `checkManifests`. */
 export const capabilitySchema = z.strictObject(baseShape).superRefine((m, ctx) => {
@@ -175,6 +232,51 @@ 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 = ["ai", "analytics", "country", "database", "email", "email-inbound", "forms", "image-search", "images", "pdf", "strings", "ui"];
+function checkOffer(file, component, o, seen) {
+    const problems = [];
+    const named = new Map();
+    const name = (option, by) => {
+        const prior = named.get(option);
+        if (prior)
+            problems.push({ file, check: "ids", message: `offer: ${option} is set by ${prior} and ${by}` });
+        else
+            named.set(option, by);
+    };
+    const asked = new Set();
+    if (o.pattern === "drafts" && !o.drafts)
+        problems.push({ file, check: "schema", message: "offer: the drafts pattern needs drafts" });
+    for (const q of o.questions) {
+        if (q.when && !asked.has(q.when.id))
+            problems.push({ file, check: "ids", message: `question ${q.id} depends on ${q.when.id}, which isn't an earlier question` });
+        asked.add(q.id);
+        seen("question", q.id);
+        if (!q.id.startsWith(`${component}.`))
+            problems.push({ file, check: "ids", message: `question ${q.id} must start with ${component}.` });
+        if (q.style === "cards" && !q.answers)
+            problems.push({ file, check: "schema", message: `question ${q.id} is cards but has no answers` });
+        if (q.style === "table" && q.answers)
+            problems.push({ file, check: "schema", message: `question ${q.id} is a table, so it lists no answers` });
+        const labels = new Set();
+        for (const a of q.answers ?? []) {
+            if (labels.has(a.label))
+                problems.push({ file, check: "ids", message: `question ${q.id} has the answer ${a.label} twice` });
+            labels.add(a.label);
+            if (/^other$/i.test(a.label))
+                problems.push({ file, check: "schema", message: `question ${q.id}: "Other" is added by Claude Code; use \`other\` instead` });
+        }
+        for (const option of typeof q.sets === "string" ? [q.sets] : q.sets)
+            name(option, `question ${q.id}`);
+    }
+    for (const n of o.not_asked ?? [])
+        name(n.sets, "not_asked");
+    return problems;
+}
 /**
  * The checks that need only the manifests themselves (§5: schema, proof, ids).
  * `files` maps a file name (e.g. `ai.json`) to its parsed JSON.
@@ -244,6 +346,16 @@ export function checkManifests(files) {
             if (a.gate === "two_step_when" && !a.when)
                 problems.push({ file, check: "schema", message: `action ${a.tool} is two_step_when but has no when` });
         }
+        if (m.offer)
+            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) {
+            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` });
     }
     return { manifests, problems };
 }

package/dist/cli.js

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
 // `npx workbench-config check [dir]`: compares the variable names in
 // <dir>/.dev.vars with <dir>/.dev.vars.example. Prints names only.
-import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+// `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).
+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";
-function main(argv) {
-    const [command, dir = "."] = argv;
-    if (command !== "check") {
-        console.error("Usage: workbench-config check [dir]");
-        return 2;
-    }
+import { planSkills } from "./skills-plan.js";
+const USAGE = "Usage: workbench-config check [dir]\n       workbench-config skills [--check] [dir]";
+function checkDevVars(dir) {
     const examplePath = join(dir, ".dev.vars.example");
     const devVarsPath = join(dir, ".dev.vars");
     if (!existsSync(examplePath)) {
@@ -31,4 +32,50 @@ function main(argv) {
         console.error(`In .dev.vars but not in .dev.vars.example: ${result.extra.join(", ")}`);
     return 1;
 }
+function skills(args) {
+    const check = args.includes("--check");
+    const dir = args.find((a) => a !== "--check") ?? ".";
+    const pkg = join(dirname(fileURLToPath(import.meta.url)), "..");
+    const version = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8")).version;
+    const { files, stale, problems } = planSkills(join(pkg, "capabilities"), dir);
+    if (problems.length) {
+        for (const p of problems)
+            console.error(p);
+        return 1;
+    }
+    if (check) {
+        const wrong = Object.entries(files).filter(([path, text]) => !existsSync(join(dir, path)) || readFileSync(join(dir, path), "utf8") !== text).map(([path]) => path);
+        for (const path of wrong)
+            console.error(`${path} is missing or differs from workbench-config ${version}.`);
+        for (const path of stale)
+            console.error(`${path} is no longer generated by workbench-config ${version}.`);
+        if (wrong.length || stale.length) {
+            console.error("Run `npx workbench-config skills` and commit the result.");
+            return 1;
+        }
+        console.log(`Skills match workbench-config ${version} (${Object.keys(files).length}).`);
+        return 0;
+    }
+    for (const [path, text] of Object.entries(files)) {
+        mkdirSync(dirname(join(dir, path)), { recursive: true });
+        writeFileSync(join(dir, path), text);
+        console.log(`wrote ${path}`);
+    }
+    for (const path of stale) {
+        rmSync(join(dir, path));
+        if (readdirSync(dirname(join(dir, path))).length === 0)
+            rmSync(dirname(join(dir, path)), { recursive: true });
+        console.log(`removed ${path}`);
+    }
+    return 0;
+}
+function main(argv) {
+    const [command, ...rest] = argv;
+    if (command === "check")
+        return checkDevVars(rest[0] ?? ".");
+    if (command === "skills")
+        return skills(rest);
+    console.error(USAGE);
+    return 2;
+}
 process.exitCode = main(process.argv.slice(2));

package/dist/index.d.ts

@@ -2,7 +2,8 @@ export { WORKBENCH_ENVS, DEFAULT_GATEWAY_URL, workbenchEnv, type WorkbenchEnv }
 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, } from "./capability-schema.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 { 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

@@ -2,7 +2,8 @@ export { WORKBENCH_ENVS, DEFAULT_GATEWAY_URL, 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, } from "./capability-schema.js";
+export { capabilitySchema, checkManifests, allowedSchemas, COMPONENTS, OFFER_PATTERNS, OFFER_PENDING, } from "./capability-schema.js";
+export { renderSkill, renderSkills, skillName, SKILLS_DIR } from "./skills.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

@@ -0,0 +1,7 @@
+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[];
+    problems: string[];
+};

package/dist/skills-plan.js

@@ -0,0 +1,26 @@
+// Node only: reads a manifests directory and a project, for
+// `workbench-config skills` (cli.ts). Kept out of index.ts, which runs in Workers.
+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";
+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) {
+    const json = {};
+    for (const f of readdirSync(manifestDir).filter((f) => f.endsWith(".json") && f !== "schema.json")) {
+        json[f] = JSON.parse(readFileSync(join(manifestDir, f), "utf8"));
+    }
+    const { manifests, problems } = checkManifests(json);
+    const files = renderSkills(manifests);
+    const stale = [];
+    const skillsDir = join(projectDir, SKILLS_DIR);
+    if (existsSync(skillsDir)) {
+        for (const d of readdirSync(skillsDir)) {
+            const path = `${SKILLS_DIR}/${d}/SKILL.md`;
+            if (d.startsWith("workbench-") && existsSync(join(projectDir, path)) && !(path in files) && readFileSync(join(projectDir, path), "utf8").includes(GENERATED_MARK))
+                stale.push(path);
+        }
+    }
+    return { files, stale, problems: problems.map((p) => `${p.file}: [${p.check}] ${p.message}`) };
+}

package/dist/skills.d.ts

@@ -0,0 +1,7 @@
+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>;

package/dist/skills.js

@@ -0,0 +1,125 @@
+// 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.
+export const SKILLS_DIR = ".claude/skills";
+export const skillName = (component) => `workbench-${component}`;
+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(", ");
+function otherLine(q) {
+    if (!q.other)
+        return "Other: not allowed. Only the answers above are accepted.";
+    const { kind, min, max, description } = q.other;
+    const range = min !== undefined && max !== undefined ? ` from ${min} to ${max}` : min !== undefined ? ` of at least ${min}` : max !== undefined ? ` of at most ${max}` : "";
+    const what = { text: "text", whole: "a whole number", money: "an amount", date: "a date (YYYY-MM-DD)", list: "a list, one item per line" }[kind];
+    const length = kind === "text" && range ? ` (length in characters)` : "";
+    return `Other: allowed. The client must type ${what}${range}${length}.${description ? ` ${description}` : ""} Refuse anything else and ask again.`;
+}
+function questionBlock(q, n) {
+    const lines = [`### ${n}. ${q.ask}`, "", `Id \`${q.id}\`. Sets ${sets(q)}.`];
+    if (q.for)
+        lines.push(`Only for: ${q.for.map((f) => `\`${f}\``).join(", ")}.`);
+    if (q.when)
+        lines.push(`Ask only when \`${q.when.id}\` is ${q.when.is.map(show).join(" or ")}.`);
+    if (q.must_ask)
+        lines.push("**Must ask:** there is no safe default, so always ask it, even when the client accepts every recommendation.");
+    lines.push("");
+    if (q.style === "table") {
+        lines.push("Ask as a table: propose a value for each row, show the table, then ask one question with the answers \"Accept all (Recommended)\", \"Change some\" and \"Add or remove\".");
+    }
+    else {
+        lines.push("| Answer | Value | Means |", "| --- | --- | --- |");
+        (q.answers ?? []).forEach((a, i) => lines.push(`| ${cell(a.label)}${i === 0 ? " (Recommended)" : ""} | ${show(a.value)} | ${cell(a.means ?? "")} |`));
+    }
+    lines.push("", otherLine(q));
+    if (q.note)
+        lines.push("", q.note);
+    return lines.join("\n");
+}
+const PATTERN_STEPS = {
+    settings: [
+        "Propose everything at once: a table of every setting with its recommended value. Then ask one question: \"Accept all (Recommended)\", \"Change some\" or \"Add or remove\".",
+        "The client edits the list in plain words (\"delete this\", \"add a dropdown with these values, required\"). Update the answers file and show the table again until they accept it.",
+    ],
+    drafts: [
+        "Ask what the thing is first, then offer examples to pick from (see Drafts below). Show them, let the client pick one or ask for another round, and keep only the one picked.",
+    ],
+    feature_or_content: [
+        "Ask the routing question first: is this a feature visitors use on the site, or something made once for the site? Then ask only the questions for that route.",
+        "A feature for visitors spends money every time someone uses it: always ask who may use it and its monthly cap.",
+    ],
+    project: [
+        "These are project-wide answers, asked once. If the answers file already exists, use it and don't ask again; offer to change it only if the client asks.",
+    ],
+    switch_on: [
+        "The template already has this. Confirm the client wants it, ask the few questions below, and name any step the owner takes in Workbench Control.",
+    ],
+};
+function draftsBlock(d) {
+    return [
+        "## Drafts",
+        "",
+        `Offer ${d.count} examples of ${d.of} to pick from, at most ${d.max_rounds} round${d.max_rounds === 1 ? "" : "s"}. Make them with \`${d.command}\`: it calls the Workbench Gateway (${d.surface}${d.alias ? `, \`${d.alias}\`` : ""}, job \`${d.job}\`) with the project's development key from \`.dev.vars\`, spends from the development budget, and prints what each round cost. Tell the client the cost it prints.`,
+        "",
+        "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) {
+    const o = m.offer;
+    if (!o)
+        return undefined;
+    const description = `${o.when} Offers Workbench ${m.title} and asks the client for its settings.`.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. -->`,
+        "",
+        `# ${m.title}`,
+        "",
+        m.summary,
+        "",
+        "## 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.`,
+        "",
+        "## 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}` : ""}: 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 an out-of-range answer. 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}`));
+    }
+    return `${out.join("\n")}\n`;
+}
+/** Every skill the manifests produce, keyed by its path in a project. */
+export function renderSkills(manifests) {
+    const files = {};
+    for (const m of manifests) {
+        const text = renderSkill(m);
+        if (text)
+            files[`${SKILLS_DIR}/${skillName(m.component)}/SKILL.md`] = text;
+    }
+    return files;
+}

package/package.json

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