@canonical/pragma-cli 0.33.0 → 0.35.0

package/dist/src/capabilities/capabilities/catalog.js

@@ -0,0 +1,130 @@
+/**
+ * The SELF-UPDATING capabilities catalog.
+ *
+ * `buildCapabilitiesData(modules)` projects the LIVE grammar: it emits the
+ * surface, walks `mcpSurface.tools` (the sorted, covenant-conformant set), and
+ * annotates each tool from the authored `TOOL_HINTS` table. The tool set, the
+ * category counts, and the discovery-sample list are all DERIVED — never pinned
+ * — so the catalog tracks the surface automatically (the fix for the old shell's
+ * hand-maintained list, which drifted to name retired tools).
+ *
+ * Pure + zod-free: it reads only `emitSurface` (itself fast-path-safe), so the
+ * verb's storeless guarantee holds. The conventions + discovery strings are
+ * exported so `kernel/project/mcp/instructions.ts` derives the handshake
+ * orientation from the SAME source and the two can never diverge.
+ */
+import { BIN_NAME, PROGRAM_DESCRIPTION, VERSION } from "../../constants.js";
+import { emitSurface } from "../../kernel/spec/index.js";
+import { TOOL_HINTS } from "./hints.js";
+/**
+ * The four orientation conventions, and the single source both the
+ * `capabilities` tool and the MCP handshake read, so the two cannot contradict
+ * each other. `system` projects the distribution's identity rather than naming
+ * a domain — the live tool catalog the same handshake carries already says
+ * which nouns exist. `querying` is verbatim from the old shell (the SPARQL
+ * model is still accurate for v2); `model` stopped claiming reads are
+ * tier/channel-SCOPED when the hand-written filtering was removed (L-OPEN-9)
+ * — the hierarchy is graph data now, not a query gate; `mutations` is new in
+ * v2, surfacing the plan-first/confirm gate.
+ */
+export const CONVENTIONS = {
+    // `help` is authored as a bare phrase (`--help` renders it as one), so the
+    // self-description trails in parentheses rather than after a period this
+    // string would have to add — a fork writing "Explore the recipe graph."
+    // otherwise reads "recipe graph.. A CLI and MCP server…".
+    system: `${BIN_NAME} — ${PROGRAM_DESCRIPTION} (a CLI and MCP server over a knowledge graph).`,
+    model: "The graph models a tier hierarchy (e.g. global > apps > apps/lxd) and release channels (normal, experimental, prerelease) as DATA on each entity. Reads are unscoped — every list shows everything; filter by inspecting an entity's tier/release fields or with graph_query.",
+    querying: "All queries run against an RDF triple store. Prefixed IRIs (e.g. prefix:name) identify entities. Use ontology_list to discover the active namespaces.",
+    mutations: "Mutating tools are plan-first: call once WITHOUT confirm to get a plan (meta.planOnly, no writes), then repeat the call with confirm: true to execute.",
+};
+/** The output modes v2 renders (dropped "text" → "plain"; condensed retired). */
+const OUTPUT_MODES = ["plain", "json", "llm"];
+/** The set of tool names that mutate, read from the emitted surface. */
+function mutatingTools(modules) {
+    const mutating = new Set();
+    for (const { verbs } of Object.values(emitSurface(modules).nouns)) {
+        for (const verb of verbs) {
+            if (verb.mutates && typeof verb.mcp === "string")
+                mutating.add(verb.mcp);
+        }
+    }
+    return mutating;
+}
+/** The live sorted tool names the covenant blesses, from the emitted surface. */
+export function liveTools(modules) {
+    return emitSurface(modules).mcpSurface.tools;
+}
+/**
+ * Build the discovery sequence, deriving the sample list from the tools that
+ * ACTUALLY exist (v2 ships block/standard/modifier/token samples). Wording is
+ * ported from the old `buildCapabilitiesData`, plus a store-state pre-check so a
+ * cold agent is never sent into `*_sample` (or any store read) blind — every
+ * store read fails STORE_UNAVAILABLE until `sources_update` has built the store.
+ */
+export function buildDiscoverySequence(tools) {
+    const samples = tools.filter((tool) => tool.endsWith("_sample"));
+    const sampleList = samples.length > 0 ? samples.join(", ") : "the *_sample";
+    return [
+        {
+            stage: 1,
+            tool: "capabilities",
+            purpose: "Understand conventions, available tools, and how to navigate",
+        },
+        {
+            stage: 2,
+            tool: "sources_status",
+            purpose: "See which pack is answering. A fresh install answers reads from the snapshot shipped with the CLI and needs no build; only an `unavailable` status requires sources_update (confirm: true), which is a project that declared its own packs and has not built them.",
+        },
+        {
+            stage: 3,
+            tool: "*_sample",
+            purpose: `Call ${sampleList} tools to see real data shapes before querying. Prevents guessing at property names.`,
+        },
+        {
+            stage: 4,
+            tool: "domain tools",
+            purpose: "Query specific entities — block_list, standard_lookup, etc. Use the use_when hints above to pick the right tool.",
+        },
+    ];
+}
+/** Tally the catalog tools by category (all counts DERIVED, never pinned). */
+function countByCategory(tools) {
+    const of = (category) => tools.filter((tool) => tool.category === category).length;
+    return {
+        total: tools.length,
+        read: of("read"),
+        write: of("write"),
+        orientation: of("orientation"),
+        diagnostic: of("diagnostic"),
+    };
+}
+/**
+ * Build the capabilities payload from a set of capability modules.
+ *
+ * @param modules - The live capability modules (passed in to avoid a static
+ *   self-cycle; the verb's `run` dynamic-imports the registry barrel).
+ * @returns The structured, self-consistent capabilities map.
+ */
+export function buildCapabilitiesData(modules) {
+    const tools = liveTools(modules);
+    const catalogTools = tools.map((name) => {
+        const hint = TOOL_HINTS[name];
+        // A missing hint is a drift bug caught by `capabilities.test.ts`; degrade
+        // to a truthful placeholder rather than throwing inside a tool call.
+        return {
+            name,
+            category: hint?.category ?? "read",
+            use_when: hint?.use_when ?? "(no hint authored — see capabilities/hints.ts)",
+        };
+    });
+    return {
+        version: VERSION,
+        conventions: CONVENTIONS,
+        discovery_sequence: buildDiscoverySequence(tools),
+        tools: catalogTools,
+        counts: countByCategory(catalogTools),
+        limits: { output_modes: OUTPUT_MODES, condensed_available: false },
+    };
+}
+export { mutatingTools };
+//# sourceMappingURL=catalog.js.map

