@widgetic/cli 0.1.1 → 0.1.3

package/README.md

@@ -20,7 +20,7 @@ widgetic api widgets get-widgets       # a REST call
 widgetic mcp create-widget --title "Launch countdown" --brief "A countdown to 14 March 2027" --wait
 ```
 
-`widgetic --help`, `widgetic api --help`, `widgetic api <group> --help` and `widgetic <command> --help` list what is there. The whole reference, one page per group, is generated into [`docs/commands`](docs/commands/index.mdx).
+`widgetic` on its own (or `widgetic --help`) is the menu: the commands under three headings, the first steps (make a key in the dashboard under Settings > API Keys, log in, run `doctor`) and a few examples. `widgetic api --help` lists the groups of the REST API with a line each, `widgetic mcp --help` lists the build tools by what they do to your account (read, write, publish, delete), and `widgetic api <group> --help` and `widgetic <command> --help` go one level down. A word that is no command is looked for in both: `widgetic widgets list` answers `try widgetic api widgets list`. The whole reference, one page per group, is generated into [`docs/commands`](docs/commands/index.mdx).
 
 ## The commands
 
@@ -66,7 +66,7 @@ The CLI is generated from the **public** contracts and from nothing else. `@widg
 | `partner`                                 | A partner key (`wgt_prt_…`): managed users, credits, storage, analytics | Listed. Its help says `Needs a partner API key (wgt_prt_…).`                     |
 | `public`                                  | Browsers, with no key: the runtime of an embed                          | Left out of `--help`; `widgetic api call <operationId>` runs it. No key is sent. |
 
