@mccaskie-labs/workbench-config 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @mccaskie-labs/workbench-config
 
+## 0.2.3
+
+### Patch Changes
+
+- Saved layouts for PDFs (capabilities manifest §9.7). workbench-pdf gains `checkLayout` and `fillLayout`, and the `workbench-pdf` command: `drafts` asks the Gateway for two to four layouts with the project's development key and writes HTML previews, `pick` saves one as `workbench/pdf/<name>.json`, and `generate [--check]` writes `src/pdf-layouts.generated.ts` with a typed `PDF_LAYOUTS.<name>.document(data)`. `@mccaskie-labs/workbench-ai` is an optional peer, needed only for `drafts`. The pdf manifest gets its client questions (the `drafts` pattern: what the document is, the paper size, then drafts to pick from), so pdf leaves `OFFER_PENDING`. A must-ask question with answers to pick from now marks none of them "(Recommended)".
+
 ## 0.2.2
 
 ### Patch Changes

package/capabilities/pdf.json

@@ -7,13 +7,14 @@
   "status": "built",
   "delivery": {
     "choice": "optional",
-    "intro": "PDFs such as invoices and receipts, printed with the project's logo and colours.",
-    "when": "The client wants a PDF: an invoice, receipt, quote, certificate, report or anything else to download or print."
+    "intro": "PDFs such as invoices and receipts, printed with the project's logo and colours."
   },
   "surfaces": {
     "package": [
       "createPdfMaker",
-      "WorkbenchPdfError"
+      "WorkbenchPdfError",
+      "checkLayout",
+      "fillLayout"
     ]
   },
   "limits": [
@@ -95,6 +96,89 @@
       "note": "Prints the app's own HTML holding an image from a host not in allowOrigins; the PDF is made and the browser reports that image's request as blocked"
     }
   ],
+  "offer": {
+    "pattern": "drafts",
+    "when": "The client wants a PDF: an invoice, receipt, quote, certificate, report or anything else to download or print.",
+    "say": "I'll make this with Workbench PDFs, printed with your logo and colours. I'll show you a few layouts to pick from. The one you pick is saved, so every one looks the same from then on.",
+    "answers_file": "workbench/pdf/<name>.json",
+    "per": "document",
+    "generator": "npx workbench-pdf generate",
+    "answers_format": "the saved layout. `npx workbench-pdf pick <name> <round>-<draft>` writes it from the draft the client picked, with the draft's request id, model and cost; never write one from nothing. It holds the document's `fields` (each value is text the app formats first, money and dates through the country pack), its `blocks` with `{field}` placeholders, and made-up `sample` values. To change a saved layout in the client's words (move a block, rename a heading, add a field), edit the file and run the generator, which refuses a layout that doesn't check. In the app, print with `pdfMakerFor(env).document(PDF_LAYOUTS.<name>.document(data), { size: PDF_LAYOUTS.<name>.size })`. Drafts and their previews stay in `workbench/pdf/drafts/`, which isn't committed.",
+    "questions": [
+      {
+        "id": "pdf.what",
+        "sets": [
+          "layout.name",
+          "layout.about"
+        ],
+        "ask": "What is this document, and what is it for?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "An invoice",
+            "value": "invoice",
+            "means": "What a customer owes, with the items and the total."
+          },
+          {
+            "label": "A receipt",
+            "value": "receipt",
+            "means": "Proof a customer paid."
+          },
+          {
+            "label": "A quote",
+            "value": "quote",
+            "means": "What a job would cost, before the customer agrees."
+          }
+        ],
+        "other": {
+          "kind": "text",
+          "min": 3,
+          "max": 200,
+          "description": "What the document is, in a few words: a certificate, a run sheet, a booking confirmation."
+        },
+        "note": "The answer's value is the layout's name (lower case and underscores: run_sheet). The client's own words, with anything they add about who reads it, go in --about.",
+        "must_ask": true
+      },
+      {
+        "id": "pdf.size",
+        "sets": "layout.size",
+        "ask": "Which paper size?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "A4",
+            "value": "A4",
+            "means": "Used almost everywhere outside North America."
+          },
+          {
+            "label": "US Letter",
+            "value": "Letter",
+            "means": "Used in the United States and Canada."
+          }
+        ],
+        "note": "Recommend US Letter only when the readers are in the United States or Canada. Pass it to the drafts command as --size."
+      }
+    ],
+    "not_asked": [
+      {
+        "sets": "layout.colours",
+        "why": "The logo, colours and fonts come from the brand (brand.json and the admins' brand page), so every document matches the rest of the app. To restyle a part of the layout, use project.css (see Restyling)."
+      },
+      {
+        "sets": "layout.contents",
+        "why": "The drafts propose what each layout shows. The client changes a picked layout in plain words, and you edit the saved file."
+      }
+    ],
+    "drafts": {
+      "of": "layouts for this document",
+      "surface": "ai",
+      "alias": "claude-default",
+      "count": 3,
+      "max_rounds": 3,
+      "job": "pdf.drafts",
+      "command": "npx workbench-pdf drafts <name> --about \"<what it is for, in the client's words>\" --size <A4 or Letter>"
+    }
+  },
   "styles": {
     "prefix": "wb-pdf-"
   }