package/dist/src/capabilities/capabilities/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../../../src/capabilities/capabilities/catalog.ts"],"names":[],"mappings":"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"}

package/dist/src/capabilities/capabilities/hints.js

@@ -0,0 +1,195 @@
+/**
+ * The one authored input to the `capabilities` catalog: a `use_when` behavioural
+ * hint + category per tool. Everything else (the tool SET, counts, discovery
+ * samples) is DERIVED from the live grammar at build time, so this table is the
+ * only thing to keep in sync — and the drift-guard test (`capabilities.test.ts`)
+ * fails CI if a live tool has no hint, a hint names a tool that no longer
+ * exists, or a hint's category disagrees with the tool's real `mutates` flag.
+ *
+ * `use_when` strings for the surviving tools are ported verbatim from the old
+ * shell's `domains/llm/data/toolCatalog.ts`; the net-new v2 tools (config_set,
+ * graph_query, setup, upgrade, doctor, capabilities, prompt_*, sources_*,
+ * tier_lookup, create_*) are authored here.
+ */
+import { BIN_NAME } from "../../constants.js";
+/**
+ * Behavioural hints keyed by the LIVE tool name (`emitSurface` naming rule:
+ * `noun` or `noun_verb`). Categories: `write` ⟺ the verb mutates; `orientation`
+ * = the session-start map; `diagnostic` = environment/version reporting; else
+ * `read`. The drift guard enforces every one of those invariants.
+ */
+export const TOOL_HINTS = {
+    // — Orientation ————————————————————————————————————————————————————————————
+    capabilities: {
+        category: "orientation",
+        use_when: "Starting a session — understand conventions, available tools, and the discovery flow",
+    },
+    // — Diagnostic ————————————————————————————————————————————————————————————
+    doctor: {
+        category: "diagnostic",
+        use_when: "Diagnosing environment issues — config, store, completions, MCP health",
+    },
+    info: {
+        category: "diagnostic",
+        use_when: `Checking ${BIN_NAME} version, configuration summary, and store state`,
+    },
+    // — Read ——————————————————————————————————————————————————————————————————
+    block_list: {
+        category: "read",
+        use_when: "Browsing all components, patterns, layouts, and subcomponents in the store",
+    },
+    block_lookup: {
+        category: "read",
+        use_when: "Need full anatomy, modifiers, tokens, and standards for specific blocks by name or IRI",
+    },
+    block_sample: {
+        category: "read",
+        use_when: "See actual block data shapes before querying — returns random instances each call, prevents guessing at property names",
+    },
+    colophon: {
+        category: "read",
+        use_when: "Understanding how the active domain is built — its declared colophon, for onboarding or a demo",
+    },
+    config_get: {
+        category: "read",
+        use_when: "Reading ONE config field's effective value and the layer it came from — the single-value form of config_show",
+    },
+    config_show: {
+        category: "read",
+        use_when: "Checking the active configuration (tier, channel, detail) and which layer set each field",
+    },
+    graph_inspect: {
+        category: "read",
+        use_when: "Examining all triples for a specific URI — predicates, objects, and types",
+    },
+    graph_query: {
+        category: "read",
+        use_when: "Complex SPARQL joins or aggregations that other tools cannot express",
+    },
+    modifier_list: {
+        category: "read",
+        use_when: "Listing all modifier families and their allowed values",
+    },
+    modifier_lookup: {
+        category: "read",
+        use_when: "Need values and usage details for specific modifier families by name",
+    },
+    modifier_sample: {
+        category: "read",
+        use_when: "See actual modifier data shapes (with value lists) before querying — returns random instances each call",
+    },
+    ontology_list: {
+        category: "read",
+        use_when: "Discovering loaded namespaces, prefixes, and class/property counts",
+    },
+    ontology_lookup: {
+        category: "read",
+        use_when: "Exploring the full schema of a namespace by name — classes, properties, and hierarchy",
+    },
+    prompt_list: {
+        category: "read",
+        use_when: "Browsing the workflow prompt templates the active graph offers",
+    },
+    prompt_lookup: {
+        category: "read",
+        use_when: "Fetching a specific workflow prompt template's body and arguments by name",
+    },
+    skill_list: {
+        category: "read",
+        use_when: "Discovering agent skills provided by installed packs",
+    },
+    skill_lookup: {
+        category: "read",
+        use_when: "Loading full SKILL.md instructions for a specific agent skill by name",
+    },
+    sources_status: {
+        category: "read",
+        use_when: "Checking whether the local knowledge-graph pack is built and current",
+    },
+    standard_list: {
+        category: "read",
+        use_when: "Browsing code standards, optionally filtered by category or search term",
+    },
+    standard_lookup: {
+        category: "read",
+        use_when: "Need do/don't code examples for specific coding standards by name or IRI",
+    },
+    standard_categories: {
+        category: "read",
+        use_when: "Discovering which standard categories exist before filtering",
+    },
+    concept_list: {
+        category: "read",
+        use_when: "Browsing long-form design-system concepts (foundations, how-to guides, decision guides)",
+    },
+    concept_lookup: {
+        category: "read",
+        use_when: "Reading a concept's full Markdown documentation by name or IRI",
+    },
+    implementation_list: {
+        category: "read",
+        use_when: "Finding which library implements a block, on which platform, and where its source lives",
+    },
+    implementation_libraries: {
+        category: "read",
+        use_when: "Discovering which implementation libraries exist, and how much of the design system each covers",
+    },
+    standard_sample: {
+        category: "read",
+        use_when: "See actual standard data shapes (with dos/donts) before querying — returns random instances each call",
+    },
+    tier_list: {
+        category: "read",
+        use_when: "Understanding the tier hierarchy before setting a tier filter",
+    },
+    tier_lookup: {
+        category: "read",
+        use_when: "Need the blocks scoped to a specific tier by name",
+    },
+    token_list: {
+        category: "read",
+        use_when: "Browsing design tokens, optionally filtered by category (color, spacing, etc.)",
+    },
+    token_lookup: {
+        category: "read",
+        use_when: "Need theme values and resolution details for specific tokens by name or IRI",
+    },
+    token_sample: {
+        category: "read",
+        use_when: "See actual token data shapes (with theme values) before querying — returns random instances each call",
+    },
+    // — Write ——————————————————————————————————————————————————————————————————
+    config_set: {
+        category: "write",
+        use_when: "Setting any config field by name — tier, channel, or detail (e.g. `config set tier apps/lxd`)",
+    },
+    config_unset: {
+        category: "write",
+        use_when: 'Clearing a config field so the built-in default applies again — no value means "remove", this tool does',
+    },
+    create_component: {
+        category: "write",
+        use_when: "Scaffolding a new component (React, Svelte, or Lit)",
+    },
+    create_package: {
+        category: "write",
+        use_when: "Scaffolding a new npm package with proper monorepo configuration",
+    },
+    create_application: {
+        category: "write",
+        use_when: "Scaffolding a new React application with SSR, routing, and optional Relay",
+    },
+    setup: {
+        category: "write",
+        use_when: `Installing ${BIN_NAME}'s shell completions, MCP config, skills, and LSP into the environment`,
+    },
+    sources_update: {
+        category: "write",
+        use_when: "Building or refreshing the knowledge-graph pack from the configured packs",
+    },
+    upgrade: {
+        category: "write",
+        use_when: `Upgrading the ${BIN_NAME} CLI itself to the latest release`,
+    },
+};
+//# sourceMappingURL=hints.js.map

