@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/capabilities/ontology/queries.ts

@@ -0,0 +1,197 @@
+/**
+ * Store-backed ontology inspection queries + shapes (the TBox exception).
+ *
+ * Unlike instance reads (GraphQL by default), ontology inspection queries the
+ * schema directly with SPARQL over `owl:Class`/`owl:*Property` — a recorded
+ * TBox exception to the source rule. Full IRIs are used in the query text so the
+ * result never depends on which vocabulary prefixes the store injected.
+ */
+
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+
+const OWL = "http://www.w3.org/2002/07/owl#";
+const RDFS = "http://www.w3.org/2000/01/rdf-schema#";
+const OWL_CLASS = `${OWL}Class`;
+const OWL_OBJECT_PROPERTY = `${OWL}ObjectProperty`;
+const OWL_DATATYPE_PROPERTY = `${OWL}DatatypeProperty`;
+
+/** A loaded namespace summary (`ontology list`). */
+export interface OntologySummary {
+  readonly prefix: string;
+  readonly namespace: string;
+  readonly classCount: number;
+  readonly propertyCount: number;
+}
+
+/** A class in the hierarchy, with its instance count from the pack index. */
+export interface OntologyClass {
+  readonly uri: string;
+  readonly label: string;
+  readonly superclass?: string;
+  readonly instanceCount: number;
+}
+
+/** A property definition. */
+export interface OntologyProperty {
+  readonly uri: string;
+  readonly label: string;
+  readonly domain?: string;
+  readonly range?: string;
+  readonly type: "object" | "datatype";
+}
+
+/** The `ontology show` payload — the detailed view plus render options. */
+export interface OntologyShowData {
+  readonly prefix: string;
+  readonly namespace: string;
+  readonly classes: readonly OntologyClass[];
+  readonly properties: readonly OntologyProperty[];
+  /** Show full IRIs instead of prefix-compacted ones. */
+  readonly fullUris: boolean;
+  /** The `--class` focus, if any. */
+  readonly focus?: string;
+}
+
+type QueryRt = Pick<PragmaRuntime, "query">;
+
+/** Local name of an IRI (`…#Thing`/`…/Thing` → `Thing`). */
+export function localName(uri: string): string {
+  const hash = uri.lastIndexOf("#");
+  if (hash !== -1) return uri.slice(hash + 1);
+  const slash = uri.lastIndexOf("/");
+  return slash !== -1 ? uri.slice(slash + 1) : uri;
+}
+
+async function select(
+  rt: QueryRt,
+  text: string,
+): Promise<Record<string, string>[]> {
+  const result = await rt.query.sparql(text);
+  return result.type === "select"
+    ? (result.bindings as Record<string, string>[])
+    : [];
+}
+
+/** Group all defined classes/properties by their namespace prefix, with counts. */
+export async function listNamespaces(
+  rt: QueryRt,
+  prefixes: Readonly<Record<string, string>>,
+): Promise<OntologySummary[]> {
+  const [classes, props] = await Promise.all([
+    select(rt, `SELECT ?class WHERE { ?class a <${OWL_CLASS}> }`),
+    select(
+      rt,
+      `SELECT ?prop WHERE { ?prop a ?t . VALUES ?t { <${OWL_OBJECT_PROPERTY}> <${OWL_DATATYPE_PROPERTY}> } }`,
+    ),
+  ]);
+  const entries = Object.entries(prefixes);
+  const classByPrefix = new Map<string, Set<string>>();
+  const propByPrefix = new Map<string, Set<string>>();
+  const tally = (
+    rows: Record<string, string>[],
+    key: "class" | "prop",
+    into: Map<string, Set<string>>,
+  ) => {
+    for (const row of rows) {
+      const uri = row[key] ?? "";
+      const match = findNamespace(uri, entries);
+      if (!match) continue;
+      const set = into.get(match.prefix) ?? new Set();
+      set.add(uri);
+      into.set(match.prefix, set);
+    }
+  };
+  tally(classes, "class", classByPrefix);
+  tally(props, "prop", propByPrefix);
+  const allPrefixes = new Set([
+    ...classByPrefix.keys(),
+    ...propByPrefix.keys(),
+  ]);
+  return [...allPrefixes].sort().map((prefix) => ({
+    prefix,
+    namespace: prefixes[prefix] ?? "",
+    classCount: classByPrefix.get(prefix)?.size ?? 0,
+    propertyCount: propByPrefix.get(prefix)?.size ?? 0,
+  }));
+}
+
+/** The longest-matching namespace prefix for a URI. */
+function findNamespace(
+  uri: string,
+  entries: [string, string][],
+): { prefix: string; namespace: string } | undefined {
+  let best: { prefix: string; namespace: string } | undefined;
+  for (const [prefix, namespace] of entries) {
+    if (
+      uri.startsWith(namespace) &&
+      (!best || namespace.length > best.namespace.length)
+    ) {
+      best = { prefix, namespace };
+    }
+  }
+  return best;
+}
+
+/** All classes in a namespace, with labels, superclasses, and index counts. */
+export async function queryClasses(
+  rt: QueryRt,
+  namespace: string,
+  instanceCountByType: Readonly<Record<string, number>>,
+): Promise<OntologyClass[]> {
+  const rows = await select(
+    rt,
+    [
+      "SELECT ?class ?label ?superclass WHERE {",
+      `  ?class a <${OWL_CLASS}> .`,
+      `  FILTER(STRSTARTS(STR(?class), "${namespace}"))`,
+      `  OPTIONAL { ?class <${RDFS}label> ?label }`,
+      `  OPTIONAL { ?class <${RDFS}subClassOf> ?superclass }`,
+      "} ORDER BY ?class",
+    ].join("\n"),
+  );
+  const seen = new Map<string, OntologyClass>();
+  for (const row of rows) {
+    const uri = row.class ?? "";
+    if (seen.has(uri)) continue;
+    seen.set(uri, {
+      uri,
+      label: row.label || localName(uri),
+      ...(row.superclass ? { superclass: row.superclass } : {}),
+      instanceCount: instanceCountByType[uri] ?? 0,
+    });
+  }
+  return [...seen.values()];
+}
+
+/** All object/datatype properties in a namespace. */
+export async function queryProperties(
+  rt: QueryRt,
+  namespace: string,
+): Promise<OntologyProperty[]> {
+  const rows = await select(
+    rt,
+    [
+      "SELECT ?prop ?label ?domain ?range ?propType WHERE {",
+      "  ?prop a ?propType .",
+      `  VALUES ?propType { <${OWL_OBJECT_PROPERTY}> <${OWL_DATATYPE_PROPERTY}> }`,
+      `  FILTER(STRSTARTS(STR(?prop), "${namespace}"))`,
+      `  OPTIONAL { ?prop <${RDFS}label> ?label }`,
+      `  OPTIONAL { ?prop <${RDFS}domain> ?domain }`,
+      `  OPTIONAL { ?prop <${RDFS}range> ?range }`,
+      "} ORDER BY ?prop",
+    ].join("\n"),
+  );
+  const seen = new Map<string, OntologyProperty>();
+  for (const row of rows) {
+    const uri = row.prop ?? "";
+    if (seen.has(uri)) continue;
+    seen.set(uri, {
+      uri,
+      label: row.label || localName(uri),
+      ...(row.domain ? { domain: row.domain } : {}),
+      ...(row.range ? { range: row.range } : {}),
+      type: row.propType?.includes("ObjectProperty") ? "object" : "datatype",
+    });
+  }
+  return [...seen.values()];
+}

