@mccaskie-labs/workbench-config 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @mccaskie-labs/workbench-config
 
+## 0.2.4
+
+### Patch Changes
+
+- Client questions for AI, pictures and picture search (feature or content): a routing question, then who may use a visitor feature and its monthly cap, or drafts of content made once. `npx workbench-ai drafts text|image|search` and `pick` make and keep that content through the Gateway with the development key. A drafts skill with no development key now offers the client's own wording or picture as well as the standard version.
+
 ## 0.2.3
 
 ### Patch Changes

package/capabilities/ai.json

@@ -7,8 +7,7 @@
   "status": "built",
   "delivery": {
     "choice": "built_in",
-    "intro": "Writing, summarising and answering questions with Claude, with a monthly spending cap.",
-    "when": "The client wants the app to write, summarise, sort, answer questions or pull details out of text with AI, as a feature visitors use or as something made once for the site."
+    "intro": "Writing, summarising and answering questions with Claude, with a monthly spending cap."
   },
   "surfaces": {
     "gateway": ["POST /anthropic/v1/messages", "POST /anthropic/v1/messages/count_tokens"],
@@ -118,5 +117,186 @@
     { "id": "ai.voice", "half": "runtime", "expect": "pass", "cost_hint_usd": 0.004 },
     { "id": "ai.voice.unknown", "half": "runtime", "expect": "refused_as_expected", "refusal": "invalid_request", "cost_hint_usd": 0 },
     { "id": "ai.voice.cache-read", "half": "runtime", "expect": "pass", "cost_hint_usd": 0.008 }
-  ]
+  ],
+  "offer": {
+    "pattern": "feature_or_content",
+    "when": "The client wants the app to write, summarise, sort, answer questions or pull details out of text with AI, as a feature visitors use, or wants wording for the site written once.",
+    "say": "I'll do this with Workbench AI, which uses Claude through Workbench, so the app holds no AI key and spending has a monthly cap.",
+    "answers_file": "workbench/ai/<name>.json",
+    "per": "feature or piece of wording",
+    "answers_format": "For a feature: `{ \"format\": 1, \"route\": \"feature\", \"name\", \"about\" (the client's words), \"who\", \"cap_usd\", \"keep\", \"job\" }`, where `job` is the `X-Workbench-Job` the feature's calls send (`<name>` with dots, such as `quotes.estimate`), so its spending shows on its own line in Control. Write it, then build the feature with the package. For wording made once: `npx workbench-ai pick <name> <round>-<draft>` writes it from the draft the client picked, with the round's request ids and cost; never write one from nothing. Then put the wording into the strings catalogue (the workbench-strings skill), keyed for where it is shown. Drafts and their previews stay in `workbench/ai/drafts/`, which isn't committed.",
+    "questions": [
+      {
+        "id": "ai.route",
+        "sets": "route",
+        "ask": "Is this something visitors use on the site, or something made once for the site?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "Visitors use it",
+            "value": "feature",
+            "means": "A feature on the site that calls the AI each time someone uses it, such as a question box or a summary of what they paste in."
+          },
+          {
+            "label": "Made once for the site",
+            "value": "content",
+            "means": "Wording for a page, written once and kept: an About page, a welcome, product descriptions."
+          }
+        ],
+        "must_ask": true,
+        "note": "Ask it even when the client's words seem to say, as a quick check: the two routes are built and paid for differently."
+      },
+      {
+        "id": "ai.who",
+        "sets": "feature.who",
+        "ask": "Who may use it?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "People who are signed in",
+            "value": "signed_in",
+            "means": "Anyone with an account. Each use is tied to a person, so misuse can be traced and stopped."
+          },
+          {
+            "label": "Admins only",
+            "value": "admins",
+            "means": "Only the business's own admins, for example a tool for writing their own posts."
+          },
+          {
+            "label": "Anyone visiting",
+            "value": "anyone",
+            "means": "No sign-in. The page checks for bots (Turnstile) and limits how often one visitor can use it."
+          }
+        ],
+        "when": {
+          "id": "ai.route",
+          "is": [
+            "feature"
+          ]
+        },
+        "note": "Signed in means `requireUser` and admins means `app_admins`, as the workbench-sign-in skill says. For anyone, check Turnstile on every use and keep a per-visitor limit; say plainly that strangers can run up the cost. Pass `subject` on every call so the Gateway can tell people apart: `user:<id>` for a signed-in person, and for anyone a random id kept in a cookie (`visitor:<id>`), never an email address or name."
+      },
+      {
+        "id": "ai.cap",
+        "sets": "feature.cap_usd",
+        "ask": "How much may it spend in a month, at most? When it's reached, the feature stops until next month.",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "US$5 a month",
+            "value": 5,
+            "means": "A small trial, or light use."
+          },
+          {
+            "label": "US$20 a month",
+            "value": 20,
+            "means": "Steady use by a small business's visitors."
+          },
+          {
+            "label": "US$50 a month",
+            "value": 50,
+            "means": "Heavy use. It can be raised later."
+          }
+        ],
+        "other": {
+          "kind": "money",
+          "min": 1,
+          "max": 1000,
+          "description": "US dollars a month, whole or with cents."
+        },
+        "must_ask": true,
+        "when": {
+          "id": "ai.route",
+          "is": [
+            "feature"
+          ]
+        },
+        "note": "Say roughly what one use costs (usually a cent or two with claude-default) so the owner can judge. The cap is the project's production cap for the `ai` tool in the Gateway, shared by every feature that uses it: set it with Workbench Control's `gw_budget_set` (env production, tool ai, monthly_usd). Raising a cap waits for the owner's approval on Control's approval page. When it is reached, calls fail with `budget_exceeded`: the page says the feature is resting until next month, never an error."
+      },
+      {
+        "id": "ai.sensitive",
+        "sets": "feature.keep",
+        "ask": "Will people type in sensitive personal details, such as their health, religion, money troubles or someone else's private information?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "No",
+            "value": "no",
+            "means": "Workbench keeps what each call sent and got back, so a problem can be traced."
+          },
+          {
+            "label": "Yes",
+            "value": "yes",
+            "means": "This feature's calls are marked not to be kept: Workbench records only that each call happened and what it cost."
+          }
+        ],
+        "must_ask": true,
+        "when": {
+          "id": "ai.route",
+          "is": [
+            "feature"
+          ]
+        },
+        "note": "With yes, pass `keep: false` on this feature's calls. If most of the app handles such details, suggest switching keeping off for the whole project instead (Workbench Control's `gw_keep_set`, env production, on false). Record it as `keep` (true or false) in the answers file."
+      },
+      {
+        "id": "ai.what",
+        "sets": [
+          "content.name",
+          "content.about"
+        ],
+        "ask": "What wording do you need?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "A page's main text",
+            "value": "page_text",
+            "means": "Such as an About page or a services page."
+          },
+          {
+            "label": "A short blurb",
+            "value": "blurb",
+            "means": "A line or two for the top of a page or a card."
+          },
+          {
+            "label": "Descriptions",
+            "value": "descriptions",
+            "means": "For products or services."
+          }
+        ],
+        "other": {
+          "kind": "text",
+          "min": 3,
+          "max": 200,
+          "description": "What the wording is, in a few words."
+        },
+        "when": {
+          "id": "ai.route",
+          "is": [
+            "content"
+          ]
+        },
+        "note": "Name the piece after where it goes (about_us, home_blurb): lower case and underscores. The client's own words, with any facts they give (when they started, where they are), go in --about, because the drafts never invent facts and leave [gaps] for the owner instead."
+      }
+    ],
+    "not_asked": [
+      {
+        "sets": "model",
+        "why": "Features use claude-default unless the work needs more (claude-best) or speed matters more than depth (claude-fast). Choose from what the feature does; the client can't judge models."
+      },
+      {
+        "sets": "voice",
+        "why": "The tone comes from the project's voice and spelling, set once for the whole site."
+      }
+    ],
+    "drafts": {
+      "of": "wording",
+      "surface": "ai",
+      "alias": "claude-default",
+      "count": 3,
+      "max_rounds": 3,
+      "job": "ai.drafts",
+      "command": "npx workbench-ai drafts text <name> --about \"<what it is for, with the client's facts>\""
+    }
+  }
 }