package/dist/src/capabilities/capabilities/hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hints.js","sourceRoot":"","sources":["../../../../src/capabilities/capabilities/hints.ts"],"names":[],"mappings":"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"}

package/dist/src/capabilities/capabilities/index.js

@@ -0,0 +1,11 @@
+/**
+ * The `capabilities` capability module — the grammar-derived orientation tool
+ * that replaces the retired `llm` tool.
+ */
+import { capabilitiesSelfVerb } from "./capabilities.verb.js";
+/** The `capabilities` capability module (a single storeless self-verb). */
+export const capabilitiesModule = {
+    name: "capabilities",
+    verbs: [capabilitiesSelfVerb],
+};
+//# sourceMappingURL=index.js.map

package/dist/src/capabilities/capabilities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/capabilities/capabilities/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D,2EAA2E;AAC3E,MAAM,CAAC,MAAM,kBAAkB,GAAqB;IAClD,IAAI,EAAE,cAAc;IACpB,KAAK,EAAE,CAAC,oBAAoB,CAAC;CAC9B,CAAC"}

package/dist/src/capabilities/capabilities/types.js

@@ -0,0 +1,11 @@
+/**
+ * Types for the `capabilities` orientation tool.
+ *
+ * The catalog is DERIVED from the live grammar (`emitSurface`) plus an authored
+ * hint table — never a hand-maintained tool list — so it cannot drift from the
+ * real surface (the exact failure mode of the old shell's `TOOL_CATALOG`, which
+ * still named retired tools). See {@link ToolHint} + `hints.ts` for the one
+ * authored input, and `catalog.ts` for the derivation.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/capabilities/capabilities/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/capabilities/capabilities/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/src/capabilities/colophon/collectColophon.js

@@ -0,0 +1,83 @@
+/**
+ * Collect the `colophon` payload — the verb's run body (lazily imported).
+ *
+ * STORELESS: it resolves the EFFECTIVE capability modules exactly as a real
+ * command would — through `loadEffectiveModules`, so a story declared by a
+ * PACKAGE the active pack carries surfaces its colophon here too, not only a
+ * config-declared one. It never boots the triple store, so the
+ * storeless-guarantee spy still sees `store.booted === false`. The static
+ * import of the validated distribution config (`config/defaults.js`) is safe
+ * here because this module sits behind the verb's dynamic `import()` — it
+ * never lands on the `--help`/`__complete` fast path.
+ *
+ * The registry is reached through a RUNTIME dynamic `import("../index.js")`
+ * inside this async body — never a static import — so the static
+ * `index → colophonModule → index` cycle can never form. Do NOT "clean it up"
+ * into a static import.
+ */
+import { BIN_NAME } from "../../constants.js";
+import distribution from "../../kernel/config/defaults.js";
+/**
+ * Assemble the colophon data for the current runtime.
+ *
+ * THE DOMAIN'S STORY WINS. A colophon answers "what am I working with", and
+ * once a domain is configured the answer is the domain — so the domain
+ * sections are the whole output, and the toolchain's own section does not
+ * ride in front of them. The toolchain section is the answer only when no
+ * domain has one: a fresh install, or a distribution that ships no story.
+ * Reading it the other way round put a paragraph about this program's
+ * architecture above the thing the user actually asked about, every time.
+ *
+ * Neither section is authored here. The toolchain half is the distribution
+ * config's `colophon` field (narrative plus condensed summary), rendered under
+ * the distribution's own name — a fork edits its config, never this module —
+ * and the domain half is each active pack's declared `colophon`. The
+ * `kind: "pragma"` value is a frozen JSON discriminant (wire compatibility),
+ * not the distribution's name.
+ *
+ * With neither declared, the payload is empty and the formatter's empty state
+ * says so, rather than the command printing nothing and leaving the reader to
+ * guess whether that is an answer or a failure.
+ *
+ * @param runtime - The per-invocation runtime.
+ * @returns The storeless colophon payload: every active pack/domain that
+ *   declares a `colophon`, or the distribution's own section when none does.
+ * @note Impure — reads the config layers (never boots the store).
+ */
+export async function collectColophon(runtime) {
+    const { loadEffectiveModules } = await import("../../kernel/packs/collect.js");
+    const { capabilities } = await import("../index.js");
+    let modules = capabilities;
+    try {
+        modules = (await loadEffectiveModules(capabilities, runtime.cwd)).modules;
+    }
+    catch {
+        // A bad config story is surfaced by the real commands; the colophon degrades
+        // to the static modules rather than failing the narrative. (A bad PACKAGE
+        // story never throws — it is dropped and reported by doctor.)
+    }
+    const sections = [];
+    for (const module of modules) {
+        if (module.colophon) {
+            sections.push({
+                kind: "pack",
+                title: module.name,
+                markdown: module.colophon,
+                source: `pack:${module.name}`,
+            });
+        }
+    }
+    if (sections.length === 0 && distribution.colophon) {
+        sections.push({
+            kind: "pragma",
+            title: BIN_NAME,
+            markdown: distribution.colophon.markdown,
+            ...(distribution.colophon.summary === undefined
+                ? {}
+                : { summary: distribution.colophon.summary }),
+            source: "built-in",
+        });
+    }
+    return { sections };
+}
+//# sourceMappingURL=collectColophon.js.map

