@mccaskie-labs/workbench-config 0.1.26 → 0.1.28

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @mccaskie-labs/workbench-config
 
+## 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
+
+- The forms manifest (`capabilities/forms.json`): five rules for `workbench-forms` (the endpoint decides, one verdict on the page and at the endpoint, codes turned into words by the strings catalogue, bounds from the limits register, no members on a form) and two no-cost probes, `forms.validate` and `forms.browser`. `forms` joins the component list.
+
 ## 0.1.26
 
 ### Patch Changes

package/capabilities/forms.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "./schema.json",
+  "format": 1,
+  "component": "forms",
+  "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",
+  "surfaces": {
+    "package": [
+      "defineForm",
+      "text",
+      "longText",
+      "email",
+      "phone",
+      "money",
+      "whole",
+      "date",
+      "choice",
+      "validate",
+      "readForm",
+      "embedConfig",
+      "inputAttributes",
+      "messageKeys",
+      "tidyLine",
+      "tidyText",
+      "CODES",
+      "FormsSetupError"
+    ]
+  },
+  "rules": [
+    {
+      "id": "forms.endpoint-decides",
+      "kind": "must",
+      "text": "Validate every form at the endpoint with validate() and store only result.values; the page's copy of the validator (FORMS_SCRIPT) only helps the person, it never decides.",
+      "enforced_by": "review",
+      "probe": "forms.validate"
+    },
+    {
+      "id": "forms.same-verdict",
+      "kind": "must",
+      "text": "Put the form on the page with embedConfig and FORMS_SCRIPT, never a second set of rules, so the page and the endpoint reach the same verdict.",
+      "enforced_by": "review",
+      "probe": "forms.browser"
+    },
+    {
+      "id": "forms.codes-not-sentences",
+      "kind": "must",
+      "text": "Turn problem codes into words through the strings catalogue (messageKeys: validation.<form>.<field>.<code>, then validation.<code>), never words written in code.",
+      "enforced_by": "review",
+      "probe": "forms.validate"
+    },
+    {
+      "id": "forms.limits-register",
+      "kind": "must",
+      "text": "Take every length, amount and date bound from the app's limits register (defineLimits, boundsFor), and keep it matched to the database with workbench-supabase check:limits.",
+      "enforced_by": "types",
+      "probe": "forms.validate"
+    },
+    {
+      "id": "forms.no-members-on-a-form",
+      "kind": "must_not",
+      "text": "List a choice field's members on the form: the vocabulary owns them, and the app passes them in context.choices.",
+      "enforced_by": "types",
+      "probe": "forms.validate"
+    }
+  ],
+  "examples": [
+    {
+      "id": "forms.example.endpoint",
+      "title": "Check a posted form at the endpoint",
+      "lang": "ts",
+      "probe": "forms.validate",
+      "code": "import { defineForm, email, money, readForm, text, validate } from '@mccaskie-labs/workbench-forms'\nimport { boundsFor } from '@mccaskie-labs/workbench-forms/limits'\nimport { COUNTRY_PACKS } from '@mccaskie-labs/workbench-country'\n\nconst lead = defineForm('lead', { name: text({ limit: 'lead.name', required: true }), email: email({ required: true }), budget: money({ limit: 'lead.budget' }) })\nconst result = validate(lead, readForm(lead, await request.formData()), { bounds: boundsFor(LIMITS, lead), country: COUNTRY_PACKS.PH! })\nif (!result.ok) return show(result.problems, result.shown)\nawait db.from('leads').insert(result.values)"
+    }
+  ],
+  "probes": [
+    {
+      "id": "forms.validate",
+      "half": "runtime",
+      "expect": "pass",
+      "smoke": true,
+      "cost_hint_usd": 0,
+      "note": "In the Worker itself: validates a fixed form (text, email, phone, money, date, choice) for PH with one good and one bad input, and compares the stored values (E.164 phone, decimal-string amount, ISO date) and the problem codes with the expected ones"
+    },
+    {
+      "id": "forms.browser",
+      "half": "runtime",
+      "expect": "pass",
+      "cost_hint_usd": 0,
+      "note": "The probe page loads FORMS_SCRIPT and the form's embedConfig block, runs the same inputs in the browser and checks the verdict matches the Worker's; no Gateway call"
+    }
+  ]
+}