package/capabilities/image-search.json

@@ -7,8 +7,7 @@
   "status": "built",
   "delivery": {
     "choice": "built_in",
-    "intro": "Finding existing pictures on the web.",
-    "when": "The client wants to find existing pictures on the web, for the site itself or as a search visitors use."
+    "intro": "Finding existing pictures on the web."
   },
   "surfaces": {
     "gateway": [
@@ -131,5 +130,157 @@
       "smoke": true,
       "cost_hint_usd": 0.001
     }
-  ]
+  ],
+  "offer": {
+    "pattern": "feature_or_content",
+    "when": "The client wants to find existing pictures on the web, for the site itself or as a search visitors use.",
+    "say": "I'll do this with Workbench picture search, which searches the web through Workbench, so the app holds no search key and spending has a monthly cap.",
+    "answers_file": "workbench/image-search/<name>.json",
+    "per": "feature or picture",
+    "answers_format": "For a feature: `{ \"format\": 1, \"route\": \"feature\", \"name\", \"about\" (the client's words), \"who\", \"cap_usd\", \"job\" }`, where `job` is the `X-Workbench-Job` the feature's calls send (`<name>` with dots, such as `quotes.estimate`), so its spending shows on its own line in Control. Write it, then build the feature with the package. For a picture found once: `npx workbench-ai pick <name> <round>-<draft> --licence \"<the owner's words>\"` downloads it to `public/images/<name>.jpg` (or .png) and writes the answers file with where it came from and the licence; never write one from nothing, and never pick one without the licence answer. Show the credit the licence asks for beside the picture. Drafts and their previews stay in `workbench/image-search/drafts/`, which isn't committed.",
+    "questions": [
+      {
+        "id": "image-search.route",
+        "sets": "route",
+        "ask": "Is this something visitors use on the site, or something made once for the site?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "Visitors use it",
+            "value": "feature",
+            "means": "A search on the site that finds pictures for whoever uses it."
+          },
+          {
+            "label": "Made once for the site",
+            "value": "content",
+            "means": "A picture for the site, found once and kept."
+          }
+        ],
+        "must_ask": true,
+        "note": "Ask it even when the client's words seem to say, as a quick check: the two routes are built and paid for differently."
+      },
+      {
+        "id": "image-search.who",
+        "sets": "feature.who",
+        "ask": "Who may use it?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "People who are signed in",
+            "value": "signed_in",
+            "means": "Anyone with an account. Each use is tied to a person, so misuse can be traced and stopped."
+          },
+          {
+            "label": "Admins only",
+            "value": "admins",
+            "means": "Only the business's own admins, for example a tool for writing their own posts."
+          },
+          {
+            "label": "Anyone visiting",
+            "value": "anyone",
+            "means": "No sign-in. The page checks for bots (Turnstile) and limits how often one visitor can use it."
+          }
+        ],
+        "when": {
+          "id": "image-search.route",
+          "is": [
+            "feature"
+          ]
+        },
+        "note": "Signed in means `requireUser` and admins means `app_admins`, as the workbench-sign-in skill says. For anyone, check Turnstile on every use and keep a per-visitor limit; say plainly that strangers can run up the cost. Pass `subject` on every call so the Gateway can tell people apart: `user:<id>` for a signed-in person, and for anyone a random id kept in a cookie (`visitor:<id>`), never an email address or name."
+      },
+      {
+        "id": "image-search.cap",
+        "sets": "feature.cap_usd",
+        "ask": "How much may it spend in a month, at most? When it's reached, the feature stops until next month.",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "US$5 a month",
+            "value": 5,
+            "means": "A small trial, or light use."
+          },
+          {
+            "label": "US$20 a month",
+            "value": 20,
+            "means": "Steady use by a small business's visitors."
+          },
+          {
+            "label": "US$50 a month",
+            "value": 50,
+            "means": "Heavy use. It can be raised later."
+          }
+        ],
+        "other": {
+          "kind": "money",
+          "min": 1,
+          "max": 1000,
+          "description": "US dollars a month, whole or with cents."
+        },
+        "must_ask": true,
+        "when": {
+          "id": "image-search.route",
+          "is": [
+            "feature"
+          ]
+        },
+        "note": "Say roughly what one use costs (about a tenth of a cent a search) so the owner can judge. The cap is the project's production cap for the `search` tool in the Gateway, shared by every feature that uses it: set it with Workbench Control's `gw_budget_set` (env production, tool search, monthly_usd). Raising a cap waits for the owner's approval on Control's approval page. When it is reached, calls fail with `budget_exceeded`: the page says the feature is resting until next month, never an error."
+      },
+      {
+        "id": "image-search.licence",
+        "sets": "content.licence",
+        "ask": "Does the site have the right to use this picture?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "Yes, it's ours",
+            "value": "own",
+            "means": "The business took it or owns it."
+          },
+          {
+            "label": "Yes, it's free to use",
+            "value": "free",
+            "means": "Its page says so, with a licence such as CC BY. Say which."
+          },
+          {
+            "label": "No, find another",
+            "value": "none",
+            "means": "Pick another result, or make one with AI pictures instead."
+          }
+        ],
+        "other": {
+          "kind": "text",
+          "min": 3,
+          "max": 200,
+          "description": "What gives the site the right to use it."
+        },
+        "must_ask": true,
+        "when": {
+          "id": "image-search.route",
+          "is": [
+            "content"
+          ]
+        },
+        "note": "Ask after the client picks a result, showing its page link. A search result is a lead, not permission. Pass the client's words as --licence; with no, don't pick it."
+      }
+    ],
+    "not_asked": [
+      {
+        "sets": "query",
+        "why": "The client's description is the search: pass it as --about, shortened to the words that matter."
+      },
+      {
+        "sets": "filters",
+        "why": "Results narrower than 600 pixels are dropped; anything finer (shape, site) is for a feature to do in its own code."
+      }
+    ],
+    "drafts": {
+      "of": "found pictures",
+      "surface": "image-search",
+      "count": 4,
+      "max_rounds": 3,
+      "job": "image-search.drafts",
+      "command": "npx workbench-ai drafts search <name> --about \"<what to search for>\""
+    }
+  }
 }