package/dist/src/capabilities/colophon/collectColophon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectColophon.js","sourceRoot":"","sources":["../../../../src/capabilities/colophon/collectColophon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,YAAY,MAAM,iCAAiC,CAAC;AAK3D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAsB;IAEtB,MAAM,EAAE,oBAAoB,EAAE,GAAG,MAAM,MAAM,CAC3C,+BAA+B,CAChC,CAAC;IACF,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IAErD,IAAI,OAAO,GAAgC,YAAY,CAAC;IACxD,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,MAAM,oBAAoB,CAAC,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;IAC5E,CAAC;IAAC,MAAM,CAAC;QACP,6EAA6E;QAC7E,0EAA0E;QAC1E,8DAA8D;IAChE,CAAC;IAED,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,MAAM;gBACZ,KAAK,EAAE,MAAM,CAAC,IAAI;gBAClB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,MAAM,EAAE,QAAQ,MAAM,CAAC,IAAI,EAAE;aAC9B,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,YAAY,CAAC,QAAQ,EAAE,CAAC;QACnD,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,QAAQ;YACf,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,QAAQ;YACxC,GAAG,CAAC,YAAY,CAAC,QAAQ,CAAC,OAAO,KAAK,SAAS;gBAC7C,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YAC/C,MAAM,EAAE,UAAU;SACnB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,CAAC;AACtB,CAAC"}

