fix(prompts): reduce recipe citations to topic names when mechanics are off

route's final step, failure fallback and See Also named a recipe as a
command to fetch, so a mechanics: false render still carried CLI
invocations. Step 8 is now a whole-step substitution that names the
destination by topic, and citations go through %(RECIPE_FETCH)s, which
renders nothing with mechanics off. The default render is byte-identical.

Author: theCodeDrift

.changeset/prompts-host-invocation-marker.md

@@ -3,3 +3,5 @@
 ---
 
 `@taskless/cli/prompts` now renders the `<taskless-cli>` marker when the caller passes no `invocation`, on every build. A nightly used to substitute its own `npx @taskless/cli-nightly@<version>` into the recipe body, so `getPrompt(topic, { header: false })` still carried a CLI version and the rendered text changed on every nightly. Pass `invocation` to name a launcher of your own. `taskless agent <topic>` is unchanged and still names the build it was run from.
+
+`mechanics: false` now also covers the passages that name a recipe as a command to fetch. In `route`, the final step names the destination by its topic name (`create-vale-rule`) rather than by its fetch command, and the failure fallback and `See Also` cite topic names, so the render carries no CLI invocation at all. The default rendering is unchanged.

packages/cli/src/agent/route.md

@@ -241,13 +241,7 @@ answered together.
    Not logged in, no GitHub owner, or not locally expressible are not
    choices. Do not pose them as one.
 
-8. **Name the command.** Finish by telling the user, or running, the
-   exact fetch for the destination you chose:
-   ```
-   %(TASKLESS_CLI)s agent create-vale-rule
-   ```
-   A destination that is not a runnable command is a category, and a
-   category is not an answer.
+8. %(NAME_DESTINATION)s
 
 ## When two destinations both fit
 
@@ -270,7 +264,7 @@ fails against the user's cases:
 - State that generating via the service uses a generation and requires
   login.
 - Call the service only after the user confirms. On yes, fetch
-  `%(TASKLESS_CLI)s agent create-remote-rule`.
+  `%(RECIPE_FETCH)screate-remote-rule`.
 
 Never fall through silently from a failed local attempt to a service
 call. A developer who watches a local attempt fail reads it as a
@@ -304,9 +298,9 @@ will work.
 
 ## See Also
 
-- `%(TASKLESS_CLI)s agent create-legacy-rule`: author in a linter the repo already uses
-- `%(TASKLESS_CLI)s agent create-sg-rule`: author a local ast-grep rule (no login)
-- `%(TASKLESS_CLI)s agent create-vale-rule`: author a local Vale rule (no login)
-- `%(TASKLESS_CLI)s agent create-runtime-rule`: the runtime tier, logged out
-- `%(TASKLESS_CLI)s agent create-remote-rule`: generate via the service (login)
-- `%(TASKLESS_CLI)s agent check`: run every engine over the repo
+- `%(RECIPE_FETCH)screate-legacy-rule`: author in a linter the repo already uses
+- `%(RECIPE_FETCH)screate-sg-rule`: author a local ast-grep rule (no login)
+- `%(RECIPE_FETCH)screate-vale-rule`: author a local Vale rule (no login)
+- `%(RECIPE_FETCH)screate-runtime-rule`: the runtime tier, logged out
+- `%(RECIPE_FETCH)screate-remote-rule`: generate via the service (login)
+- `%(RECIPE_FETCH)scheck`: run every engine over the repo

packages/cli/src/prompts/recipes.ts