package/capabilities/schema.json

@@ -33,7 +33,8 @@
         "kv",
         "github",
         "strings",
-        "ui"
+        "ui",
+        "forms"
       ]
     },
     "title": {
@@ -400,6 +401,189 @@
         ],
         "additionalProperties": false
       }
+    },
+    "offer": {
+      "type": "object",
+      "properties": {
+        "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"
+              },
+              "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
+          }
+        }
+      },
+      "required": [
+        "when",
+        "say",
+        "answers_file",
+        "questions"
+      ],
+      "additionalProperties": false
     }
   },
   "required": [

package/dist/capabilities.gen.d.ts

@@ -1,4 +1,4 @@
-export declare const MANIFEST_VERSION: "7d046814165b";
+export declare const MANIFEST_VERSION: "c83a7c612319";
 export declare const capabilities: {
     readonly ai: {
         readonly $schema: "./schema.json";
@@ -1084,6 +1084,69 @@ export declare const capabilities: {
             readonly note: "Another project's namespace";
         }];
     };
+    readonly forms: {
+        readonly $schema: "./schema.json";
+        readonly format: 1;
+        readonly component: "forms";
+        readonly title: "Form validation";
+        readonly 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.";
+        readonly status: "built";
+        readonly surfaces: {
+            readonly package: readonly ["defineForm", "text", "longText", "email", "phone", "money", "whole", "date", "choice", "validate", "readForm", "embedConfig", "inputAttributes", "messageKeys", "tidyLine", "tidyText", "CODES", "FormsSetupError"];
+        };
+        readonly rules: readonly [{
+            readonly id: "forms.endpoint-decides";
+            readonly kind: "must";
+            readonly text: "Validate every form at the endpoint with validate() and store only result.values; the page's copy of the validator (FORMS_SCRIPT) only helps the person, it never decides.";
+            readonly enforced_by: "review";
+            readonly probe: "forms.validate";
+        }, {
+            readonly id: "forms.same-verdict";
+            readonly kind: "must";
+            readonly text: "Put the form on the page with embedConfig and FORMS_SCRIPT, never a second set of rules, so the page and the endpoint reach the same verdict.";
+            readonly enforced_by: "review";
+            readonly probe: "forms.browser";
+        }, {
+            readonly id: "forms.codes-not-sentences";
+            readonly kind: "must";
+            readonly text: "Turn problem codes into words through the strings catalogue (messageKeys: validation.<form>.<field>.<code>, then validation.<code>), never words written in code.";
+            readonly enforced_by: "review";
+            readonly probe: "forms.validate";
+        }, {
+            readonly id: "forms.limits-register";
+            readonly kind: "must";
+            readonly text: "Take every length, amount and date bound from the app's limits register (defineLimits, boundsFor), and keep it matched to the database with workbench-supabase check:limits.";
+            readonly enforced_by: "types";
+            readonly probe: "forms.validate";
+        }, {
+            readonly id: "forms.no-members-on-a-form";
+            readonly kind: "must_not";
+            readonly text: "List a choice field's members on the form: the vocabulary owns them, and the app passes them in context.choices.";
+            readonly enforced_by: "types";
+            readonly probe: "forms.validate";
+        }];
+        readonly examples: readonly [{
+            readonly id: "forms.example.endpoint";
+            readonly title: "Check a posted form at the endpoint";
+            readonly lang: "ts";
+            readonly code: "import { defineForm, email, money, readForm, text, validate } from '@mccaskie-labs/workbench-forms'\nimport { boundsFor } from '@mccaskie-labs/workbench-forms/limits'\nimport { COUNTRY_PACKS } from '@mccaskie-labs/workbench-country'\n\nconst lead = defineForm('lead', { name: text({ limit: 'lead.name', required: true }), email: email({ required: true }), budget: money({ limit: 'lead.budget' }) })\nconst result = validate(lead, readForm(lead, await request.formData()), { bounds: boundsFor(LIMITS, lead), country: COUNTRY_PACKS.PH! })\nif (!result.ok) return show(result.problems, result.shown)\nawait db.from('leads').insert(result.values)";
+            readonly probe: "forms.validate";
+        }];
+        readonly probes: readonly [{
+            readonly id: "forms.validate";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly smoke: true;
+            readonly cost_hint_usd: 0;
+            readonly note: "In the Worker itself: validates a fixed form (text, email, phone, money, date, choice) for PH with one good and one bad input, and compares the stored values (E.164 phone, decimal-string amount, ISO date) and the problem codes with the expected ones";
+        }, {
+            readonly id: "forms.browser";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0;
+            readonly note: "The probe page loads FORMS_SCRIPT and the form's embedConfig block, runs the same inputs in the browser and checks the verdict matches the Worker's; no Gateway call";
+        }];
+    };
     readonly gateway: {
         readonly $schema: "./schema.json";
         readonly format: 1;

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 = "7d046814165b";
+export const MANIFEST_VERSION = "c83a7c612319";
 export const capabilities = {
     "ai": {
         "$schema": "./schema.json",
@@ -1475,6 +1475,99 @@ export const capabilities = {
             }
         ]
     },
+    "forms": {
+        "$schema": "./schema.json",
+        "format": 1,
+        "component": "forms",
+        "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",
+        "surfaces": {
+            "package": [
+                "defineForm",
+                "text",
+                "longText",
+                "email",
+                "phone",
+                "money",
+                "whole",
+                "date",
+                "choice",
+                "validate",
+                "readForm",
+                "embedConfig",
+                "inputAttributes",
+                "messageKeys",
+                "tidyLine",
+                "tidyText",
+                "CODES",
+                "FormsSetupError"
+            ]
+        },
+        "rules": [
+            {
+                "id": "forms.endpoint-decides",
+                "kind": "must",
+                "text": "Validate every form at the endpoint with validate() and store only result.values; the page's copy of the validator (FORMS_SCRIPT) only helps the person, it never decides.",
+                "enforced_by": "review",
+                "probe": "forms.validate"
+            },
+            {
+                "id": "forms.same-verdict",
+                "kind": "must",
+                "text": "Put the form on the page with embedConfig and FORMS_SCRIPT, never a second set of rules, so the page and the endpoint reach the same verdict.",
+                "enforced_by": "review",
+                "probe": "forms.browser"
+            },
+            {
+                "id": "forms.codes-not-sentences",
+                "kind": "must",
+                "text": "Turn problem codes into words through the strings catalogue (messageKeys: validation.<form>.<field>.<code>, then validation.<code>), never words written in code.",
+                "enforced_by": "review",
+                "probe": "forms.validate"
+            },
+            {
+                "id": "forms.limits-register",
+                "kind": "must",
+                "text": "Take every length, amount and date bound from the app's limits register (defineLimits, boundsFor), and keep it matched to the database with workbench-supabase check:limits.",
+                "enforced_by": "types",
+                "probe": "forms.validate"
+            },
+            {
+                "id": "forms.no-members-on-a-form",
+                "kind": "must_not",
+                "text": "List a choice field's members on the form: the vocabulary owns them, and the app passes them in context.choices.",
+                "enforced_by": "types",
+                "probe": "forms.validate"
+            }
+        ],
+        "examples": [
+            {
+                "id": "forms.example.endpoint",
+                "title": "Check a posted form at the endpoint",
+                "lang": "ts",
+                "code": "import { defineForm, email, money, readForm, text, validate } from '@mccaskie-labs/workbench-forms'\nimport { boundsFor } from '@mccaskie-labs/workbench-forms/limits'\nimport { COUNTRY_PACKS } from '@mccaskie-labs/workbench-country'\n\nconst lead = defineForm('lead', { name: text({ limit: 'lead.name', required: true }), email: email({ required: true }), budget: money({ limit: 'lead.budget' }) })\nconst result = validate(lead, readForm(lead, await request.formData()), { bounds: boundsFor(LIMITS, lead), country: COUNTRY_PACKS.PH! })\nif (!result.ok) return show(result.problems, result.shown)\nawait db.from('leads').insert(result.values)",
+                "probe": "forms.validate"
+            }
+        ],
+        "probes": [
+            {
+                "id": "forms.validate",
+                "half": "runtime",
+                "expect": "pass",
+                "smoke": true,
+                "cost_hint_usd": 0,
+                "note": "In the Worker itself: validates a fixed form (text, email, phone, money, date, choice) for PH with one good and one bad input, and compares the stored values (E.164 phone, decimal-string amount, ISO date) and the problem codes with the expected ones"
+            },
+            {
+                "id": "forms.browser",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0,
+                "note": "The probe page loads FORMS_SCRIPT and the form's embedConfig block, runs the same inputs in the browser and checks the verdict matches the Worker's; no Gateway call"
+            }
+        ]
+    },
     "gateway": {
         "$schema": "./schema.json",
         "format": 1,

package/dist/capability-schema.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-export declare const COMPONENTS: readonly ["gateway", "ai", "images", "image-search", "config", "email", "email-inbound", "email-sending", "database", "workers", "domains", "dns", "analytics", "country", "pdf", "access", "r2", "kv", "github", "strings", "ui"];
+export declare const COMPONENTS: readonly ["gateway", "ai", "images", "image-search", "config", "email", "email-inbound", "email-sending", "database", "workers", "domains", "dns", "analytics", "country", "pdf", "access", "r2", "kv", "github", "strings", "ui", "forms"];
 export type Component = (typeof COMPONENTS)[number];
 export declare const allowedSchemas: {
     gateway: z.ZodObject<{
@@ -87,6 +87,46 @@ export declare const allowedSchemas: {
         }>>;
     }, z.core.$strict>;
 };
+declare const offer: z.ZodObject<{
+    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>;
+        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>>>;
+}, 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">;
@@ -103,6 +143,7 @@ export declare const capabilitySchema: z.ZodObject<{
         email: "email";
         "email-inbound": "email-inbound";
         "email-sending": "email-sending";
+        forms: "forms";
         gateway: "gateway";
         github: "github";
         "image-search": "image-search";
@@ -220,8 +261,49 @@ 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<{
+        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>;
+            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>>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type Capability = z.infer<typeof capabilitySchema>;
+export type Offer = z.infer<typeof offer>;
 export interface ManifestProblem {
     file: string;
     check: "schema" | "proof" | "ids" | "surfaces" | "errors" | "generated";
@@ -235,3 +317,4 @@ export declare function checkManifests(files: Record<string, unknown>): {
     manifests: Capability[];
     problems: ManifestProblem[];
 };
+export {};

package/dist/capability-schema.js

@@ -24,6 +24,7 @@ export const COMPONENTS = [
     "github",
     "strings",
     "ui",
+    "forms",
 ];
 const id = z.string().regex(/^[a-z0-9][a-z0-9.-]*$/, "lower case, digits, dots and hyphens");
 const code = z.string().regex(/^[a-z][a-z0-9_]*$/, "a snake_case error code");
@@ -135,6 +136,42 @@ 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(),
+    note: z.string().min(1).optional(),
+});
+const offer = z.strictObject({
+    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(),
+});
 const baseShape = {
     $schema: z.literal("./schema.json"),
     format: z.literal(1),
@@ -157,6 +194,7 @@ const baseShape = {
     rules: z.array(rule).min(1),
     examples: z.array(example).min(1).optional(),
     probes: z.array(probe).min(1),
+    offer: offer.optional(),
 };
 /** One file in `capabilities/`. Parsing checks shape only; cross-references are checked by `checkManifests`. */
 export const capabilitySchema = z.strictObject(baseShape).superRefine((m, ctx) => {
@@ -174,6 +212,39 @@ export const capabilitySchema = z.strictObject(baseShape).superRefine((m, ctx) =
         }
     }
 });
+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);
+    };
+    for (const q of o.questions) {
+        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.
@@ -243,6 +314,8 @@ 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));
     }
     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, } 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

@@ -3,6 +3,7 @@ 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 { 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,91 @@
+// 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.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");
+}
+/** 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",
+        "",
+        "- 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.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.26",
+  "version": "0.1.28",
   "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",