package/dist/src/capabilities/colophon/colophon.render.js

@@ -0,0 +1,59 @@
+/**
+ * Formatters for `pragma colophon` — plain (styled Markdown), llm (condensed
+ * Markdown passthrough), json (the structured envelope). Pure and dependency-
+ * light: the plain path routes through the `chalk`-only {@link
+ * renderMarkdownToTerminal}; there is NO Ink here.
+ *
+ * The section title is composed as an H1 (`# <title>`) and fed through the ONE
+ * styler, so all heading styling lives in a single place and the authored body
+ * (which carries no leading H1) is never double-titled.
+ *
+ * The formatters render whatever sections the collector hands them and decide
+ * nothing about which sections exist — that choice (the domain's story, or the
+ * toolchain's when no domain tells one) belongs to the collector, and keeping
+ * it there is what lets these stay pure.
+ */
+import { BIN_NAME } from "../../constants.js";
+import { defaultStyle } from "../../kernel/render/style.js";
+import { renderMarkdownToTerminal } from "./markdownTerminal.js";
+/**
+ * The zero-section empty state: nothing declares a colophon — no active pack,
+ * and no story from the distribution itself. Blank output would read as a
+ * broken command, so say what is missing and name the command that fixes it.
+ * Like every empty state it goes to stderr with exit 0 (a calm success), so a
+ * script reading stdout still reads nothing.
+ */
+const EMPTY_NOTICE = `No colophon declared. A colophon comes from an active pack — build the store with \`${BIN_NAME} sources update\`.`;
+/** Render one section (title as H1 + body) as styled terminal Markdown. */
+function plainSection(section, style) {
+    return renderMarkdownToTerminal(`# ${section.title}\n\n${section.markdown}`, style);
+}
+/** Render one section as condensed Markdown for `--format llm` (summary preferred). */
+function llmSection(section) {
+    return `## ${section.title}\n\n${section.summary ?? section.markdown}`;
+}
+export const colophonFormatters = {
+    plain(data) {
+        // Resolve the TTY decision ONCE (impure: reads stdout.isTTY + chalk level),
+        // then render every section through the same inert-off-a-TTY styler.
+        const style = defaultStyle();
+        return data.sections
+            .map((section) => plainSection(section, style))
+            .join("\n\n");
+    },
+    llm(data) {
+        // llm returns before the dispatcher's empty-state routing, so the
+        // condensed form carries its own zero-section line (the same shape the
+        // other empty states use) rather than handing an agent zero bytes.
+        if (data.sections.length === 0)
+            return `_${EMPTY_NOTICE}_`;
+        return data.sections.map(llmSection).join("\n\n");
+    },
+    json(data) {
+        return JSON.stringify(data);
+    },
+    // Zero sections: the dispatcher routes this to stderr (exit 0) so plain
+    // stdout stays empty; llm/json keep their own empty shapes.
+    emptyNotice: (data) => data.sections.length === 0 ? EMPTY_NOTICE : undefined,
+};
+//# sourceMappingURL=colophon.render.js.map

