@mccaskie-labs/workbench-config 0.1.28 → 0.1.29

package/CHANGELOG.md

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

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

@@ -405,6 +405,16 @@
     "offer": {
       "type": "object",
       "properties": {
+        "pattern": {
+          "type": "string",
+          "enum": [
+            "settings",
+            "drafts",
+            "feature_or_content",
+            "project",
+            "switch_on"
+          ]
+        },
         "when": {
           "type": "string",
           "minLength": 1
@@ -540,6 +550,32 @@
               "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
@@ -575,15 +611,76 @@
             ],
             "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,7 +87,16 @@ 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;
@@ -120,12 +129,30 @@ declare const offer: z.ZodObject<{
         }, 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<{
@@ -262,6 +289,13 @@ export declare const capabilitySchema: z.ZodObject<{
         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;
@@ -294,16 +328,41 @@ export declare const capabilitySchema: z.ZodObject<{
             }, 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";

package/dist/capability-schema.js

@@ -161,9 +161,24 @@ const question = z.strictObject({
     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/"),
@@ -171,6 +186,9 @@ const offer = z.strictObject({
     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"),
@@ -195,6 +213,8 @@ const baseShape = {
     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) => {
@@ -212,6 +232,12 @@ 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();
@@ -222,7 +248,13 @@ function checkOffer(file, component, o, seen) {
         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}.` });
@@ -316,6 +348,14 @@ export function checkManifests(files) {
         }
         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/index.d.ts

@@ -2,7 +2,7 @@ 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, type Offer, } 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";

package/dist/index.js

@@ -2,7 +2,7 @@ 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";

package/dist/skills.js

@@ -21,6 +21,8 @@ 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("");
@@ -36,6 +38,34 @@ function questionBlock(q, n) {
         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;
@@ -64,6 +94,8 @@ export function renderSkill(m) {
         "",
         "## 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.",
@@ -74,6 +106,8 @@ export function renderSkill(m) {
         "",
         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}`));
     }

package/package.json

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