package/capabilities/images.json

@@ -7,8 +7,7 @@
   "status": "built",
   "delivery": {
     "choice": "built_in",
-    "intro": "Pictures made by AI from a description.",
-    "when": "The client wants a picture made by AI, such as an illustration, a hero image or a product mock-up, as a feature visitors use or once for the site."
+    "intro": "Pictures made by AI from a description."
   },
   "surfaces": {
     "gateway": [
@@ -209,5 +208,195 @@
       "refusal": "invalid_request",
       "cost_hint_usd": 0
     }
-  ]
+  ],
+  "offer": {
+    "pattern": "feature_or_content",
+    "when": "The client wants a picture made by AI, such as an illustration, a hero image or a product mock-up, as a feature visitors use or once for the site.",
+    "say": "I'll make this with Workbench pictures, made by AI through Workbench, so the app holds no image key and spending has a monthly cap.",
+    "answers_file": "workbench/images/<name>.json",
+    "per": "feature or picture",
+    "answers_format": "For a feature: `{ \"format\": 1, \"route\": \"feature\", \"name\", \"about\" (the client's words), \"who\", \"cap_usd\", \"job\" }`, where `job` is the `X-Workbench-Job` the feature's calls send (`<name>` with dots, such as `quotes.estimate`), so its spending shows on its own line in Control. Write it, then build the feature with the package. For a picture made once: `npx workbench-ai pick <name> <round>-<draft>` copies the picked picture to `public/images/<name>.png` (or .jpg) and writes the answers file with its prompt, model, request id and cost; never write one from nothing. Show it on the page from `/images/<name>.png`, with alt text that says what it shows. Drafts and their previews stay in `workbench/images/drafts/`, which isn't committed.",
+    "questions": [
+      {
+        "id": "images.route",
+        "sets": "route",
+        "ask": "Is this something visitors use on the site, or something made once for the site?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "Visitors use it",
+            "value": "feature",
+            "means": "A feature that makes a new picture each time someone uses it, such as a mock-up of their own design."
+          },
+          {
+            "label": "Made once for the site",
+            "value": "content",
+            "means": "A picture for the site, made once and kept: a hero image, an illustration for a page."
+          }
+        ],
+        "must_ask": true,
+        "note": "Ask it even when the client's words seem to say, as a quick check: the two routes are built and paid for differently."
+      },
+      {
+        "id": "images.who",
+        "sets": "feature.who",
+        "ask": "Who may use it?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "People who are signed in",
+            "value": "signed_in",
+            "means": "Anyone with an account. Each use is tied to a person, so misuse can be traced and stopped."
+          },
+          {
+            "label": "Admins only",
+            "value": "admins",
+            "means": "Only the business's own admins, for example a tool for writing their own posts."
+          },
+          {
+            "label": "Anyone visiting",
+            "value": "anyone",
+            "means": "No sign-in. The page checks for bots (Turnstile) and limits how often one visitor can use it."
+          }
+        ],
+        "when": {
+          "id": "images.route",
+          "is": [
+            "feature"
+          ]
+        },
+        "note": "Signed in means `requireUser` and admins means `app_admins`, as the workbench-sign-in skill says. For anyone, check Turnstile on every use and keep a per-visitor limit; say plainly that strangers can run up the cost. Pass `subject` on every call so the Gateway can tell people apart: `user:<id>` for a signed-in person, and for anyone a random id kept in a cookie (`visitor:<id>`), never an email address or name."
+      },
+      {
+        "id": "images.cap",
+        "sets": "feature.cap_usd",
+        "ask": "How much may it spend in a month, at most? When it's reached, the feature stops until next month.",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "US$5 a month",
+            "value": 5,
+            "means": "A small trial, or light use."
+          },
+          {
+            "label": "US$20 a month",
+            "value": 20,
+            "means": "Steady use by a small business's visitors."
+          },
+          {
+            "label": "US$50 a month",
+            "value": 50,
+            "means": "Heavy use. It can be raised later."
+          }
+        ],
+        "other": {
+          "kind": "money",
+          "min": 1,
+          "max": 1000,
+          "description": "US dollars a month, whole or with cents."
+        },
+        "must_ask": true,
+        "when": {
+          "id": "images.route",
+          "is": [
+            "feature"
+          ]
+        },
+        "note": "Say roughly what one use costs (about US$0.07 a picture with image-default) so the owner can judge. The cap is the project's production cap for the `images` tool in the Gateway, shared by every feature that uses it: set it with Workbench Control's `gw_budget_set` (env production, tool images, monthly_usd). Raising a cap waits for the owner's approval on Control's approval page. When it is reached, calls fail with `budget_exceeded`: the page says the feature is resting until next month, never an error."
+      },
+      {
+        "id": "images.what",
+        "sets": [
+          "content.name",
+          "content.about"
+        ],
+        "ask": "What picture do you need?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "A hero image",
+            "value": "hero",
+            "means": "The large picture across the top of a page."
+          },
+          {
+            "label": "An illustration",
+            "value": "illustration",
+            "means": "A drawing for a page or a section."
+          },
+          {
+            "label": "A product mock-up",
+            "value": "mockup",
+            "means": "A product shown in use or in a setting."
+          }
+        ],
+        "other": {
+          "kind": "text",
+          "min": 3,
+          "max": 200,
+          "description": "What the picture is, in a few words."
+        },
+        "when": {
+          "id": "images.route",
+          "is": [
+            "content"
+          ]
+        },
+        "note": "Name the picture after where it goes (home_hero): lower case and underscores. The client's own words about what it shows and the feel they want go in --about."
+      },
+      {
+        "id": "images.shape",
+        "sets": "content.aspect",
+        "ask": "What shape should it be?",
+        "style": "cards",
+        "answers": [
+          {
+            "label": "Landscape (3:2)",
+            "value": "3:2",
+            "means": "Wider than tall, the usual shape for a page."
+          },
+          {
+            "label": "Wide banner (16:9)",
+            "value": "16:9",
+            "means": "For a picture across the top of a page."
+          },
+          {
+            "label": "Square (1:1)",
+            "value": "1:1",
+            "means": "For cards and social posts."
+          },
+          {
+            "label": "Portrait (2:3)",
+            "value": "2:3",
+            "means": "Taller than wide."
+          }
+        ],
+        "when": {
+          "id": "images.route",
+          "is": [
+            "content"
+          ]
+        },
+        "note": "Recommend the banner for a hero image. Pass it to the drafts command as --aspect."
+      }
+    ],
+    "not_asked": [
+      {
+        "sets": "model",
+        "why": "Drafts and features use image-default. image-pro costs about twice as much for finer detail and image-openai is cheapest; suggest one only when the client asks about quality or cost."
+      },
+      {
+        "sets": "references",
+        "why": "A reference picture (to make something like it) is only for a feature that needs one, and works with Google aliases only; offer it when the client mentions one."
+      }
+    ],
+    "drafts": {
+      "of": "pictures",
+      "surface": "images",
+      "alias": "image-default",
+      "count": 3,
+      "max_rounds": 3,
+      "job": "images.drafts",
+      "command": "npx workbench-ai drafts image <name> --about \"<what it shows, in the client's words>\" --aspect <shape>"
+    }
+  }
 }