@@ -191,10 +191,13 @@ export interface RecipeOptions {
    */
   invocation?: string;
   /**
-   * Render the steps that gather evidence by running this CLI.
+   * Render the steps that gather evidence by running this CLI, and the
+   * passages that name a recipe as a command to fetch.
    *
-   * `false` replaces them with a statement of what the caller must supply
-   * instead. It exists because `invocation` cannot do this job: that option
+   * `false` replaces the evidence steps with a statement of what the caller
+   * must supply instead, and reduces a recipe citation to its topic name: the
+   * route's final step names the destination rather than its fetch command,
+   * and `See Also` lists topics rather than invocations. It exists because `invocation` cannot do this job: that option
    * substitutes the BINARY NAME inside a command, so a consumer with no CLI
    * setting it to a phrase renders `Run: <no CLI available> detect --json` — a
    * malformed instruction rather than a clean absence, and worse than either
@@ -296,6 +299,33 @@ function runBlock(
   return `Run:\n   \`\`\`\n   ${invocation} ${command}\n   \`\`\`\n   ${connective}`;
 }
 
+/**
+ * The route recipe's final step, as a whole numbered step including its title.
+ *
+ * The title is inside the substitution for the reason {@link hostToolsStep}
+ * gives: "Name the command" is the part that is wrong for a caller with no
+ * terminal, where the answer is the destination's topic name and a command
+ * would be one more thing to strip back out (taskless/cli#469).
+ */
+function nameDestinationStep(invocation: string | undefined): string {
+  if (invocation === undefined) {
+    return `**Name the destination.** Finish with the topic name of the
+recipe that authors this rule:
+\`\`\`
+create-vale-rule
+\`\`\`
+A destination that is not one of the topic names above is a category,
+and a category is not an answer.`;
+  }
+  return `**Name the command.** Finish by telling the user, or running, the
+exact fetch for the destination you chose:
+\`\`\`
+${invocation} agent create-vale-rule
+\`\`\`
+A destination that is not a runnable command is a category, and a
+category is not an answer.`;
+}
+
 /**
  * Indent every line after the first, so a multi-line block substituted into an
  * indented `%(KEY)s` is still the markdown unit it replaces.
@@ -493,6 +523,18 @@ export function buildVariables(
       options.mechanics === false
         ? SUPPLIED_LOGIN
         : runBlock(resolveInvocation(options), "info --json", "and note"),
+    // A recipe named as something to fetch. Written against the topic name in
+    // the source (`%(RECIPE_FETCH)screate-sg-rule`), so with mechanics off the
+    // citation reduces to the name itself rather than to a command whose
+    // binary the caller does not have.
+    RECIPE_FETCH:
+      options.mechanics === false ? "" : `${resolveInvocation(options)} agent `,
+    NAME_DESTINATION: indentBlock(
+      nameDestinationStep(
+        options.mechanics === false ? undefined : resolveInvocation(options)
+      ),
+      "   "
+    ),
     // Three steps, in descending order of how much the resolver actually
     // knows: the caller was told how the CLI was launched; the build is a
     // nightly/dev/self that knows what it is; nobody knows, so ask the agent.

packages/cli/test/prompts.test.ts

@@ -185,7 +185,9 @@ describe("the CLI invocation variable", () => {
       "DETECT_EVIDENCE",
       "HOST_TOOLS",
       "LOGIN_EVIDENCE",
+      "NAME_DESTINATION",
       "PACKAGE_MANAGER_DLX",
+      "RECIPE_FETCH",
       "SOURCE_PR_REVIEW",
       "TASKLESS_CLI",
       "VALE_COMMENT_FORMATS",
@@ -382,6 +384,31 @@ describe("host mechanics suppression", () => {
     );
   });
 
+  it("names the destination by topic rather than by command", () => {
+    // taskless/cli#469. Step 8, the failure fallback and See Also all named a
+    // recipe as a command to fetch, so a caller with no terminal still got
+    // invocations after asking for none. The citation reduces to the topic
+    // name, which is the answer the step asks for.
+    const rendered = getPrompt("route", { mechanics: false });
+    expect(rendered).toContain("**Name the destination.**");
+    expect(rendered).not.toContain("**Name the command.**");
+    expect(rendered).toMatch(/```\n {3}create-vale-rule\n {3}```/);
+    expect(rendered).toContain("- `create-sg-rule`: author a local ast-grep");
+    expect(rendered).toContain("On yes, fetch\n  `create-remote-rule`.");
+    expect(rendered).not.toContain("<taskless-cli>");
+    expect(rendered).not.toContain(" agent create-");
+  });
+
+  it("still renders every recipe citation as a command by default", () => {
+    const rendered = getPrompt("route", { invocation: "npx @taskless/cli" });
+    expect(rendered).toContain("**Name the command.**");
+    expect(rendered).toContain("   npx @taskless/cli agent create-vale-rule\n");
+    expect(rendered).toContain(
+      "- `npx @taskless/cli agent create-sg-rule`: author a local ast-grep"
+    );
+    expect(rendered).toContain("`npx @taskless/cli agent create-remote-rule`.");
+  });
+
   it("keeps the evidence itself, since the criteria are stated in terms of it", () => {
     // Dropping the steps entirely would lose the inputs, not just the
     // commands: the prose below each step describes what the evidence holds.