-The CLI does not decide who may do what. The API does, on every call, from the key: a key without the scope or the level gets a 403 (exit code 3), the same answer as from the SDK or from `curl`. The CLI only makes what the key may already do easy to find and to call.
+The CLI does not decide who may do what. The API does, on every call, from the key: a key without the scope or the level gets a 403 (exit code 3), the same answer as from the SDK or from `curl`. The CLI only makes what the key may already do easy to find and to call. One thing to know when you make the key: the `widgetic mcp` commands need a key made with **full access**, because the MCP endpoint hands a client every tool the account has and refuses a key limited to some scopes (the dashboard's "Read only", "Content" and "Custom"). The `widgetic api` commands work with a limited key, within its scopes.
 
 ## The key
 
@@ -145,7 +145,7 @@ The gateway (`Services/api-gateway-service`) builds a package, [`@widgetic/api-c
 There is nothing to keep in step by hand: the commands are a function of the contracts, and four guards fail when they are not.
 
 - **Tests.** `test/command-snapshot.test.ts` holds the command tree (names, flags, groups) to a checked-in snapshot, so a new endpoint, a renamed tool or a changed flag shows up as a diff somebody reads; `test/command-reference.test.ts` does the same for the generated reference in `docs/commands`; the generator tests fail on an operation or a tool that has no command, or two with one name.
-- **The release gate** (`npm run check:release`, run by the publish script before the version is raised, and by the `publish` job of `.gitlab-ci.yml`). It fails unless the contracts the commands were generated from are a release, are the newest `latest` of `@widgetic/api-contracts` on npm, and the tool names and the tool contract version are the ones production's MCP `tools/list` answers. It asks production with the key of `WIDGETIC_API_KEY` or of `widgetic auth login`; a read-only key is enough. Nothing is published and no version is raised when it fails.
+- **The release gate** (`npm run check:release`, run by the publish script before the version is raised, and by the `publish` job of `.gitlab-ci.yml`). It fails unless the contracts the commands were generated from are a release, are the newest `latest` of `@widgetic/api-contracts` on npm, and the tool names and the tool contract version are the ones production's MCP server serves. It reads that from `/.well-known/widgetic-mcp-contract` on production's MCP host, a public document (the contract version, the number of tools and their names; no key, no cookie, no description of any tool, a redirect is never followed). A document that is there but cannot be trusted (an error, something that is not JSON, another schema, a count that is not the length of the list) fails the gate: it never sends the gate to look somewhere else. Only while production runs a gateway older than the release that adds the document (it answers `404`) does the gate ask the MCP server itself, with the key of `WIDGETIC_API_KEY` or of `widgetic auth login`: `initialize`, then `tools/list`. That key has to be made with full access: the MCP endpoint refuses a key limited to some scopes (read only, content or custom), and a key for a CI variable is best made on an account that is used for nothing else. With neither the document nor a key the gate fails, and says which of the two is missing. The report says which one it relied on. Nothing is published and no version is raised when it fails.
 - **At run time.** When an MCP command opens a session and the server's tool contract is not the one the CLI was built for, the CLI says so once in 24 hours on stderr (never with `--json`), and `widgetic doctor` always shows the two versions.
 - **The server can refuse an old CLI.** Every request carries `X-SDK-Version: @widgetic/cli/<version>` (MCP: the client's `clientInfo`). The gateway counts the versions it sees and can answer `426` to one that is too old: exit code 7.
 
@@ -159,7 +159,7 @@ npm run check          # typecheck, tests, prettier
 npm run build          # dist/ (and generated/)
 npm run docs           # write docs/commands from the installed contracts
 npm run snapshot       # write the command snapshot from the installed contracts
-npm run check:release  # the release gate (needs the network and a key)
+npm run check:release  # the release gate (needs the network; a key only while production publishes no contract document)
 ```
 
 Tests run the real program in-process against a fake environment (`test/helpers/fake-environment.ts`): a fetch that answers from a function and records what it was asked, streams that collect the output, no terminal, no real network, and a package manager that is a function (nothing is ever installed by a test). A fake MCP server (`test/helpers/fake-mcp-server.ts`) answers the MCP tests. The question on the terminal is the one thing the fake replaces whole, so `test/terminal.test.ts` runs the real one on streams of its own.

package/dist/cli.js

@@ -6,6 +6,7 @@ import { registerDoctorCommand } from "./commands/doctor.js";
 import { registerSchemaCommand } from "./commands/schema.js";
 import { registerUpdateCommand } from "./commands/update.js";
 import { CliError, EXIT_CODES, usageError } from "./errors.js";
+import { apiHelpFooter, existingCommandPath, firstCommandWord, mcpHelpFooter, ROOT_HEADINGS, rootHelpFooter, unknownCommandHint } from "./help.js";
 import { loadMcpManifest, loadRestManifest } from "./manifest/load.js";
 import { registerMcpCommands } from "./mcp/register.js";
 import { asCliError, printError } from "./output.js";
@@ -58,12 +59,19 @@ export function namespaceOf(argv) {
  */
 export function buildProgram(environment, argv = []) {
     const root = createRootCommand(environment);
+    // The list of commands in `widgetic --help` is a menu: each command is listed under the heading that was set when it
+    // was added, with the one line of its `summary` (the whole `description` is the help of the command itself).
+    root.commandsGroup(ROOT_HEADINGS.work);
     const api = root
         .command('api')
-        .description('Call the public REST API: one command for every operation of its OpenAPI description.');
+        .summary('Call the public REST API: one command for every operation.')
+        .description('Call the public REST API: one command for every operation of its OpenAPI description.')
+        .addHelpText('after', apiHelpFooter());
     const mcp = root
         .command('mcp')
-        .description('Run the AI build tools of the Widgetic MCP server: one command for every tool.');
+        .summary('Build, edit and publish widgets with the AI build tools of the MCP server.')
+        .description('Run the AI build tools of the Widgetic MCP server: one command for every tool.')
+        .addHelpText('after', mcpHelpFooter());
     const namespace = namespaceOf(argv);
     if (namespace === 'api') {
         const manifest = loadRestManifest();
@@ -75,29 +83,53 @@ export function buildProgram(environment, argv = []) {
         registerMcpCommands(mcp, manifest, environment);
         registerMcpCall(mcp, manifest, { environment, manifest });
     }
+    root.commandsGroup(ROOT_HEADINGS.setup);
     registerAuthCommands(root, environment);
     registerDoctorCommand(root, environment);
     registerUpdateCommand(root, environment);
-    registerSchemaCommand(root, environment);
     registerCompletionCommands(root, environment, (words) => buildProgram(environment, words));
+    root.commandsGroup(ROOT_HEADINGS.lookup);
+    registerSchemaCommand(root, environment);
+    root.helpCommand('help [command]', 'Show the help of a command');
+    root.addHelpText('after', rootHelpFooter());
     return root;
 }
-/** What a Commander error becomes: `null` when it only means "the help or the version was printed". */
-function fromCommanderError(error) {
+/**
+ * What a Commander error becomes: `null` when it only means "the help or the version was printed". A word that is no
+ * command of `widgetic` itself gets a hint that looks for it in the REST API and among the tools (`widgetic widgets
+ * list` was meant as `widgetic api widgets list`); one that is no command under `api` or `mcp` keeps Commander's own
+ * "did you mean", which is right there, and is told which help lists the commands of that level.
+ */
+function fromCommanderError(error, argv, program) {
     if (CLEAN_COMMANDER_CODES.has(error.code))
         return null;
     const message = error.message.replace(/^error:\s*/i, '');
+    if (error.code === 'commander.unknownCommand') {
+        const word = /^unknown command '([^']*)'/.exec(message)?.[1];
+        const first = firstCommandWord(argv);
+        if (word !== undefined && word === first) {
+            return usageError(message, unknownCommandHint(word, argv.slice(argv.indexOf(first) + 1)));
+        }
+        // Under `api` or `mcp`: Commander has said what is close; the hint says where the commands of that level are listed.
+        if (word !== undefined && program !== undefined) {
+            const where = ['widgetic', ...existingCommandPath(program, argv)].join(' ');
+            return usageError(message, `Run ${where} --help to see its commands.`);
+        }
+    }
     return usageError(message, 'Run the command with --help to see what it takes.');
 }
 export async function run(argv, environment) {
     const json = argv.includes('--json');
+    let program;
     try {
-        const program = buildProgram(environment, argv);
+        program = buildProgram(environment, argv);
         await program.parseAsync([...argv], { from: 'user' });
         return EXIT_CODES.ok;
     }
     catch (error) {
-        const failure = error instanceof CommanderError ? fromCommanderError(error) : asCliError(error, environment);
+        const failure = error instanceof CommanderError
+            ? fromCommanderError(error, argv, program)
+            : asCliError(error, environment);
         if (failure === null)
             return EXIT_CODES.ok;
         printError(environment, failure, json);

package/dist/commands/completion.js

@@ -121,6 +121,8 @@ export function completionsFor(build, words, current) {
 export function registerCompletionCommands(root, environment, build) {
     root
         .command('completion')
+        // The line the list of commands of `widgetic --help` shows; the shell lines are the help of `completion` itself.
+        .summary('Print the script that completes commands and flags with the Tab key.')
         .description('Print the script that completes widgetic commands and flags with the Tab key.\n\nbash: eval "$(widgetic completion bash)" in ~/.bashrc\nzsh:  eval "$(widgetic completion zsh)" in ~/.zshrc, after compinit\nfish: widgetic completion fish > ~/.config/fish/completions/widgetic.fish')
         .argument('<shell>', `One of: ${SHELLS.join(', ')}`)
         .action((shell) => {

package/dist/commands/doctor.js

@@ -283,6 +283,8 @@ async function runDoctor(environment, node) {
 export function registerDoctorCommand(root, environment) {
     const doctor = root
         .command('doctor')
+        // The line the list of commands of `widgetic --help` shows; the whole text is the help of `doctor` itself.
+        .summary('Check the install, the API key and both servers, and say what is wrong.')
         .description('Check the install and both servers: the CLI and its contracts, the API key, the REST API, and the MCP server (which tool contract it speaks and which tools it offers, compared with this CLI).\n\nExit code 0 when nothing failed, 1 when a check did; --json prints every check.');
     addBasicOptions(doctor, { server: true });
     doctor.action(async () => {

package/dist/commands/schema.js

@@ -183,6 +183,8 @@ export function unknownOperation(manifest, words) {
 export function registerSchemaCommand(root, environment) {
     const schema = root
         .command('schema')
+        // The line the list of commands of `widgetic --help` shows; the whole text is the help of `schema` itself.
+        .summary('Show everything one command takes, with the schema its input is checked against.')
         .description('Print the whole description of one command and the schema its input is checked against.\n\nIt is the cheap way to find out what a command takes, for a person and for an agent: one command, not the whole API.');
     const api = schema
         .command('api')

package/dist/constants.js

@@ -12,6 +12,12 @@ export const DEFAULT_PROFILE = 'default';
 export const PROFILE_NAME = /^[A-Za-z0-9._-]{1,64}$/;
 /** What a Widgetic API key looks like (`wgt_usr_…`, `wgt_prt_…`, `wdg_org_…`): used to warn about a value that is not one, never to refuse one. */
 export const API_KEY_SHAPE = /^(?:wgt_(?:adm|prt|usr)|wdg_org)_[A-Za-z0-9]{16,}$/;
+/**
+ * What a person is told to do about the API key: with none at all, to make one in the dashboard and give it to the CLI;
+ * with one the server does not accept, to give a working one. Both name where the keys are (Settings > API Keys).
+ */
+export const NO_KEY_HINT = 'Make an API key in the dashboard (Settings > API Keys), then run `widgetic auth login` with it, or set WIDGETIC_API_KEY.';
+export const KEY_REFUSED_HINT = 'Run `widgetic auth login` with a working API key (Settings > API Keys in the dashboard), or set WIDGETIC_API_KEY.';
 /** Seconds a call may take before the CLI gives up on it; `--timeout` changes it. */
 export const DEFAULT_TIMEOUT_SECONDS = 60;
 /**

package/dist/credentials.js

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { DEFAULT_PROFILE } from "./constants.js";
+import { DEFAULT_PROFILE, NO_KEY_HINT } from "./constants.js";
 import { CliError, EXIT_CODES } from "./errors.js";
 const FILE_NAME = 'credentials.json';
 function damaged(path, why) {
@@ -93,7 +93,7 @@ export function noApiKey(settings) {
             ? 'No API key.'
             : `No API key is saved for the profile "${settings.profile}".`,
         exitCode: EXIT_CODES.auth,
-        hint: 'Run `widgetic auth login` with an API key, or set WIDGETIC_API_KEY.'
+        hint: NO_KEY_HINT
     });
 }
 /** The key for a call that carries one, or the error that says how to get one (exit 3, nothing was sent). */

package/dist/help.js

@@ -0,0 +1,174 @@
+import { editDistance } from "./commands/schema.js";
+import { loadMcpManifest, loadRestManifest } from "./manifest/load.js";
+import { API_GROUP_SUMMARIES } from "./overlay.js";
+/**
+ * What the screens a new person meets first say beyond what the contracts say: the headings that sort the commands of
+ * `widgetic --help`, the "Get started" and "Examples" at the foot of `widgetic`, `widgetic api` and `widgetic mcp`, the
+ * line each group of the REST API gets, and what is said after a word that is no command.
+ *
+ * The commands themselves, their flags and their descriptions come from the contracts and are not here. Every command
+ * an example names is checked by `test/help.test.ts` (it exists, and so does every flag), so the help cannot send
+ * a person to a command that was renamed. The lines are short on purpose (78 characters at most): the text of a
+ * footer is printed as it is written, and a terminal that is 80 columns wide would break a longer one.
+ */
+/** The headings that sort the commands of `widgetic --help`: what you do with Widgetic, how you set it up, how you look things up. */
+export const ROOT_HEADINGS = {
+    work: 'Work with Widgetic:',
+    setup: 'Set up:',
+    lookup: 'Look things up:'
+};
+/** The dashboard, where an API key is made (Settings > API Keys): the address the documentation gives for it. */
+const DASHBOARD = 'app.widgetic.com';
+/** The first steps of a person who has just installed the CLI: the first is made in the dashboard, the rest are commands. */
+export const GET_STARTED_COMMANDS = [
+    { command: 'widgetic auth login', says: 'save it (it is asked for, and never shown)' },
+    { command: 'widgetic doctor', says: 'check that the key and both servers work' },
+    { command: 'widgetic mcp list-widgets', says: 'see your widgets' }
+];
+/** Commands that are safe to run to see what the CLI does: they read, or they only print the request. */
+export const ROOT_EXAMPLES = [
+    'widgetic mcp list-widgets',
+    'widgetic api widgets list --json',
+    'widgetic mcp create-widget --title Launch --brief "A countdown" --dry-run',
+    'widgetic schema mcp create-widget'
+];
+export const API_EXAMPLES = [
+    'widgetic api widgets list',
+    'widgetic api compositions list --size 5',
+    'widgetic api tokens validate-token'
+];
+export const MCP_EXAMPLES = [
+    'widgetic mcp list-widgets',
+    'widgetic mcp create-widget --title Launch --brief "A countdown" --wait',
+    'widgetic mcp create-widget --help'
+];
+/** A block of lines indented by two spaces, under a heading. */
+function section(heading, lines) {
+    return `${heading}\n${lines.map((line) => `  ${line}`).join('\n')}`;
+}
+/** The numbered steps of "Get started", with the sentence of each command aligned in a column. */
+function stepLines() {
+    const width = Math.max(...GET_STARTED_COMMANDS.map((step) => step.command.length));
+    return [
+        `1. Make an API key in the dashboard (Settings > API Keys, ${DASHBOARD}).`,
+        ...GET_STARTED_COMMANDS.map((step, index) => `${index + 2}. ${step.command.padEnd(width)}  ${step.says}`)
+    ];
+}
+/** What `widgetic --help` ends with. */
+export function rootHelpFooter() {
+    return [
+        '',
+        section('Get started:', stepLines()),
+        '',
+        section('Examples:', ROOT_EXAMPLES),
+        '',
+        'Add --json to get the result as one line of JSON, for scripts. Add --dry-run',
+        'to a command that calls the API to print the request and send nothing.',
+        'Add --help to any command to see what it takes.'
+    ].join('\n');
+}
+/** What `widgetic api --help` ends with. */
+export function apiHelpFooter() {
+    return [
+        '',
+        section('Examples:', API_EXAMPLES),
+        '',
+        'Run widgetic api <group> --help to list the commands of a group. A group',
+        'that needs a partner API key says so.'
+    ].join('\n');
+}
+/** What `widgetic mcp --help` ends with. */
+export function mcpHelpFooter() {
+    return [
+        '',
+        section('Examples:', MCP_EXAMPLES),
+        '',
+        'A command that builds a widget starts the build and answers at once; --wait',
+        'keeps asking until the build is finished and prints the finished widget.'
+    ].join('\n');
+}
+/** Every command of a group needs a partner API key (`wgt_prt_…`), so the group's line says so. */
+function needsPartnerKey(group) {
+    const listed = group.commands.filter((command) => !command.hidden);
+    return listed.length > 0 && listed.every((command) => command.accessLevel === 'partner');
+}
+/**
+ * The line a group of the REST API gets in the list of `widgetic api --help` and at the top of its own help: what it
+ * works on, from the overlay, and the kind of key it needs when that is always the partner's. A group the overlay does
+ * not know (a later contract added it) is listed by its name and its number of commands, which is true if not pretty.
+ */
+export function apiGroupSummary(group) {
+    const count = group.commands.length;
+    const written = API_GROUP_SUMMARIES[group.name] ?? `${group.title}: ${count} ${count === 1 ? 'command' : 'commands'}.`;
+    return needsPartnerKey(group) ? `${written.replace(/\.$/, '')} (needs a partner key).` : written;
+}
+/** A name without its separators or its case, so `list_widgets`, `list-widgets` and `ListWidgets` are one word. */
+const alphanumeric = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+/**
+ * The commands of `argv` that exist, from the program down: `api widgets` for `api widgets get`, where `get` is not a
+ * command of `widgets`. A word that is not a command (a flag's value, the unknown word itself) ends the walk, so what
+ * is returned is always a command the person can ask for `--help`.
+ */
+export function existingCommandPath(root, argv) {
+    let command = root;
+    const path = [];
+    for (const word of argv) {
+        if (word.startsWith('-'))
+            continue;
+        const next = command.commands.find((child) => child.name() === word || child.aliases().includes(word));
+        if (!next)
+            break;
+        command = next;
+        path.push(next.name());
+    }
+    return path;
+}
+/** The word of a command line that is the name of the command: the first one that is not a flag. */
+export function firstCommandWord(argv) {
+    return argv.find((word) => !word.startsWith('-'));
+}
+/**
+ * What to say after `widgetic <word>` when the word is no command of `widgetic`. People coming from other tools leave
+ * out the namespace (`widgetic widgets list`, `widgetic list-widgets`), so the word is looked for among the groups of
+ * the REST API and the tools of the MCP server, and a name that is close to one is offered. One line: the hint is
+ * printed on a single indented line.
+ */
+export function unknownCommandHint(word, rest = []) {
+    const fallback = 'Run widgetic --help to see the commands.';
+    try {
+        const groups = loadRestManifest().groups.filter((group) => !group.hidden);
+        const tools = loadMcpManifest().commands;
+        const typed = alphanumeric(word);
+        const group = groups.find((candidate) => alphanumeric(candidate.name) === typed);
+        if (group) {
+            // The words the person typed after the group, up to the first flag (`widgets list --id x` is `list`).
+            const following = [];
+            for (const next of rest) {
+                if (next.startsWith('-'))
+                    break;
+                following.push(next);
+            }
+            return `"${word}" is in the REST API: try widgetic api ${[group.name, ...following].join(' ')}`;
+        }
+        const tool = tools.find((candidate) => alphanumeric(candidate.name) === typed);
+        if (tool)
+            return `"${word}" is a tool of the MCP server: try widgetic mcp ${tool.name}`;
+        // Only names a typo away: a name that merely contains the word (`widget` is in a dozen tools) would bury the one meant.
+        const allowed = typed.length >= 5 ? 2 : 1;
+        const closeTo = (names) => names
+            .map((name) => ({ name, distance: editDistance(typed, alphanumeric(name)) }))
+            .filter((entry) => entry.distance <= allowed)
+            .sort((a, b) => a.distance - b.distance || a.name.localeCompare(b.name))
+            .map((entry) => entry.name);
+        const near = [
+            ...closeTo(groups.map((candidate) => candidate.name)).map((name) => `widgetic api ${name}`),
+            ...closeTo(tools.map((candidate) => candidate.name)).map((name) => `widgetic mcp ${name}`)
+        ].slice(0, 3);
+        if (near.length > 0)
+            return `Did you mean ${near.join(' or ')}? ${fallback}`;
+    }
+    catch {
+        // The manifests could not be read (a broken install): `widgetic doctor` says so; the hint is only a courtesy.
+    }
+    return fallback;
+}

package/dist/http.js

@@ -1,3 +1,4 @@
+import { KEY_REFUSED_HINT } from "./constants.js";
 import { CliError, EXIT_CODES, exitCodeForStatus } from "./errors.js";
 export function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -38,7 +39,6 @@ function upgradeHint(details) {
     // The gateway names the package of the client it recognised; for this CLI that is `@widgetic/cli`.
     return typeof command === 'string' ? `Update the CLI: ${command}` : undefined;
 }
-const NO_KEY_HINT = 'Run `widgetic auth login` with an API key, or set WIDGETIC_API_KEY.';
 /** The error an answer that was not a success stands for. */
 export function errorFromAnswer(answer, now, keySource) {
     const { status, headers, body } = answer;
@@ -69,7 +69,7 @@ export function errorFromAnswer(answer, now, keySource) {
         hint =
             keySource === 'environment'
                 ? 'The key in WIDGETIC_API_KEY was not accepted: check it, or unset it to use the saved one.'
-                : NO_KEY_HINT;
+                : KEY_REFUSED_HINT;
     }
     else if (status === 426) {
         hint = upgradeHint(details) ?? suggested;

package/dist/mcp/session.js

@@ -1,3 +1,4 @@
+import { KEY_REFUSED_HINT } from "../constants.js";
 import { CliError, EXIT_CODES, exitCodeForStatus } from "../errors.js";
 import { errorFromAnswer, isRecord, networkFailure, readAnswer } from "../http.js";
 import { cliVersion, identityHeaders } from "../version.js";
@@ -24,7 +25,7 @@ export function refusalOf(outcome) {
             code: 'AUTH_REQUIRED',
             message: outcome.text || 'The API key was not accepted.',
             exitCode: EXIT_CODES.auth,
-            hint: 'Run `widgetic auth login` with an API key, or set WIDGETIC_API_KEY.'
+            hint: KEY_REFUSED_HINT
         });
     }
     return new CliError({

package/dist/overlay.js

@@ -29,3 +29,27 @@ export const WAIT_OVERLAY = {
 export function isWaitTool(tool) {
     return WAIT_OVERLAY.tools.includes(tool);
 }
+/**
+ * The line `widgetic api --help` shows beside each group of the REST API. The contract names the groups (they are the
+ * tags of its operations) and says nothing about them, so without these lines the list would be thirteen bare nouns and
+ * a person could not tell `compositions` from `canvases`. Each line is written from what the operations of the group
+ * say about themselves; a group that has none yet (a later contract adds one) is listed with the number of its commands
+ * and `test/overlay.test.ts` fails until somebody writes its line.
+ */
+export const API_GROUP_SUMMARIES = {
+    'brand-kit': 'Your Brand Kit: the colors, fonts, icons, corner radius and notes for the AI that every new widget follows.',
+    canvases: 'The canvases that hold your widgets: create, list, read, update and delete them.',
+    compositions: 'What is made from a widget: its content, design, preview, versions, data and embed settings.',
+    credits: "An account's credit balance and credit ledger.",
+    entitlements: 'The entitlements of a partner and of its managed users.',
+    invoices: "A partner's invoices.",
+    'managed-users': "A partner's managed users: their limits, design defaults and editor sessions.",
+    operations: 'The status of work that goes on after the call that started it has answered.',
+    partners: 'A partner account: analytics, billing, presets, notifications, storage and data.',
+    'public-embed': 'What the browser of a visitor calls to show and run a published widget; it needs no API key. Left out of the list.',
+    tokens: 'Check that the API key in use is valid.',
+    uploads: 'Upload files, list and delete them, and see the upload limits.',
+    users: 'Your account: API keys, the websites that may show your widgets, and adapter connections.',
+    widgets: 'Your library of widgets: list and create them, and start a composition from one.',
+    workflows: 'Workflows: create, edit, publish, pause and archive them, and restore their versions.'
+};

package/dist/rest/register.js

@@ -1,7 +1,8 @@
 import { resolveSettings, timeoutMilliseconds } from "../config.js";
 import { confirmOrStop } from "../confirm.js";
 import { requireApiKey } from "../credentials.js";
-import { addCommonOptions, addFlag, commandHelp, readCommon, readFlags, shorten } from "../options.js";
+import { apiGroupSummary } from "../help.js";
+import { addCommonOptions, addFlag, commandHelp, readCommon, readFlags } from "../options.js";
 import { note, printResult } from "../output.js";
 import { retryNotifier } from "../retry.js";
 import { sendRestRequest } from "./execute.js";
@@ -125,14 +126,18 @@ function registerCommand(parent, group, command, run) {
         await runRestCommand(run, command, node, bindings);
     });
 }
-/** Adds the groups of the manifest, and their commands, under `api`. */
+/**
+ * Adds the groups of the manifest, and their commands, under `api`. A group is listed with the line of
+ * `apiGroupSummary` (what it works on, and the key it needs when that is a partner's), which is also the first line
+ * of its own help: the contract names the group and says nothing else about it.
+ */
 export function registerRestCommands(api, manifest, environment) {
     const run = { environment, manifest };
     for (const group of manifest.groups) {
         const node = api
             .command(group.name, { hidden: group.hidden })
-            .summary(group.title)
-            .description(shorten(group.description || group.title, 300));
+            .summary(apiGroupSummary(group))
+            .description(apiGroupSummary(group));
         for (const command of group.commands)
             registerCommand(node, group, command, run);
     }

package/generated/contracts.json

@@ -1 +1 @@
-{"package":"@widgetic/api-contracts","version":"1.11.109","publishTag":"latest","source":{"commit":"21238b5bbb97b100ef2edb0d9d98d167467e8d18","branch":null,"dirty":false,"atOriginMain":true},"openApi":{"file":"openapi-public.json","sha256":"750e774e958a819377963d0a6f7a2feb2e7b70327b614053fdbe748e3e5e5865","paths":120,"operations":161,"servers":["https://api.widgetic.com/v1"]},"mcp":{"file":"mcp-tools.json","sha256":"9d6494d8d1d227e1752a170339d63853b52770812e9283cda2ca66981edd72c6","contractVersion":"1.12.0","serverName":"widgetic","tools":32}}
+{"package":"@widgetic/api-contracts","version":"1.11.111","publishTag":"latest","source":{"commit":"fa75adf8384a27c620fb9d0d99b65db4f25ca7b5","branch":null,"dirty":false,"atOriginMain":true},"openApi":{"file":"openapi-public.json","sha256":"f268893f66578ba4099660fb42b4f8f1c3c56bc0672f1190b4bb12b905f34e6c","paths":124,"operations":169,"servers":["https://api.widgetic.com/v1"]},"mcp":{"file":"mcp-tools.json","sha256":"e6ca36563883e9d31597f201bcc0276babede3b901310558d291bff349ddbae3","contractVersion":"1.14.0","serverName":"widgetic","tools":34}}