package/src/capabilities/ontology/render.ts

@@ -0,0 +1,87 @@
+/**
+ * Formatters for `ontology list` and `ontology show`.
+ */
+
+import { compactUri } from "../../kernel/render/compactUri.js";
+import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
+import type { Formatters } from "../../kernel/spec/types.js";
+import type {
+  OntologyClass,
+  OntologyProperty,
+  OntologyShowData,
+  OntologySummary,
+} from "./queries.js";
+
+export const ontologyListFormatters: Formatters<OntologySummary[]> = {
+  plain: (rows) =>
+    rows
+      .map(
+        (r) =>
+          `${r.prefix}  ${compactUri(r.namespace, DEFAULT_PREFIX_MAP)}  ${r.classCount} classes, ${r.propertyCount} properties`,
+      )
+      .join("\n"),
+  llm: (rows) =>
+    [
+      `## Ontologies (${rows.length})`,
+      "",
+      ...rows.map(
+        (r) =>
+          `- \`${r.prefix}\` — ${r.classCount} classes, ${r.propertyCount} properties (\`${r.namespace}\`)`,
+      ),
+    ].join("\n"),
+  json: (rows) => JSON.stringify(rows, null, 2),
+};
+
+/** Render a URI compacted or full, per the show flags. */
+function uri(value: string, full: boolean): string {
+  return full ? value : compactUri(value, DEFAULT_PREFIX_MAP);
+}
+
+function classLine(c: OntologyClass, full: boolean, bullet: string): string {
+  const sup = c.superclass ? ` extends ${uri(c.superclass, full)}` : "";
+  const count = c.instanceCount > 0 ? ` [${c.instanceCount}]` : "";
+  return `${bullet}${c.label} (${uri(c.uri, full)})${sup}${count}`;
+}
+
+function propLine(p: OntologyProperty, full: boolean, bullet: string): string {
+  const domain = p.domain ? ` domain: ${uri(p.domain, full)}` : "";
+  const range = p.range ? ` range: ${uri(p.range, full)}` : "";
+  return `${bullet}${p.label} (${uri(p.uri, full)}) (${p.type})${domain}${range}`;
+}
+
+export const ontologyShowFormatters: Formatters<OntologyShowData> = {
+  plain(data) {
+    const title = `${data.prefix}: ${compactUri(data.namespace, DEFAULT_PREFIX_MAP)}${data.focus ? ` — ${data.focus}` : ""}`;
+    const lines = [title, "═".repeat(Math.max(title.length, 24))];
+    if (data.classes.length > 0) {
+      lines.push("", "Classes:");
+      for (const c of data.classes)
+        lines.push(classLine(c, data.fullUris, "  "));
+    }
+    if (data.properties.length > 0) {
+      lines.push("", "Properties:");
+      for (const p of data.properties)
+        lines.push(propLine(p, data.fullUris, "  "));
+    }
+    return lines.join("\n");
+  },
+  llm(data) {
+    const lines = [
+      `## ${data.prefix}: ${compactUri(data.namespace, DEFAULT_PREFIX_MAP)}${data.focus ? ` — ${data.focus}` : ""}`,
+      "",
+    ];
+    if (data.classes.length > 0) {
+      lines.push("### Classes");
+      for (const c of data.classes)
+        lines.push(classLine(c, data.fullUris, "- "));
+      lines.push("");
+    }
+    if (data.properties.length > 0) {
+      lines.push("### Properties");
+      for (const p of data.properties)
+        lines.push(propLine(p, data.fullUris, "- "));
+    }
+    return lines.join("\n").trimEnd();
+  },
+  json: (data) => JSON.stringify(data, null, 2),
+};