package/dist/src/capabilities/colophon/colophon.render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colophon.render.js","sourceRoot":"","sources":["../../../../src/capabilities/colophon/colophon.render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAoB,MAAM,8BAA8B,CAAC;AAE9E,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAGjE;;;;;;GAMG;AACH,MAAM,YAAY,GAAG,uFAAuF,QAAQ,oBAAoB,CAAC;AAEzI,2EAA2E;AAC3E,SAAS,YAAY,CAAC,OAAwB,EAAE,KAAkB;IAChE,OAAO,wBAAwB,CAC7B,KAAK,OAAO,CAAC,KAAK,OAAO,OAAO,CAAC,QAAQ,EAAE,EAC3C,KAAK,CACN,CAAC;AACJ,CAAC;AAED,uFAAuF;AACvF,SAAS,UAAU,CAAC,OAAwB;IAC1C,OAAO,MAAM,OAAO,CAAC,KAAK,OAAO,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;AACzE,CAAC;AAED,MAAM,CAAC,MAAM,kBAAkB,GAA6B;IAC1D,KAAK,CAAC,IAAI;QACR,4EAA4E;QAC5E,qEAAqE;QACrE,MAAM,KAAK,GAAG,YAAY,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC,QAAQ;aACjB,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;aAC9C,IAAI,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;IAED,GAAG,CAAC,IAAI;QACN,kEAAkE;QAClE,uEAAuE;QACvE,mEAAmE;QACnE,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,YAAY,GAAG,CAAC;QAC3D,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,CAAC,IAAI;QACP,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,wEAAwE;IACxE,4DAA4D;IAC5D,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CACpB,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS;CACxD,CAAC"}

