@canonical/pragma-cli 0.32.0 → 0.33.0

package/src/capabilities/tier/lookup.render.ts

@@ -2,6 +2,8 @@
  * Formatters + data shape for `tier lookup <name>`.
  */
 
+import type { RenderLookupOptions } from "../../kernel/render/contracts.js";
+import { renderLookupPlain } from "../../kernel/render/renderers.js";
 import type { Formatters } from "../../kernel/spec/types.js";
 
 /** The looked-up tier: its IRI, name, and the blocks scoped directly to it. */
@@ -11,18 +13,41 @@ export interface TierLookupData {
   readonly blocks: readonly string[];
 }
 
+/**
+ * The shared plain-lookup layout for a tier: a `name (uri)` title over an ═ rule,
+ * then the directly-scoped blocks as one inline field. Delegating to
+ * {@link renderLookupPlain} single-sources the frame AND the TTY styling (bold
+ * title, dim rule, cyan label) that block/skill lookups already earn — so a tier
+ * title no longer stays unstyled on a terminal while theirs are bold (B7).
+ */
+const tierPlainOptions: RenderLookupOptions<TierLookupData> = {
+  title: (tier) => `${tier.name} (${tier.uri})`,
+  fields: [
+    {
+      label: "blocks",
+      // Pre-joined so the empty case still renders (the shared field renderer
+      // skips an empty array). Blocks are `ds:name` display strings, never IRIs,
+      // so the shared renderer's URI compaction is a no-op here — byte-stable.
+      value: (tier) =>
+        tier.blocks.length > 0
+          ? tier.blocks.join(", ")
+          : "(none scoped directly to this tier)",
+    },
+  ],
+  sections: [],
+};
+
 export const tierLookupFormatters: Formatters<TierLookupData> = {
   plain(data) {
-    const lines = [`${data.name} (${data.uri})`];
-    lines.push(
-      data.blocks.length > 0
-        ? `  blocks: ${data.blocks.join(", ")}`
-        : "  blocks: (none scoped directly to this tier)",
-    );
-    return lines.join("\n");
+    return renderLookupPlain(data, tierPlainOptions);
   },
   llm(data) {
-    const lines = [`# ${data.name}`, `- IRI: \`${data.uri}\``];
+    // A byte-frozen agent contract that DIVERGES from the generic
+    // `renderLookupLlm`: an H2 `name` title (not `name (uri)`) with the IRI and
+    // blocks backtick-wrapped (`\`cs:…\``) — a shape the shared renderer does not
+    // emit. The llm path is never styled, so it has no TTY drift to single-source;
+    // kept inline so the frozen bytes hold (B2).
+    const lines = [`## ${data.name}`, `- IRI: \`${data.uri}\``];
     if (data.blocks.length > 0) {
       lines.push(`- Blocks: ${data.blocks.map((b) => `\`${b}\``).join(", ")}`);
     }

package/src/capabilities/tier/lookup.test.ts

@@ -39,6 +39,21 @@ describe("tier_lookup — bespoke single-name lookup (PROTECTED)", () => {
     const error = result.error as { code: string };
     expect(error.code).toBe("ENTITY_NOT_FOUND");
   });
+
+  it("suggests a near-miss tier name from the full list (did-you-mean parity)", async () => {
+    // B6: tier lookup was the only entity lookup that omitted suggestions,
+    // though — like the others — it can read the full tier list on a miss.
+    let caught: unknown;
+    try {
+      await runTierLookup(fixture.runtime, "apps/lxdd");
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: "ENTITY_NOT_FOUND" });
+    expect((caught as { suggestions: string[] }).suggestions).toContain(
+      "apps/lxd",
+    );
+  });
 });
 
 describe("tier_lookup — cold/unseeded store (ROOT A)", () => {

package/src/capabilities/tier/runLookup.ts

@@ -9,11 +9,34 @@
 
 import { PragmaError } from "../../kernel/error/PragmaError.js";
 import { runSelect } from "../../kernel/packs/sparql/runSelect.js";
+import { suggestNames } from "../../kernel/project/cli/suggestNames.js";
 import { compactUri } from "../../kernel/render/compactUri.js";
 import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import type { TierLookupData } from "./lookup.render.js";
 
+/**
+ * Read every tier name in the store (its `ds:name`), ordered.
+ *
+ * The bespoke lookup already holds the machinery to reach the store, so a
+ * name-not-found can rank "did you mean?" candidates the same way every other
+ * entity lookup does — the tier list is a single cheap SELECT away.
+ *
+ * @param rt - The runtime (its store is booted by the projector for needsStore).
+ * @returns The tier names, ordered.
+ * @note Impure — queries the store through `runSelect`.
+ */
+async function selectTierNames(rt: PragmaRuntime): Promise<string[]> {
+  const rows = await runSelect(
+    rt,
+    "SELECT ?name WHERE { ?tier a ds:Tier ; ds:name ?name } ORDER BY ?name",
+    "tier",
+  );
+  return rows
+    .map((row) => row.name as string | undefined)
+    .filter((name): name is string => Boolean(name));
+}
+
 /**
  * Look up one tier by name.
  *
@@ -43,7 +66,12 @@ export async function runTierLookup(
   const rows = await runSelect(rt, query, "tier");
   const uri = rows[0]?.uri;
   if (!uri) {
+    // Rank "did you mean?" candidates from the full tier list — the only entity
+    // lookup that used to omit suggestions, though (like the others) it has the
+    // names in hand. The suggestion query runs only on this cold, not-found path.
+    const suggestions = suggestNames(name, await selectTierNames(rt));
     throw PragmaError.notFound("tier", name, {
+      suggestions,
       recovery: {
         message: "List available tiers.",
         cli: "pragma tier list",

package/src/constants.test.ts

@@ -25,7 +25,7 @@ describe("constants", () => {
   });
 
   it("exposes the stable output formats and detail levels", () => {
-    expect(OUTPUT_FORMATS).toEqual(["plain", "json"]);
+    expect(OUTPUT_FORMATS).toEqual(["plain", "llm", "json"]);
     expect(DETAIL_LEVELS).toEqual(["summary", "standard", "detailed"]);
     expect(DETAIL_LEVELS).toContain(DEFAULT_DETAIL_LEVEL);
     expect(PROGRAM_DESCRIPTION.length).toBeGreaterThan(0);

package/src/constants.ts

@@ -31,8 +31,8 @@ const VERSION: string = pkg.version;
  */
 const RECOVERY_CLI_PREFIX = "pragma ";
 
-/** The two machine/human output formats the renderer selects between. */
-const OUTPUT_FORMATS = ["plain", "json"] as const;
+/** The output formats the renderer selects between (`llm` = condensed Markdown). */
+const OUTPUT_FORMATS = ["plain", "llm", "json"] as const;
 
 /** A selected output format. `--format text` is normalised to `plain`. */
 type OutputFormat = (typeof OUTPUT_FORMATS)[number];

package/src/kernel/completion/__snapshots__/emitScripts.test.ts.snap

@@ -58,21 +58,21 @@ _pragma() {
     block/list/--tags) return ;;
   esac
   case "$prev" in
-    --format) COMPREPLY=($(compgen -W "plain json" -- "$cur")); return ;;
+    --format) COMPREPLY=($(compgen -W "plain llm json" -- "$cur")); return ;;
     --detail) COMPREPLY=($(compgen -W "summary standard detailed" -- "$cur")); return ;;
   esac
 
   # flag names
   if [[ "$cur" == -* ]]; then
     case "$noun/$verb" in
-      block/get) COMPREPLY=($(compgen -W "--view --out --with-meta --note --llm --format --verbose --detail --help" -- "$cur")); return ;;
-      block/list) COMPREPLY=($(compgen -W "--tags --llm --format --verbose --detail --help" -- "$cur")); return ;;
-      block/remove) COMPREPLY=($(compgen -W "--dry-run --undo --yes --llm --format --verbose --detail --help" -- "$cur")); return ;;
+      block/get) COMPREPLY=($(compgen -W "--view --out --with-meta --note --format --verbose --detail --help" -- "$cur")); return ;;
+      block/list) COMPREPLY=($(compgen -W "--tags --format --verbose --detail --help" -- "$cur")); return ;;
+      block/remove) COMPREPLY=($(compgen -W "--dry-run --undo --yes --format --verbose --detail --help" -- "$cur")); return ;;
     esac
     if [ -z "$noun" ]; then
-      COMPREPLY=($(compgen -W "--llm --format --verbose --detail --help --version" -- "$cur"))
+      COMPREPLY=($(compgen -W "--format --verbose --detail --help --version" -- "$cur"))
     else
-      COMPREPLY=($(compgen -W "--llm --format --verbose --detail --help" -- "$cur"))
+      COMPREPLY=($(compgen -W "--format --verbose --detail --help" -- "$cur"))
     fi
     return
   fi
@@ -172,8 +172,7 @@ complete -c pragma -f
 complete -c pragma -n "__pragma_at ''" -a "block mcp standard status"
 
 # global flags
-complete -c pragma -l llm
-complete -c pragma -l format -x -a "plain json"
+complete -c pragma -l format -x -a "plain llm json"
 complete -c pragma -l verbose
 complete -c pragma -l detail -x -a "summary standard detailed"
 complete -c pragma -l help
@@ -268,21 +267,21 @@ _pragma() {
     block/list/--tags) return 0 ;;
   esac
   case "$prev" in
-    --format) compadd -- plain json; return 0 ;;
+    --format) compadd -- plain llm json; return 0 ;;
     --detail) compadd -- summary standard detailed; return 0 ;;
   esac
 
   # flag names
   if [[ "$cur" == -* ]]; then
     case "$noun/$verb" in
-      block/get) compadd -- --view --out --with-meta --note --llm --format --verbose --detail --help; return 0 ;;
-      block/list) compadd -- --tags --llm --format --verbose --detail --help; return 0 ;;
-      block/remove) compadd -- --dry-run --undo --yes --llm --format --verbose --detail --help; return 0 ;;
+      block/get) compadd -- --view --out --with-meta --note --format --verbose --detail --help; return 0 ;;
+      block/list) compadd -- --tags --format --verbose --detail --help; return 0 ;;
+      block/remove) compadd -- --dry-run --undo --yes --format --verbose --detail --help; return 0 ;;
     esac
     if [[ -z "$noun" ]]; then
-      compadd -- --llm --format --verbose --detail --help --version
+      compadd -- --format --verbose --detail --help --version
     else
-      compadd -- --llm --format --verbose --detail --help
+      compadd -- --format --verbose --detail --help
     fi
     return 0
   fi

package/src/kernel/completion/bashDrive.test.ts

@@ -51,7 +51,7 @@ describe.skipIf(!bashOk)("generated bash — --flag=value wordbreak (M1)", () =>
   it("routes --format=<TAB> to the format values (not nouns/positionals)", () => {
     // Default COMP_WORDBREAKS split: `--format` `=` `` (empty current word).
     const reply = driveBash(["pragma", "--format", "=", ""], 3);
-    expect(reply.sort()).toEqual(["json", "plain"]);
+    expect(reply.sort()).toEqual(["json", "llm", "plain"]);
   });
 
   it("filters the value by the partial typed after =", () => {
@@ -63,11 +63,11 @@ describe.skipIf(!bashOk)("generated bash — --flag=value wordbreak (M1)", () =>
     // After a noun/verb the value must still route as a flag value, never as
     // block's positional (which would offer entity/enum candidates instead).
     const reply = driveBash(["pragma", "block", "get", "--format", "=", ""], 5);
-    expect(reply.sort()).toEqual(["json", "plain"]);
+    expect(reply.sort()).toEqual(["json", "llm", "plain"]);
   });
 
   it("still completes the space form --format <TAB> (unbroken)", () => {
     const reply = driveBash(["pragma", "--format", ""], 2);
-    expect(reply.sort()).toEqual(["json", "plain"]);
+    expect(reply.sort()).toEqual(["json", "llm", "plain"]);
   });
 });

package/src/kernel/completion/complete.test.ts

@@ -19,16 +19,14 @@ describe("runComplete — the __complete pipeline", () => {
       "config",
     ]);
     // The live `config` sub-verbs, prefix-filtered and sorted by the resolver.
+    // AV-228 B3 retired the per-field tier/channel/detail verbs, leaving set + show.
     await expect(runComplete(["config", ""], capabilities)).resolves.toEqual([
-      "channel",
-      "detail",
       "set",
       "show",
-      "tier",
     ]);
     await expect(runComplete(["mc"], capabilities)).resolves.toEqual(["mcp"]);
-    await expect(runComplete(["--l"], capabilities)).resolves.toEqual([
-      "--llm",
+    await expect(runComplete(["--d"], capabilities)).resolves.toEqual([
+      "--detail",
     ]);
   });
 

package/src/kernel/completion/entitySource.ts

@@ -98,18 +98,26 @@ export function readPackIndex(cwd: string): PackIndex | undefined {
 }
 
 /**
- * Sum a pack index's per-type instance counts — the "total entities" figure
+ * Count a pack index's DISTINCT abox subjects — the "total entities" figure
  * `info` and `doctor` report. Works over any {@link PackIndex}, whether read
  * storelessly via {@link readPackIndex} or taken from a booted store session.
  *
+ * NOT a sum of `instanceCountByType`: on a real OWL/Protégé export that raw
+ * multiset double-counts — every individual is typed as both its domain class
+ * AND `owl:NamedIndividual`, and the `owl:Class`/property meta-buckets pile on
+ * top — so the total ran ~2× the real entity count (A1). Counting distinct
+ * abox subjects (the individuals, each once) is the figure users expect; the
+ * tbox schema classes/properties are not "entities" in this count.
+ *
  * @param index - A pack index.
- * @returns The total number of indexed entity instances across every type.
+ * @returns The number of distinct abox subjects indexed.
  */
 export function entityTotal(index: PackIndex): number {
-  return Object.values(index.instanceCountByType).reduce(
-    (sum, n) => sum + n,
-    0,
-  );
+  const subjects = new Set<string>();
+  for (const entity of index.entities) {
+    if (entity.box === "abox") subjects.add(entity.uri ?? entity.name);
+  }
+  return subjects.size;
 }
 
 /** Load the active pack's index: the locked pack, else the embedded fallback. */

package/src/kernel/completion/model.test.ts

@@ -264,13 +264,13 @@ describe("buildCompletionModel — flags and sources", () => {
     const flags = Object.fromEntries(model.globalFlags.map((f) => [f.flag, f]));
     expect(flags["--format"]?.source).toEqual({
       kind: "values",
-      values: ["plain", "json"],
+      values: ["plain", "llm", "json"],
     });
     expect(flags["--detail"]?.source).toEqual({
       kind: "values",
       values: ["summary", "standard", "detailed"],
     });
-    expect(flags["--llm"]?.takesValue).toBe(false);
+    expect(flags["--llm"]).toBeUndefined();
     expect(flags["--version"]?.rootOnly).toBe(true);
     expect(flags["--help"]?.rootOnly).toBeUndefined();
   });

package/src/kernel/completion/model.ts

@@ -61,7 +61,6 @@ export function assertSafeToken(token: string, where: string): void {
 
 /** The global flags completion offers, mirroring the surface's globalFlags. */
 const GLOBAL_FLAGS: readonly FlagEntry[] = [
-  { flag: "--llm", takesValue: false, repeatable: false, source: none() },
   {
     flag: "--format",
     takesValue: true,

package/src/kernel/completion/parse.test.ts

@@ -73,7 +73,7 @@ describe("parseWords — nouns and verbs (PROTECTED)", () => {
       context: { kind: "noun" },
       partial: "blo",
     });
-    expect(parse(["--llm", "block", ""]).context).toEqual({
+    expect(parse(["--verbose", "block", ""]).context).toEqual({
       kind: "verb",
       noun: "block",
     });
@@ -83,7 +83,6 @@ describe("parseWords — nouns and verbs (PROTECTED)", () => {
 describe("parseWords — flag names (PROTECTED)", () => {
   it("offers only globals (with --version) at the root", () => {
     expect(flagsOf(parse(["--"]).context)).toEqual([
-      "--llm",
       "--format",
       "--verbose",
       "--detail",
@@ -105,7 +104,6 @@ describe("parseWords — flag names (PROTECTED)", () => {
       "--out",
       "--with-meta",
       "--note",
-      "--llm",
       "--format",
       "--verbose",
       "--detail",
@@ -192,7 +190,7 @@ describe("parseWords — flag values (PROTECTED)", () => {
       context: {
         kind: "flag-value",
         flag: "--format",
-        source: { kind: "values", values: ["plain", "json"] },
+        source: { kind: "values", values: ["plain", "llm", "json"] },
       },
     });
     expect(parse(["block", "get", "--detail", "s"])).toMatchObject({

package/src/kernel/error/PragmaError.test.ts

@@ -26,10 +26,10 @@ describe("PragmaError factories", () => {
 
   it("invalidInput enumerates valid options", () => {
     const error = PragmaError.invalidInput("format", "yaml", {
-      validOptions: ["plain", "json"],
+      validOptions: ["plain", "llm", "json"],
     });
     expect(error.code).toBe("INVALID_INPUT");
-    expect(error.validOptions).toEqual(["plain", "json"]);
+    expect(error.validOptions).toEqual(["plain", "llm", "json"]);
   });
 
   it("unknownVerb names the token", () => {
@@ -105,14 +105,14 @@ describe("envelope builders", () => {
 
   it("wraps an error into the failure envelope", () => {
     const error = PragmaError.invalidInput("format", "yaml", {
-      validOptions: ["plain", "json"],
+      validOptions: ["plain", "llm", "json"],
     });
     expect(errorEnvelope(error)).toEqual({
       ok: false,
       error: {
         code: "INVALID_INPUT",
         message: 'Invalid format "yaml".',
-        validOptions: ["plain", "json"],
+        validOptions: ["plain", "llm", "json"],
       },
     });
   });

package/src/kernel/error/renderError.ts

@@ -2,7 +2,7 @@
  * Render a {@link PragmaError} for each output surface.
  *
  * Plain text targets a human terminal (stderr), condensed Markdown targets an
- * agent reading `--llm`, and JSON emits the `{ ok: false, error }` envelope —
+ * agent reading `--format llm`, and JSON emits the `{ ok: false, error }` envelope —
  * the same failure shape the MCP projector returns, so agents see one contract
  * whichever transport they use.
  */

package/src/kernel/packs/compile.ts

@@ -145,7 +145,7 @@ function compileListVerb(shape: PackList, meta: ListVerbMeta): VerbSpec {
             },
           ]
         : []),
-      { cmd: `pragma ${meta.noun} ${meta.verb} --llm` },
+      { cmd: `pragma ${meta.noun} ${meta.verb} --format llm` },
     ],
     capability: READ_CAPABILITY,
     run: (params: Record<string, unknown>, rt: PragmaRuntime) =>

package/src/kernel/project/cli/buildProgram.test.ts

@@ -61,6 +61,50 @@ describe("buildProgram — flags", () => {
   });
 });
 
+describe("buildProgram — default-true boolean negation (B9)", () => {
+  const negatableVerb: VerbSpec = {
+    path: ["thing", "do"],
+    summary: "thing do summary",
+    params: [
+      { kind: "boolean", name: "ssr", doc: "Include SSR.", default: true },
+      {
+        kind: "boolean",
+        name: "runInstall",
+        doc: "Install now.",
+        default: false,
+      },
+      { kind: "boolean", name: "withHistory", doc: "Seed history." },
+    ],
+    output: {
+      formatters: {
+        plain: (d) => String(d),
+        llm: (d) => String(d),
+        json: (d) => JSON.stringify(d),
+      },
+    },
+    capability: { needsStore: false, mutates: false, mcp: { expose: true } },
+    run: async () => null,
+  };
+  const program = projectCli([{ name: "thing", verbs: [negatableVerb] }]);
+  const doCmd = program.commands
+    .find((c) => c.name() === "thing")
+    ?.commands.find((c) => c.name() === "do");
+
+  it("pairs a `--no-` negation onto a default-true boolean so it is disableable", () => {
+    const longs = doCmd?.options.map((o) => o.long) ?? [];
+    expect(longs).toContain("--ssr");
+    expect(longs).toContain("--no-ssr");
+  });
+
+  it("leaves default-false / defaultless booleans un-negated (no Commander default-flip)", () => {
+    const longs = doCmd?.options.map((o) => o.long) ?? [];
+    expect(longs).toContain("--run-install");
+    expect(longs).not.toContain("--no-run-install");
+    expect(longs).toContain("--with-history");
+    expect(longs).not.toContain("--no-with-history");
+  });
+});
+
 describe("buildProgram — early exits", () => {
   it("throws commander.version for --version, writing the version", async () => {
     const program = projectCli([fixtureModule]);
@@ -353,7 +397,8 @@ describe("formatRootHelp — grouping", () => {
 
   it("shows the global flags block", () => {
     expect(help).toContain("Global flags");
-    expect(help).toContain("--llm");
+    expect(help).not.toContain("--llm");
+    expect(help).toContain("--format <plain|llm|json>");
     expect(help).toContain("--detail <level>");
   });
 
@@ -374,12 +419,11 @@ describe("formatRootHelp — grouping", () => {
         mcp     Start the MCP server over stdio
 
       Global flags
-        --llm                  Condensed Markdown output for agents
-        --format <json|plain>  Select output format
-        --detail <level>       Progressive-disclosure level (summary, standard, detailed)
-        --verbose              Diagnostic output on stderr
-        --help                 Show help (works on any command)
-        --version              Show the CLI version
+        --format <plain|llm|json>  Select output format (llm = condensed Markdown for agents)
+        --detail <level>           Progressive-disclosure level (summary, standard, detailed)
+        --verbose                  Diagnostic output on stderr
+        --help                     Show help (works on any command)
+        --version                  Show the CLI version
 
       Run \`pragma <command> --help\` for details, or \`pragma capabilities\` to get oriented."
     `);

package/src/kernel/project/cli/buildProgram.ts

@@ -70,6 +70,17 @@ function registerParams(command: Command, verb: VerbSpec): void {
     } else {
       command.option(spec, param.doc);
     }
+    // B9: a default-`true` boolean is otherwise undisableable — the grammar has
+    // no negation form, so `create`'s sibling booleans (--ssr/--with-styles/…)
+    // could never be turned off. Register a paired `--no-<flag>` so they can:
+    // Commander keeps the `true` default and lets `--no-<flag>` set it false
+    // (verified: an unset default-false boolean is left alone). This is a CLI
+    // PARSE convenience, never a ParamSpec — `emitSurface`/MCP/the covenant are
+    // untouched — so the frozen flag list stands and negation stays additive.
+    if (param.kind === "boolean" && param.default === true) {
+      const flag = kebabCase(param.name);
+      command.option(`--no-${flag}`, `Disable --${flag} (on by default).`);
+    }
   }
 
   if (verb.capability.mutates) {

package/src/kernel/project/cli/globalFlags.test.ts

@@ -9,10 +9,18 @@ const TTY = { isTty: true, noAutoLlm: false };
 const PIPE = { isTty: false, noAutoLlm: false };
 
 describe("parseGlobalFlags", () => {
-  it("honours an explicit --llm", () => {
-    expect(parseGlobalFlags(["--llm"], TTY)).toMatchObject({
+  it("honours an explicit --format llm (condensed even on a TTY)", () => {
+    expect(parseGlobalFlags(["--format", "llm"], TTY)).toMatchObject({
       llm: true,
       autoLlm: false,
+      format: "llm",
+    });
+  });
+
+  it("forces human output with --format plain down a pipe", () => {
+    expect(parseGlobalFlags(["--format", "plain"], PIPE)).toMatchObject({
+      llm: false,
+      autoLlm: false,
       format: "plain",
     });
   });
@@ -69,7 +77,7 @@ describe("stripGlobalFlags", () => {
       "list",
     ]);
     expect(
-      stripGlobalFlags(["block", "--llm", "list", "--detail", "detailed"]),
+      stripGlobalFlags(["block", "--verbose", "list", "--detail", "detailed"]),
     ).toEqual(["block", "list"]);
     expect(stripGlobalFlags(["--format=json", "config", "show"])).toEqual([
       "config",
@@ -90,7 +98,7 @@ describe("readRawFormat", () => {
 
   it("reports a valueless --format as empty string", () => {
     expect(readRawFormat(["--format"])).toBe("");
-    expect(readRawFormat(["--format", "--llm"])).toBe("");
+    expect(readRawFormat(["--format", "--verbose"])).toBe("");
   });
 
   it("returns undefined when --format is absent", () => {

package/src/kernel/project/cli/globalFlags.ts

@@ -1,13 +1,14 @@
 /**
  * Global-flag pre-parsing, ahead of Commander.
  *
- * `--llm`, `--format`, `--verbose`, and `--detail` may appear anywhere on the
- * line, so they are scanned and stripped before Commander sees argv — otherwise
+ * `--format`, `--verbose`, and `--detail` may appear anywhere on the line, so
+ * they are scanned and stripped before Commander sees argv — otherwise
  * `enablePositionalOptions()` scoping would reject a flag placed after a verb.
  * Ported from the v1 `parseGlobalFlags`, with two v2 changes: a new `--detail`
  * flag and the `--format text` value renamed to `plain` (the kernel's
- * {@link OutputFormat}). Both the space (`--format json`) and equals
- * (`--format=json`) forms are recognized.
+ * {@link OutputFormat}). The dedicated `--llm` flag was folded into
+ * `--format llm`, leaving auto-detection as the sole implicit trigger. Both the
+ * space (`--format json`) and equals (`--format=json`) forms are recognized.
  */
 
 import { DETAIL_LEVELS, type DetailLevel } from "../../../constants.js";
@@ -86,10 +87,11 @@ function readDetail(argv: readonly string[]): DetailLevel | undefined {
 /**
  * Extract the global flags from raw argv (the user's arguments, argv[2:]).
  *
- * Auto-LLM: with no `--llm`/`--format` and a non-interactive stdout (piped or
+ * Auto-LLM: with no explicit `--format` and a non-interactive stdout (piped or
  * redirected — the shape an agent captures), `llm` defaults to true so agents
- * get condensed Markdown without a flag. `--llm`, `--format`, and
- * `PRAGMA_NO_AUTO_LLM` all override it.
+ * get condensed Markdown without a flag. Any explicit `--format` overrides it —
+ * `--format plain` forces human output down a pipe, `--format llm` forces the
+ * condensed form even on a TTY — as does `PRAGMA_NO_AUTO_LLM`.
  *
  * @param argv - The user's arguments (no `node`/script prefix).
  * @param env - Output environment probe (defaults to the real process).
@@ -100,15 +102,14 @@ export function parseGlobalFlags(
   argv: readonly string[],
   env: OutputEnvironment = readOutputEnvironment(),
 ): GlobalFlags {
-  const explicitLlm = argv.includes("--llm");
   const rawFormat = readFlagValue(argv, "--format");
-  const format = rawFormat === "json" ? "json" : "plain";
+  const format =
+    rawFormat === "json" ? "json" : rawFormat === "llm" ? "llm" : "plain";
   const formatRequested = rawFormat !== undefined;
-  const autoLlm =
-    !explicitLlm && !formatRequested && !env.isTty && !env.noAutoLlm;
+  const autoLlm = !formatRequested && !env.isTty && !env.noAutoLlm;
   const detail = readDetail(argv);
   return {
-    llm: explicitLlm || autoLlm,
+    llm: format === "llm" || autoLlm,
     autoLlm,
     format,
     verbose: argv.includes("--verbose"),
@@ -130,10 +131,9 @@ export function stripGlobalFlags(argv: readonly string[]): string[] {
   const result: string[] = [];
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
-    if (arg === "--llm" || arg === "--verbose") continue;
+    if (arg === "--verbose") continue;
     if (
       arg?.startsWith("--format=") ||
-      arg?.startsWith("--llm=") ||
       arg?.startsWith("--verbose=") ||
       arg?.startsWith("--detail=")
     ) {

package/src/kernel/project/cli/rootHelp.ts

@@ -195,8 +195,10 @@ export function formatRootHelp(
   // never these strings.
   lines.push(helpHeading("Global flags"));
   const flags: [string, string][] = [
-    ["--llm", "Condensed Markdown output for agents"],
-    ["--format <json|plain>", "Select output format"],
+    [
+      "--format <plain|llm|json>",
+      "Select output format (llm = condensed Markdown for agents)",
+    ],
     [
       "--detail <level>",
       "Progressive-disclosure level (summary, standard, detailed)",

package/src/kernel/project/mcp/instructions.ts

@@ -38,7 +38,7 @@ export function buildInstructions(
 
   return [
     "pragma is a CLI and MCP server over a design-system knowledge graph.",
-    `${CONVENTIONS.system} ${CONVENTIONS.model} ${CONVENTIONS.querying}`,
+    `${CONVENTIONS.system} ${CONVENTIONS.model} ${CONVENTIONS.querying} ${CONVENTIONS.mutations}`,
     "",
     "Discovery sequence:",
     steps,