package/src/capabilities/ontology/verbs.ts

@@ -0,0 +1,269 @@
+/**
+ * `ontology list` and `ontology lookup <prefix>` — schema (TBox) inspection.
+ *
+ * `list` groups loaded namespaces by prefix with class/property counts; `lookup`
+ * renders a namespace's class hierarchy (with per-class instance counts read
+ * from the pack index) and, with `--properties`, a `--class` focus, or a
+ * `--detail` of `standard`+, its properties. `--full-uris` shows absolute IRIs;
+ * `--class <name>` narrows to one class and the properties whose domain is that
+ * class.
+ *
+ * `ontology show` is the DEPRECATED alias of `ontology lookup` (AV-228 B1): the
+ * verb was renamed to `lookup` for consistency with block/standard/tier/etc.
+ * (the ratified by-name read name), and `show` is kept callable — both share the
+ * same params, disclosure, and handler, and both stay blessed in the covenant.
+ *
+ * Disclosure (B5): rather than reinvent its own scheme, the by-name read declares
+ * the canonical disclosure ladder and honours the `--detail`/config `detail` the
+ * rest of the CLI reads AND the injected `detail` tool param the MCP projector
+ * derives from that declaration — a two-behaviour fold where `summary` is
+ * classes-only and `standard`/`detailed` add the properties section. The frozen
+ * `--properties` flag stays as an explicit override (it forces the section at
+ * any level), so the covenant is untouched.
+ */
+
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { resolvePackDetail } from "../../kernel/packs/disclosure.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type {
+  DisclosureSpec,
+  ParamSpec,
+  VerbSpec,
+} from "../../kernel/spec/types.js";
+import {
+  listNamespaces,
+  localName,
+  type OntologyShowData,
+  type OntologySummary,
+  queryClasses,
+  queryProperties,
+} from "./queries.js";
+import { ontologyListFormatters, ontologyShowFormatters } from "./render.js";
+
+/** Resolve a prefix (`ds`) or full namespace URI to the `{ prefix, namespace }` pair. */
+function resolvePrefix(
+  input: string,
+  prefixes: Readonly<Record<string, string>>,
+): { prefix: string; namespace: string } {
+  if (input.startsWith("http://") || input.startsWith("https://")) {
+    const entry = Object.entries(prefixes).find(([, ns]) => ns === input);
+    if (entry) return { prefix: entry[0], namespace: entry[1] };
+    throw PragmaError.invalidInput("namespace", input, {
+      validOptions: Object.values(prefixes),
+      recovery: {
+        message: "List loaded ontology namespaces.",
+        cli: "pragma ontology list",
+        mcp: { tool: "ontology_list" },
+      },
+    });
+  }
+  const namespace = prefixes[input];
+  if (namespace === undefined) {
+    throw PragmaError.invalidInput("prefix", input, {
+      validOptions: Object.keys(prefixes),
+      recovery: {
+        message: "List loaded ontologies.",
+        cli: "pragma ontology list",
+        mcp: { tool: "ontology_list" },
+      },
+    });
+  }
+  return { prefix: input, namespace };
+}
+
+const listVerb: VerbSpec<Record<string, unknown>, OntologySummary[]> = {
+  path: ["ontology", "list"],
+  summary: "List loaded ontology namespaces with class and property counts.",
+  params: [],
+  output: { formatters: ontologyListFormatters },
+  examples: [{ cmd: "pragma ontology list" }],
+  capability: {
+    needsStore: true,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: async (_params: Record<string, unknown>, rt: PragmaRuntime) => {
+    const session = await rt.store.get();
+    return listNamespaces(rt, session.prefixes);
+  },
+};
+
+/**
+ * The canonical disclosure the by-name read folds onto (B5). Declared on both
+ * the primary {@link ontologyLookupVerb} and its deprecated {@link
+ * ontologyShowVerb} alias — so the MCP projector injects the `detail` enum tool
+ * param and its per-call `withDetail` seeding light up (symmetric with
+ * `block`/`standard`, which an inline resolve left dark over MCP) — AND read by
+ * `run` to resolve the effective level, so the advertised param and the fetched
+ * level share ONE source. The levels are the full canonical ladder; the fold is
+ * two-behaviour (`summary` = classes only, `standard`/`detailed` add properties).
+ */
+const BY_NAME_DISCLOSURE: DisclosureSpec = {
+  levels: ["summary", "standard", "detailed"],
+  default: "summary",
+};
+
+/** The params shared by `ontology lookup` and its deprecated `ontology show` alias. */
+const BY_NAME_PARAMS: ParamSpec[] = [
+  {
+    kind: "string",
+    name: "prefix",
+    doc: "The namespace prefix (ds) or full URI.",
+    positional: true,
+    required: true,
+    complete: { kind: "names", source: { from: "prefixes" } },
+  },
+  {
+    kind: "boolean",
+    name: "properties",
+    doc: "Include the properties section (also implied by --detail standard or higher).",
+  },
+  {
+    kind: "boolean",
+    name: "fullUris",
+    doc: "Show full IRIs instead of prefixed.",
+  },
+  {
+    kind: "string",
+    name: "class",
+    doc: "Focus on one class and its properties.",
+  },
+];
+
+/** The by-name read capability — a storeless-free, read-only MCP tool. */
+const BY_NAME_CAPABILITY = {
+  needsStore: true,
+  mutates: false,
+  mcp: {
+    expose: true as const,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+};
+
+/**
+ * The by-name read handler shared by `ontology lookup` and `ontology show`.
+ *
+ * @param params - The coerced param bag (`prefix`, `properties`, `fullUris`, `class`).
+ * @param rt - The runtime (store + disclosure precedence).
+ * @returns The namespace's classes (and, per disclosure, properties) payload.
+ */
+async function runByName(
+  params: Record<string, unknown>,
+  rt: PragmaRuntime,
+): Promise<OntologyShowData> {
+  const session = await rt.store.get();
+  const { prefix, namespace } = resolvePrefix(
+    String(params.prefix),
+    session.prefixes,
+  );
+  const focus = typeof params.class === "string" ? params.class : undefined;
+  // Fold ontology's bespoke disclosure onto the canonical `--detail` (B5),
+  // resolving through the SAME {@link BY_NAME_DISCLOSURE} the verb declares (so
+  // the MCP `detail` param and its withDetail seeding resolve identically, not
+  // just the CLI `--detail` flag) and the SAME precedence packs use (flag >
+  // explicit config > default). The frozen `--properties` flag and a `--class`
+  // focus still force the section, so honouring the level is covenant-safe.
+  const level = await resolvePackDetail(rt, BY_NAME_DISCLOSURE);
+  const wantProperties =
+    params.properties === true || focus !== undefined || level !== "summary";
+
+  let classes = await queryClasses(
+    rt,
+    namespace,
+    session.index.instanceCountByType,
+  );
+  let properties = wantProperties ? await queryProperties(rt, namespace) : [];
+
+  if (focus !== undefined) {
+    const needle = focus.toLowerCase();
+    classes = classes.filter(
+      (c) =>
+        localName(c.uri).toLowerCase() === needle ||
+        c.label.toLowerCase() === needle,
+    );
+    const focusUris = new Set(classes.map((c) => c.uri));
+    properties = properties.filter(
+      (p) => p.domain !== undefined && focusUris.has(p.domain),
+    );
+  }
+
+  if (classes.length === 0 && properties.length === 0) {
+    throw PragmaError.notFound("ontology", String(params.prefix), {
+      recovery: {
+        message: "List loaded ontologies.",
+        cli: "pragma ontology list",
+        mcp: { tool: "ontology_list" },
+      },
+    });
+  }
+
+  return {
+    prefix,
+    namespace,
+    classes,
+    properties,
+    fullUris: params.fullUris === true,
+    ...(focus !== undefined ? { focus } : {}),
+  };
+}
+
+/**
+ * Build one by-name read verb (`lookup` primary or `show` deprecated alias) —
+ * both share {@link BY_NAME_PARAMS}, {@link BY_NAME_DISCLOSURE}, the formatters,
+ * and {@link runByName}; only the path label, summary, doc, and examples differ.
+ */
+function byNameVerb(
+  verb: "lookup" | "show",
+  summary: string,
+  examples: VerbSpec["examples"],
+  doc?: string,
+): VerbSpec<Record<string, unknown>, OntologyShowData> {
+  return {
+    path: ["ontology", verb],
+    summary,
+    ...(doc !== undefined ? { doc } : {}),
+    params: BY_NAME_PARAMS,
+    output: { formatters: ontologyShowFormatters },
+    examples,
+    disclosure: BY_NAME_DISCLOSURE,
+    capability: BY_NAME_CAPABILITY,
+    run: runByName,
+  };
+}
+
+/** The `ontology` verbs (`list`, `lookup`, and the deprecated `show` alias). */
+export const ontologyListVerb = asVerb(listVerb);
+
+/** `ontology lookup <prefix>` — the primary by-name schema read. */
+export const ontologyLookupVerb = asVerb(
+  byNameVerb(
+    "lookup",
+    "Look up a namespace's classes (hierarchy + counts) and properties.",
+    [
+      { cmd: "pragma ontology lookup ds" },
+      { cmd: "pragma ontology lookup ds --properties" },
+      { cmd: "pragma ontology lookup ds --class Component" },
+    ],
+  ),
+);
+
+/**
+ * `ontology show <prefix>` — DEPRECATED alias of {@link ontologyLookupVerb}
+ * (AV-228 B1). Kept callable and blessed in the covenant; shares the same
+ * handler, so it behaves identically. New callers should use `ontology lookup`.
+ */
+export const ontologyShowVerb = asVerb(
+  byNameVerb(
+    "show",
+    "(deprecated: use `ontology lookup`) Show a namespace's classes (hierarchy + counts) and properties.",
+    [
+      { cmd: "pragma ontology lookup ds", note: "prefer `lookup`" },
+      { cmd: "pragma ontology show ds", note: "deprecated alias" },
+    ],
+    "Deprecated alias of `ontology lookup` — retained for compatibility. Prefer `ontology lookup <prefix>`.",
+  ),
+);

package/src/capabilities/prompt/index.ts

@@ -0,0 +1,18 @@
+/**
+ * The `prompt` capability module — the covenant content noun
+ * (`prompt_list`/`prompt_lookup`) PLUS the native MCP `prompts/*` surface, both
+ * projecting the ONE `ds:Prompt` source. The `mcpPrompts` hook is the same
+ * `promptProvider` the kernel defines; this module is where it attaches, so the
+ * default MCP server advertises prompts sourced from the active graph.
+ */
+
+import { promptProvider } from "../../kernel/project/mcp/prompts/provider.js";
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { promptListVerb, promptLookupVerb } from "./verbs.js";
+
+/** The `prompt` capability module (content tools + native prompt surface). */
+export const promptModule: CapabilityModule = {
+  name: "prompt",
+  verbs: [promptListVerb, promptLookupVerb],
+  mcpPrompts: promptProvider,
+};

package/src/capabilities/prompt/prompt.render.test.ts

@@ -0,0 +1,94 @@
+import chalk from "chalk";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  promptListFormatters,
+  promptLookupFormatters,
+} from "./prompt.render.js";
+import type { PromptListData, PromptLookupData } from "./types.js";
+
+/** Run `body` with stdout's `isTTY` forced to `value`, then restore it. */
+function withStdoutTty(value: boolean | undefined, body: () => void): void {
+  const stream = process.stdout as { isTTY?: boolean };
+  const saved = stream.isTTY;
+  stream.isTTY = value;
+  try {
+    body();
+  } finally {
+    stream.isTTY = saved;
+  }
+}
+
+const LOOKUP: PromptLookupData = {
+  name: "build-a-block",
+  description: "Scaffold a block",
+  arguments: [
+    { name: "blockName", required: true, description: "The block name" },
+    { name: "tier", required: false },
+  ],
+  body: "Create {{blockName}} in {{tier}}.",
+};
+
+const LIST: PromptListData = {
+  prompts: [
+    { name: "build-a-block", description: "Scaffold a block", arguments: [] },
+  ],
+};
+
+describe("promptLookupFormatters", () => {
+  it("underlines the plain name with an ═ rule (B7)", () => {
+    const lines = promptLookupFormatters.plain(LOOKUP).split("\n");
+    expect(lines.at(0)).toBe("build-a-block");
+    expect(lines.at(1)).toBe("═".repeat(24));
+    expect(lines.at(2)).toBe("");
+    expect(lines).toContain("  args: blockName (required), tier");
+  });
+
+  it("heads the llm entity at H2 with H3 sub-sections (B2)", () => {
+    const lines = promptLookupFormatters.llm(LOOKUP).split("\n");
+    expect(lines.at(0)).toBe("## build-a-block");
+    expect(lines).toContain("### Arguments");
+    expect(lines).toContain("### Template");
+    // The old H1 title / H2 sub-sections are gone.
+    expect(lines).not.toContain("# build-a-block");
+    expect(lines).not.toContain("## Arguments");
+    expect(lines).not.toContain("## Template");
+  });
+});
+
+describe("promptListFormatters", () => {
+  it("heads the llm list at H2, never H1 (B2)", () => {
+    const out = promptListFormatters.llm(LIST);
+    expect(out.startsWith("## Prompts")).toBe(true);
+    expect(out).not.toMatch(/^# Prompts/m);
+  });
+});
+
+describe("promptLookupFormatters — shared style seam (B7)", () => {
+  const prevLevel = chalk.level;
+  afterEach(() => {
+    chalk.level = prevLevel;
+  });
+
+  it("styles the plain title on a color-capable TTY", () => {
+    chalk.level = 1;
+    withStdoutTty(true, () => {
+      // The title/rule/label now route through the same style seam block and
+      // skill lookups use — previously a prompt title stayed unstyled on a TTY.
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting the ESC byte is the point
+      expect(promptLookupFormatters.plain(LOOKUP)).toMatch(/\x1b\[/);
+    });
+  });
+
+  it("keeps piped plain output byte-stable off a TTY", () => {
+    chalk.level = 3;
+    withStdoutTty(undefined, () => {
+      const out = promptLookupFormatters.plain(LOOKUP);
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: asserting NO ESC byte survives
+      expect(out).not.toMatch(/\x1b\[/);
+      const lines = out.split("\n");
+      expect(lines.at(0)).toBe("build-a-block");
+      expect(lines.at(1)).toBe("═".repeat(24));
+      expect(lines).toContain("  args: blockName (required), tier");
+    });
+  });
+});