package/dist/src/capabilities/colophon/colophon.verb.js

@@ -0,0 +1,43 @@
+/**
+ * The `colophon` verb spec (noun `colophon`, self-verb).
+ *
+ * `run` is a lazy thunk: it dynamic-imports the collector, so building the
+ * command tree (help, completion, surface emit) reads this spec without pulling
+ * the config reader or the registry onto the fast path — identical to
+ * `infoVerb` / `doctorVerb` / `capabilitiesVerb`.
+ */
+import { BIN_NAME } from "../../constants.js";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import { colophonFormatters } from "./colophon.render.js";
+const colophonVerb = {
+    path: ["colophon"],
+    summary: "Narrate how the active domain is made.",
+    doc: `Storeless — the colophon each active pack declares for its domain. With no pack telling a story, it prints the one ${BIN_NAME} declares for itself instead; with neither, it says so. Also available as a condensed Markdown narration for agents, or as a structured JSON projection of the sections.`,
+    params: [],
+    output: { formatters: colophonFormatters },
+    examples: [
+        {
+            cmd: `${BIN_NAME} colophon`,
+            note: "the active domain's story",
+        },
+        {
+            cmd: `${BIN_NAME} colophon --format llm`,
+            note: "condensed Markdown for agents",
+        },
+    ],
+    capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: {
+            expose: true,
+            annotations: { readOnlyHint: true, openWorldHint: false },
+        },
+    },
+    run: (_params, runtime) => import("./collectColophon.js").then((m) => m.collectColophon(runtime)),
+};
+/** The `colophon` capability module (a single storeless self-verb). */
+export const colophonModule = {
+    name: "colophon",
+    verbs: [asVerb(colophonVerb)],
+};
+//# sourceMappingURL=colophon.verb.js.map

package/dist/src/capabilities/colophon/colophon.verb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colophon.verb.js","sourceRoot":"","sources":["../../../../src/capabilities/colophon/colophon.verb.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAErD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,MAAM,YAAY,GAAoD;IACpE,IAAI,EAAE,CAAC,UAAU,CAAC;IAClB,OAAO,EAAE,wCAAwC;IACjD,GAAG,EAAE,sHAAsH,QAAQ,0KAA0K;IAC7S,MAAM,EAAE,EAAE;IACV,MAAM,EAAE,EAAE,UAAU,EAAE,kBAAkB,EAAE;IAC1C,QAAQ,EAAE;QACR;YACE,GAAG,EAAE,GAAG,QAAQ,WAAW;YAC3B,IAAI,EAAE,2BAA2B;SAClC;QACD;YACE,GAAG,EAAE,GAAG,QAAQ,wBAAwB;YACxC,IAAI,EAAE,+BAA+B;SACtC;KACF;IACD,UAAU,EAAE;QACV,UAAU,EAAE,KAAK;QACjB,OAAO,EAAE,KAAK;QACd,GAAG,EAAE;YACH,MAAM,EAAE,IAAI;YACZ,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;SAC1D;KACF;IACD,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CACxB,MAAM,CAAC,sBAAsB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;CACzE,CAAC;AAEF,uEAAuE;AACvE,MAAM,CAAC,MAAM,cAAc,GAAqB;IAC9C,IAAI,EAAE,UAAU;IAChB,KAAK,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;CAC9B,CAAC"}

package/dist/src/capabilities/colophon/index.js

@@ -0,0 +1,5 @@
+/**
+ * The `colophon` capability barrel.
+ */
+export { colophonModule } from "./colophon.verb.js";
+//# sourceMappingURL=index.js.map

package/dist/src/capabilities/colophon/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/capabilities/colophon/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}