package/dist/capabilities.gen.d.ts

@@ -1,4 +1,4 @@
-export declare const MANIFEST_VERSION: "cfe1c836b884";
+export declare const MANIFEST_VERSION: "0a5f38e30870";
 export declare const capabilities: {
     readonly ai: {
         readonly $schema: "./schema.json";
@@ -1814,7 +1814,7 @@ export declare const capabilities: {
         readonly summary: "workbench-pdf prints an app's content as a PDF with its brand.json logo, colours and fonts, in the app's own Worker through its Browser Rendering binding (BROWSER). Nothing goes through the Gateway and the app holds no Cloudflare token. The standard layout takes plain-text blocks; html() takes the app's own markup.";
         readonly status: "built";
         readonly surfaces: {
-            readonly package: readonly ["createPdfMaker", "WorkbenchPdfError"];
+            readonly package: readonly ["createPdfMaker", "WorkbenchPdfError", "checkLayout", "fillLayout"];
         };
         readonly limits: readonly [{
             readonly id: "pdf.blocks";
@@ -1881,13 +1881,79 @@ export declare const capabilities: {
             readonly cost_hint_usd: 0;
             readonly note: "Prints the app's own HTML holding an image from a host not in allowOrigins; the PDF is made and the browser reports that image's request as blocked";
         }];
+        readonly offer: {
+            readonly pattern: "drafts";
+            readonly when: "The client wants a PDF: an invoice, receipt, quote, certificate, report or anything else to download or print.";
+            readonly say: "I'll make this with Workbench PDFs, printed with your logo and colours. I'll show you a few layouts to pick from. The one you pick is saved, so every one looks the same from then on.";
+            readonly answers_file: "workbench/pdf/<name>.json";
+            readonly per: "document";
+            readonly generator: "npx workbench-pdf generate";
+            readonly answers_format: "the saved layout. `npx workbench-pdf pick <name> <round>-<draft>` writes it from the draft the client picked, with the draft's request id, model and cost; never write one from nothing. It holds the document's `fields` (each value is text the app formats first, money and dates through the country pack), its `blocks` with `{field}` placeholders, and made-up `sample` values. To change a saved layout in the client's words (move a block, rename a heading, add a field), edit the file and run the generator, which refuses a layout that doesn't check. In the app, print with `pdfMakerFor(env).document(PDF_LAYOUTS.<name>.document(data), { size: PDF_LAYOUTS.<name>.size })`. Drafts and their previews stay in `workbench/pdf/drafts/`, which isn't committed.";
+            readonly questions: readonly [{
+                readonly id: "pdf.what";
+                readonly sets: readonly ["layout.name", "layout.about"];
+                readonly ask: "What is this document, and what is it for?";
+                readonly style: "cards";
+                readonly answers: readonly [{
+                    readonly label: "An invoice";
+                    readonly value: "invoice";
+                    readonly means: "What a customer owes, with the items and the total.";
+                }, {
+                    readonly label: "A receipt";
+                    readonly value: "receipt";
+                    readonly means: "Proof a customer paid.";
+                }, {
+                    readonly label: "A quote";
+                    readonly value: "quote";
+                    readonly means: "What a job would cost, before the customer agrees.";
+                }];
+                readonly other: {
+                    readonly kind: "text";
+                    readonly min: 3;
+                    readonly max: 200;
+                    readonly description: "What the document is, in a few words: a certificate, a run sheet, a booking confirmation.";
+                };
+                readonly must_ask: true;
+                readonly note: "The answer's value is the layout's name (lower case and underscores: run_sheet). The client's own words, with anything they add about who reads it, go in --about.";
+            }, {
+                readonly id: "pdf.size";
+                readonly sets: "layout.size";
+                readonly ask: "Which paper size?";
+                readonly style: "cards";
+                readonly answers: readonly [{
+                    readonly label: "A4";
+                    readonly value: "A4";
+                    readonly means: "Used almost everywhere outside North America.";
+                }, {
+                    readonly label: "US Letter";
+                    readonly value: "Letter";
+                    readonly means: "Used in the United States and Canada.";
+                }];
+                readonly note: "Recommend US Letter only when the readers are in the United States or Canada. Pass it to the drafts command as --size.";
+            }];
+            readonly not_asked: readonly [{
+                readonly sets: "layout.colours";
+                readonly why: "The logo, colours and fonts come from the brand (brand.json and the admins' brand page), so every document matches the rest of the app. To restyle a part of the layout, use project.css (see Restyling).";
+            }, {
+                readonly sets: "layout.contents";
+                readonly why: "The drafts propose what each layout shows. The client changes a picked layout in plain words, and you edit the saved file.";
+            }];
+            readonly drafts: {
+                readonly of: "layouts for this document";
+                readonly surface: "ai";
+                readonly alias: "claude-default";
+                readonly count: 3;
+                readonly max_rounds: 3;
+                readonly job: "pdf.drafts";
+                readonly command: "npx workbench-pdf drafts <name> --about \"<what it is for, in the client's words>\" --size <A4 or Letter>";
+            };
+        };
         readonly styles: {
             readonly prefix: "wb-pdf-";
         };
         readonly delivery: {
             readonly choice: "optional";
             readonly intro: "PDFs such as invoices and receipts, printed with the project's logo and colours.";
-            readonly when: "The client wants a PDF: an invoice, receipt, quote, certificate, report or anything else to download or print.";
         };
     };
     readonly "sign-in": {

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 = "cfe1c836b884";
+export const MANIFEST_VERSION = "0a5f38e30870";
 export const capabilities = {
     "ai": {
         "$schema": "./schema.json",
@@ -2447,7 +2447,9 @@ export const capabilities = {
         "surfaces": {
             "package": [
                 "createPdfMaker",
-                "WorkbenchPdfError"
+                "WorkbenchPdfError",
+                "checkLayout",
+                "fillLayout"
             ]
         },
         "limits": [
@@ -2529,13 +2531,95 @@ export const capabilities = {
                 "note": "Prints the app's own HTML holding an image from a host not in allowOrigins; the PDF is made and the browser reports that image's request as blocked"
             }
         ],
+        "offer": {
+            "pattern": "drafts",
+            "when": "The client wants a PDF: an invoice, receipt, quote, certificate, report or anything else to download or print.",
+            "say": "I'll make this with Workbench PDFs, printed with your logo and colours. I'll show you a few layouts to pick from. The one you pick is saved, so every one looks the same from then on.",
+            "answers_file": "workbench/pdf/<name>.json",
+            "per": "document",
+            "generator": "npx workbench-pdf generate",
+            "answers_format": "the saved layout. `npx workbench-pdf pick <name> <round>-<draft>` writes it from the draft the client picked, with the draft's request id, model and cost; never write one from nothing. It holds the document's `fields` (each value is text the app formats first, money and dates through the country pack), its `blocks` with `{field}` placeholders, and made-up `sample` values. To change a saved layout in the client's words (move a block, rename a heading, add a field), edit the file and run the generator, which refuses a layout that doesn't check. In the app, print with `pdfMakerFor(env).document(PDF_LAYOUTS.<name>.document(data), { size: PDF_LAYOUTS.<name>.size })`. Drafts and their previews stay in `workbench/pdf/drafts/`, which isn't committed.",
+            "questions": [
+                {
+                    "id": "pdf.what",
+                    "sets": [
+                        "layout.name",
+                        "layout.about"
+                    ],
+                    "ask": "What is this document, and what is it for?",
+                    "style": "cards",
+                    "answers": [
+                        {
+                            "label": "An invoice",
+                            "value": "invoice",
+                            "means": "What a customer owes, with the items and the total."
+                        },
+                        {
+                            "label": "A receipt",
+                            "value": "receipt",
+                            "means": "Proof a customer paid."
+                        },
+                        {
+                            "label": "A quote",
+                            "value": "quote",
+                            "means": "What a job would cost, before the customer agrees."
+                        }
+                    ],
+                    "other": {
+                        "kind": "text",
+                        "min": 3,
+                        "max": 200,
+                        "description": "What the document is, in a few words: a certificate, a run sheet, a booking confirmation."
+                    },
+                    "must_ask": true,
+                    "note": "The answer's value is the layout's name (lower case and underscores: run_sheet). The client's own words, with anything they add about who reads it, go in --about."
+                },
+                {
+                    "id": "pdf.size",
+                    "sets": "layout.size",
+                    "ask": "Which paper size?",
+                    "style": "cards",
+                    "answers": [
+                        {
+                            "label": "A4",
+                            "value": "A4",
+                            "means": "Used almost everywhere outside North America."
+                        },
+                        {
+                            "label": "US Letter",
+                            "value": "Letter",
+                            "means": "Used in the United States and Canada."
+                        }
+                    ],
+                    "note": "Recommend US Letter only when the readers are in the United States or Canada. Pass it to the drafts command as --size."
+                }
+            ],
+            "not_asked": [
+                {
+                    "sets": "layout.colours",
+                    "why": "The logo, colours and fonts come from the brand (brand.json and the admins' brand page), so every document matches the rest of the app. To restyle a part of the layout, use project.css (see Restyling)."
+                },
+                {
+                    "sets": "layout.contents",
+                    "why": "The drafts propose what each layout shows. The client changes a picked layout in plain words, and you edit the saved file."
+                }
+            ],
+            "drafts": {
+                "of": "layouts for this document",
+                "surface": "ai",
+                "alias": "claude-default",
+                "count": 3,
+                "max_rounds": 3,
+                "job": "pdf.drafts",
+                "command": "npx workbench-pdf drafts <name> --about \"<what it is for, in the client's words>\" --size <A4 or Letter>"
+            }
+        },
         "styles": {
             "prefix": "wb-pdf-"
         },
         "delivery": {
             "choice": "optional",
-            "intro": "PDFs such as invoices and receipts, printed with the project's logo and colours.",
-            "when": "The client wants a PDF: an invoice, receipt, quote, certificate, report or anything else to download or print."
+            "intro": "PDFs such as invoices and receipts, printed with the project's logo and colours."
         }
     },
     "sign-in": {

package/dist/capability-schema.d.ts

@@ -401,7 +401,7 @@ export type Offer = z.infer<typeof offer>;
  * 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", "image-search", "images", "pdf", "strings", "ui"];
+export declare const OFFER_PENDING: readonly ["ai", "analytics", "country", "database", "email", "email-inbound", "image-search", "images", "strings", "ui"];
 export interface ManifestProblem {
     file: string;
     check: "schema" | "proof" | "ids" | "surfaces" | "errors" | "generated";

package/dist/capability-schema.js

@@ -267,7 +267,7 @@ export const capabilitySchema = z.strictObject(baseShape).superRefine((m, ctx) =
  * 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", "image-search", "images", "pdf", "strings", "ui"];
+export const OFFER_PENDING = ["ai", "analytics", "country", "database", "email", "email-inbound", "image-search", "images", "strings", "ui"];
 function checkOffer(file, component, o, seen) {
     const problems = [];
     const named = new Map();

package/dist/skills.js

@@ -41,8 +41,11 @@ function questionBlock(q, n) {
         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 {
+        // A must-ask question has no safe default, so none of its answers is recommended.
+        if (q.must_ask)
+            lines.push("None of these answers is recommended: only the client knows, so don't label any \"(Recommended)\".", "");
         lines.push("| Answer | Value | Means |", "| --- | --- | --- |");
-        (q.answers ?? []).forEach((a, i) => lines.push(`| ${cell(a.label)}${i === 0 ? " (Recommended)" : ""} | ${show(a.value)} | ${cell(a.means ?? "")} |`));
+        (q.answers ?? []).forEach((a, i) => lines.push(`| ${cell(a.label)}${i === 0 && !q.must_ask ? " (Recommended)" : ""} | ${show(a.value)} | ${cell(a.means ?? "")} |`));
     }
     lines.push("", otherLine(q));
     if (q.note)
@@ -149,7 +152,7 @@ export function renderSkill(m, guide) {
     }
     out.push("", "## What to say", "", d.choice === "optional"
         ? `Once the owner's choice is yes, say: "${o.say}"`
-        : `Say: "${o.say}" Don't ask whether to use Workbench or something of the client's own. If the client says they don't want it, stop and say what they give up.`, "", "## How to ask", "", ...(o.needs?.length ? [`- First check the project setup this needs: ${o.needs.map((n) => `\`workbench/${n}.json\``).join(", ")}. If one is missing, use that component's \`workbench-<component>\` skill first.`] : []), ...PATTERN_STEPS[o.pattern].map((step) => `- ${step}`), "- Ask with the AskUserQuestion tool, up to four questions per call. Give each question's answers in the order below; the first is recommended, so label it \"(Recommended)\". The tool adds \"Other\" itself.", "- Where the client accepts every recommendation, still ask each \"Must ask\" question.", "- An \"Other\" answer must meet the rule under its question. When it doesn't, say why and ask again. Never store a value outside it.", "- Ask nothing that isn't listed here, and invent no setting. A need the questions don't cover goes back to the client as a plain question, and isn't written to the answers file.", `- Write the answers to \`${o.answers_file}\`${o.per ? `, one entry per ${o.per}` : ""}: ${o.answers_format ?? `for each question its id, the value, and the client's own words when they typed "Other" or changed a recommendation.`}${o.generator ? ` Then run \`${o.generator}\`, which writes the code and refuses anything the package can't apply (it doesn't check the "Other" rules: you do). It builds nothing while an answers file is a draft. Never edit what it writes; change the answers file and run it again.` : ""}`, "", "## Questions", "", o.questions.map((q, i) => questionBlock(q, i + 1)).join("\n\n"));
+        : `Say: "${o.say}" Don't ask whether to use Workbench or something of the client's own. If the client says they don't want it, stop and say what they give up.`, "", "## How to ask", "", ...(o.needs?.length ? [`- First check the project setup this needs: ${o.needs.map((n) => `\`workbench/${n}.json\``).join(", ")}. If one is missing, use that component's \`workbench-<component>\` skill first.`] : []), ...PATTERN_STEPS[o.pattern].map((step) => `- ${step}`), "- Ask with the AskUserQuestion tool, up to four questions per call. Give each question's answers in the order below; the first is recommended, so label it \"(Recommended)\", unless the question says none is. The tool adds \"Other\" itself.", "- Where the client accepts every recommendation, still ask each \"Must ask\" question.", "- An \"Other\" answer must meet the rule under its question. When it doesn't, say why and ask again. Never store a value outside it.", "- Ask nothing that isn't listed here, and invent no setting. A need the questions don't cover goes back to the client as a plain question, and isn't written to the answers file.", `- Write the answers to \`${o.answers_file}\`${o.per ? `, one entry per ${o.per}` : ""}: ${o.answers_format ?? `for each question its id, the value, and the client's own words when they typed "Other" or changed a recommendation.`}${o.generator ? ` Then run \`${o.generator}\`, which writes the code and refuses anything the package can't apply (it doesn't check the "Other" rules: you do). It builds nothing while an answers file is a draft. Never edit what it writes; change the answers file and run it again.` : ""}`, "", "## Questions", "", o.questions.map((q, i) => questionBlock(q, i + 1)).join("\n\n"));
     if (o.drafts)
         out.push("", draftsBlock(o.drafts));
     if (o.not_asked?.length) {

package/package.json

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