feat(find): hint for --task and --ai-model when a find leaves them out (v2.8.0)

README.md

@@ -269,6 +269,7 @@ one actions find shopify "list products" -t knowledge
 - **`--task`** describes the whole job in one line, in general terms. Agents are asked to send it with every find, since it helps tell similar actions apart.
 - **`-t knowledge`** searches the catalog for writing code and building flows and relays, which includes the platform's own (passthrough) endpoints; the default is the catalog for running actions now.
 - **`--ai-model`** names the model running the CLI (e.g. `claude-sonnet-5`), recorded with the find beside the CLI and the harness that launched it, so the account's usage can report which model asked. Agents are asked to send it with every find.
+- An answer to a find without `--task` or `--ai-model` carries a `hint` field (a dim line for humans) asking for them on the next find. Both stay optional.
 - **`--no-knowledge`** lists the chosen actions (actionId, title, method, path) without fetching their documentation; load it later with `one actions load <actionId>`.
 
 Each intent's answer gives the action(s) to use with their docs, any actions also needed beside them, a **substitute** when the model was unsure (use one or the other, never both), and a few alternatives, then says once how to execute. Always read the docs before executing. The access settings from `one config` apply: an action they refuse is never offered.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/cli",
-  "version": "2.7.1",
+  "version": "2.8.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [

skills/one/SKILL.md

@@ -85,6 +85,7 @@ one --agent actions find <platform> "<intent>" [<platform> "<intent>" ...] --tas
 - **`--task`**: send it with every find. It is the whole job in one line, **in general terms**: `"email a weather report to a contact"`, without names, addresses, IDs, or message text. It helps tell similar actions apart.
 - **`-t knowledge`** searches the catalog for writing code and building flows and relays (it includes the platform's own passthrough endpoints); the default, `-t execute`, is the catalog for running actions now.
 - **`--ai-model`**: send it with every find. Your model name as you know it (e.g. `claude-sonnet-5`), recorded with the find; leave it out only if you do not know which model you are.
+- A find answer sent without either carries a **`hint`** naming what was missing: add it on your next find.
 - **`--no-knowledge`** (optional): list the chosen actions without their documentation, when you only need the actionIds. Load the documentation with `actions load` before executing.
 - Platform names are lowercase; multi-word names use dashes: `gmail`, `hubspot`, `ship-station`, `google-calendar`.
 

src/commands/actions.ts

@@ -13,6 +13,7 @@ import {
   type FindDeps,
   type FindSettings,
   type LoadOptions,
+  findHint,
 } from '../lib/find.js';
 import { knowledgeCachePath, readCache, isFresh, getAge, formatAge } from '../lib/cache.js';
 
@@ -107,13 +108,15 @@ export async function actionsFindCommand(pairs: string[], options: ActionsFindOp
       { knowledgeCatalog: options.type === 'knowledge', knowledge: options.knowledge !== false }
     );
 
+    const hint = findHint(options.task, options.aiModel);
     if (output.isAgentMode()) {
-      output.json(result);
+      output.json(hint ? { ...result, hint } : result);
       return;
     }
     spinner.stop('Found');
     console.log();
     console.log(renderFind(result));
+    if (hint) console.log(`\n${pc.dim(hint)}`);
     console.log();
   } catch (error) {
     spinner.stop('Find failed');

src/lib/find.test.ts

@@ -6,6 +6,7 @@ import {
   FindArgsError,
   REFUSED_LOAD,
   find,
+  findHint,
   load,
   renderFind,
   type DocumentedAction,
@@ -286,3 +287,32 @@ describe('actions load', () => {
     assert.equal((result.loaded[1] as DocumentedAction).knowledge, huge);
   });
 });
+
+describe('find hint', () => {
+  it('asks for the task and the model when a find carries neither', () => {
+    const hint = findHint(undefined, undefined);
+    assert.ok(hint);
+    assert.match(hint, /--task/);
+    assert.match(hint, /--ai-model/);
+  });
+
+  it('names only what is missing', () => {
+    const noTask = findHint(undefined, 'claude-sonnet-5');
+    assert.ok(noTask);
+    assert.match(noTask, /--task/);
+    assert.doesNotMatch(noTask, /--ai-model/);
+
+    const noModel = findHint('email a report to a contact', undefined);
+    assert.ok(noModel);
+    assert.match(noModel, /--ai-model/);
+    assert.doesNotMatch(noModel, /--task/);
+  });
+
+  it('treats a blank value as missing', () => {
+    assert.match(findHint('   ', 'claude-sonnet-5') ?? '', /--task/);
+  });
+
+  it('says nothing when both were sent', () => {
+    assert.equal(findHint('email a report to a contact', 'claude-sonnet-5'), undefined);
+  });
+});

src/lib/find.ts

@@ -110,6 +110,24 @@ export interface FindResult {
   answers: FindAnswer[];
   /** What applies to every documented action, stated once: how to execute, or the code guide's rules. */
   guide?: string;
+  /** Set when the find came without `--task` or `--ai-model`: asks for them on the next find (see {@link findHint}). */
+  hint?: string;
+}
+
+/**
+ * What a find should have carried, said back to the agent in its answer: the
+ * task (it helps tell similar actions apart) and the model (recorded with the
+ * find). Agents that never read the skill still read the answer, so this is
+ * where the ask reaches them. Undefined when both were sent; a blank value
+ * counts as missing. Never blocks a find: both stay optional.
+ */
+export function findHint(task?: string, aiModel?: string): string | undefined {
+  const missing = [
+    task?.trim() ? null : '--task "<the whole job in one line, in general terms, without names, addresses, IDs or message text>"',
+    aiModel?.trim() ? null : '--ai-model "<your model name>"',
+  ].filter((m): m is string => m !== null);
+  if (missing.length === 0) return undefined;
+  return `Send ${missing.join(' and ')} with every find: the task helps tell similar actions apart, and both are recorded with the find.`;
 }
 
 /** One `actions load` entry's outcome. */

src/lib/guide-content.ts

@@ -183,6 +183,7 @@ One call for the whole task: one platform and intent pair per operation, on any
 - **\`--task\`**: send it with every find. It is the whole job in one line, **in general terms**: what it does, without names, addresses, IDs, or message text. It helps tell similar actions apart.
 - **\`-t knowledge\`** searches the catalog for writing code and building flows and relays, which includes the platform's own (passthrough) endpoints; the default, \`-t execute\`, is the catalog for running actions now. Knowledge-only mode always uses \`knowledge\`.
 - **\`--ai-model\`**: send it with every find. Your model name as you know it (e.g. \`claude-sonnet-5\`), recorded with the find; leave it out only if you do not know which model you are.
+- A find answer sent without either carries a **\`hint\`** naming what was missing: add it on your next find.
 - **\`--no-knowledge\`** (optional) lists the chosen actions without their documentation, when only the actionIds are needed. Load the documentation with \`actions load\` before executing.
 
 In \`--agent\` mode: