@letterstory/cli 0.35.0 → 0.36.1

package/README.md

@@ -245,6 +245,34 @@ letterstory onboarding status
 letterstory onboarding step --complete connect_domain
 ```
 
+### Offerings — one org, many products
+
+Context is layered **org → offering → collection**. An offering is anything the org would
+name when recommending it ("use Lettershred"). Each layer stores only what it overrides: an
+omitted field inherits, and `--reset <field>` puts one back to inheriting. Stances, avoid
+topics and blocked mentions **add** across layers (a collection's stances lead in prompts);
+priority topics (`--topic`) **replace** the inherited list, so a product never picks up its
+siblings' focus.
+
+```bash
+letterstory offerings list
+letterstory offerings create lettershred --name Lettershred --link https://lettershred.com \
+  --one-liner "Removes AI watermarks from text" --stance "Detection is an arms race" --topic "AI watermarks"
+letterstory offerings update <offering-id> --reset priority_topics      # inherit the org's focus again
+letterstory offerings competitor <offering-id> --competitor <competitor-domain-id> --stance avoid
+
+# A collection publishes as its primary offering and may mention the others it lists.
+letterstory offerings set-collection <collection-id> --primary <offering-id> --also <other-id>:0.5
+letterstory offerings set-collection <collection-id> --none               # the org itself again
+
+# Why is this collection writing what it's writing? (every field + the layer that set it)
+letterstory offerings collection <collection-id>
+letterstory offerings collection-context <collection-id> --stance "…" --avoid "pricing" --framing "…"
+
+# The planner picks an offering per topic; override one pick (or --offering none to clear).
+letterstory offerings topic <topic-id> --offering <offering-id>
+```
+
 ### One-shot domain onboarding
 
 A bare company domain in, a fully-configured organization out — as ONE durable job that
@@ -494,6 +522,22 @@ letterstory templates update <template-id> --angle "…"   # unset fields keep t
 letterstory templates delete <template-id> --yes   # bound seers fall back to defaults
 ```
 
+Primitive compositions (a named bundle of kernel/shredder/template/seer references —
+`docs/formats/compositions.md`; not a primitive, no endpoint or run. Needs
+`composition:read` / `composition:write`):
+
+```bash
+letterstory compositions list
+letterstory compositions create --name "Regulation-watch site kit" \
+  --content '{"kernel_family":"Cedar","shred":true,"template_key":"tmpl_howto"}' \
+  --phantom '{"theme":"gazette"}' \
+  --seer '{"name":"AI regulation watch","provider":"regulation_change","mode":"auto","config":{"query":"AI regulation"}}'
+letterstory compositions resolve comp_9f1a2b3c4d5e     # preview, read-only — costs nothing
+letterstory compositions update <composition-id> --clear-seer
+letterstory compositions delete <composition-id> --yes  # non-destructive to phantoms already built from it
+letterstory phantom create --name "EU AI Act Weekly" --composition '{"key":"comp_9f1a2b3c4d5e"}'
+```
+
 ## Cover images
 
 Which image model draws a post's cover is a CLI decision, not a UI-only one. `variants`

package/lib/cli.mjs

@@ -37,15 +37,17 @@ import {
 	cmdOnboard,
 	cmdSeers,
 	cmdTemplates,
+	cmdCompositions,
 	cmdShredder,
 	cmdLede,
 	cmdLandings,
 	cmdAdmin,
 	cmdFeedback,
+	cmdOfferings,
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.35.0";
+export const VERSION = "0.36.1";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -99,6 +101,8 @@ const BOOLEAN_FLAGS = new Set([
 	"clear-topics",
 	"clear-stances",
 	"clear-avoid",
+	// `offerings set-collection <id> --none` (the org itself is the subject again).
+	"none",
 ]);
 
 // Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
@@ -214,7 +218,7 @@ Content:
   posts unpublish <article-id>                       Unpublish an article
   posts delete --id <uuid> [--id <uuid> ...]         Permanently delete article(s)
   published list [--limit <n>] [--collection <uuid>] [--format html|md]
-  published show (--id <uuid> | --slug <slug>) [--format html|md]
+  published show (--id <uuid> | --slug <slug>) [--collection <id>] [--format html|md]
 
 Reviewers:
   reviewers standing list                             List the org's standing reviewers
@@ -290,6 +294,33 @@ Strategy & onboarding:
   directives propose <collection_id> <what you want>   Read one instruction back as concrete levers (applies nothing)
   directives apply <directive_id> --effect <id>...     Commit the levers you kept (or --reason to decline them all)
   directives off <directive_id> --reason <why>         Stop a live instruction; the reason is read back by the next proposal
+
+Offerings (context layered org → offering → collection; a layer sets only what it overrides):
+  offerings list                                       The org's offerings (things you'd name when recommending them)
+  offerings show <offering-id>                         One offering + its competitor overrides
+  offerings create <slug> [--name <n>] [--alias <a>…] [--link <url>] [--manifesto <text>|--manifesto-file <path>]
+                   [--one-liner <s>] [--is <fact>…] [--is-not <fact>…] [--descriptor <d>…] [--framing <f>]
+                   [--stance <s>…] [--topic <t>…] [--avoid <t>…] [--block <name>…] [--brand-profile <slug>]
+                   [--position <n>] [--detach <field>…] Omitted = inherit the org. Stances/avoid/block ADD to the
+                                                       org's; --topic (priority topics) REPLACES them. --detach
+                                                       stops inheriting a field (e.g. --detach stances = only
+                                                       this offering's own; --detach manifesto = none).
+  offerings update <offering-id> [same flags] [--slug <s>] [--reset <field>…]
+                                                       --reset puts a field back to inheriting. The identity
+                                                       flags (--one-liner/--is/--is-not/--descriptor) replace
+                                                       the whole identity.
+  offerings delete <offering-id> --yes                 Collections that published as it fall back to the org
+  offerings competitor <offering-id> (--competitor <competitor-domain-id> | --add-domain <d> --add-name <n>)
+                   --stance inherit|mention|avoid      This offering's stance on one competitor
+  offerings collection <collection-id>                 Why it writes what it writes: resolved context, the layer
+                                                       each field came from, and its mention set
+  offerings collection-context <collection-id> [--stance <s>…] [--topic <t>…] [--avoid <t>…] [--block <name>…]
+                   [--framing <f>] [--detach <field>…] [--reset <field>…]
+                                                       Edit the collection's own layer (its stances lead)
+  offerings set-collection <collection-id> (--primary <offering-id> [--also <offering-id>[:weight]…] | --none)
+                                                       What it may promote; the primary is what it publishes as
+  offerings topic <topic-id> --offering <offering-id|none>
+                                                       Override which offering one planner topic promotes
   probes list [--collection <uuid>] [--active-only] [--kind mention|citation|page]
   probes keep | pause | resume <probe_id>              Keep = protect an AI probe from rotation (no pause)
   probes edit <probe_id> <new question text>           Fix/sharpen a generated probe
@@ -534,6 +565,26 @@ Content templates (compose structures seers bind via config.template_key):
       for coverage in your own words and lets the engine pick the shape.
   templates delete <template-id> --yes
 
+Primitive compositions (named bundles of kernel/shredder/template/seer; not a primitive —
+no endpoint, no run. Applied on phantom create --composition '{"key":"..."}'):
+  compositions list                                     Org's compositions, by key
+  compositions show <composition-id>
+  compositions create --name <n> [--description <text>]
+      [--content '<json>'|--content-file <path>]        The collection's own content
+                                                       section (kernel_family, shred,
+                                                       shredder_endpoint_id, template_key,
+                                                       mention_degree, cover, visuals, verify).
+      [--phantom '<json>'|--phantom-file <path>]        Phantom-hosting defaults ({theme}).
+      [--seer '<json>'|--seer-file <path>]              Optional — the same shape
+                                                       'seers create' takes, minus
+                                                       collection/org (filled in once
+                                                       the phantom's collection exists).
+  compositions update <composition-id> [--name] [--description]
+      [--content ...] [--phantom ...] [--seer '<json>'|--seer-file <path>|--clear-seer]
+  compositions delete <composition-id> --yes
+  compositions resolve <composition-key>                Preview what create_phantom would
+                                                       merge in — read-only, costs nothing.
+
 Shredder (diversify content produced outside Letterstory; structure preserved):
   shredder list                                        Your shredder endpoints + run counts
   shredder create --name <n>                           New endpoint (returns a callable public id)
@@ -653,6 +704,7 @@ const CLIENT_COMMANDS = {
 	connectors: cmdConnectors,
 	strategy: cmdStrategy,
 	directives: cmdDirectives,
+	offerings: cmdOfferings,
 	probes: cmdProbes,
 	suggestions: cmdSuggestions,
 	onboarding: cmdOnboarding,
@@ -665,6 +717,7 @@ const CLIENT_COMMANDS = {
 	"phantom-onboard": cmdOnboard,
 	seers: cmdSeers,
 	templates: cmdTemplates,
+	compositions: cmdCompositions,
 	shredder: cmdShredder,
 	lede: cmdLede,
 	ledes: cmdLede,

package/lib/commands/compositions.mjs

@@ -0,0 +1,193 @@
+// `compositions` — Primitive Compositions, the FORMAT that bundles a kernel, a shredder, a
+// content template and a seer into one named, reusable reference (docs/formats/compositions.md).
+//
+// Not a primitive: no endpoint, no run, no balance. What it has instead of a door is a
+// RESOLUTION — `compositions resolve <key>` — and one consuming door, `phantom create
+// --composition '{"key":"..."}'` (see phantom.mjs), which resolves it exactly once and merges
+// it in. Authoring (list/show/create/update/delete) is CLI/REST parity work only; the mechanism
+// itself shipped with the format.
+
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.mjs";
+import { flagStr, requirePositional, printResult, ok, argsFromFlags } from "./shared.mjs";
+
+function readJsonFileFlag(flags, flag) {
+	const path = flagStr(flags[flag]);
+	if (path === undefined) return undefined;
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		throw new CliError(
+			`Could not read --${flag} ${path}: ${error instanceof Error ? error.message : String(error)}`
+		);
+	}
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new CliError(`--${flag} ${path} is not valid JSON.`);
+	}
+}
+
+function readJsonObjectFlag(flags, name) {
+	const inline = flagStr(flags[name]);
+	if (inline !== undefined) {
+		let parsed;
+		try {
+			parsed = JSON.parse(inline);
+		} catch (err) {
+			throw new CliError(`--${name} is not valid JSON: ${err.message}`);
+		}
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+			throw new CliError(`--${name} must be a JSON object`);
+		return parsed;
+	}
+	return readJsonFileFlag(flags, `${name}-file`);
+}
+
+// `--seer '<json>'`/`--seer-file <path>` sets it, `--clear-seer` sends null (the composition
+// stands up no seer), neither leaves it unchanged — same idiom as seers.mjs's clearableValue.
+function seerFromFlags(flags) {
+	if (flags["clear-seer"] === true) return null;
+	return readJsonObjectFlag(flags, "seer");
+}
+
+/**
+ * How this command sources its tool inputs — see `argsFromFlags` in shared.mjs and
+ * `scripts/parity-check.ts`. `content`/`phantom`/`seer` are each a JSON object (the collection
+ * content section, `{theme}`, and a create_seer-shaped spec, respectively) — the same
+ * `--flag '<json>'`/`--flag-file <path>` idiom `phantom create --composition` already uses,
+ * not decomposed field-by-field: they're bundles authored once and read back, not edited a
+ * field at a time from the CLI.
+ */
+export const ARGS = {
+	list_compositions: {},
+	get_composition: {
+		composition_id: { positional: 0, label: "composition-id", required: true },
+	},
+	resolve_composition: {
+		key: { positional: 0, label: "composition-key", required: true },
+	},
+	create_composition: {
+		name: { flag: "name", required: true },
+		description: "description",
+		content: { value: (flags) => readJsonObjectFlag(flags, "content") },
+		phantom: { value: (flags) => readJsonObjectFlag(flags, "phantom") },
+		seer: { value: (flags) => readJsonObjectFlag(flags, "seer") },
+	},
+	update_composition: {
+		composition_id: { positional: 0, label: "composition-id", required: true },
+		name: "name",
+		description: "description",
+		content: { value: (flags) => readJsonObjectFlag(flags, "content") },
+		phantom: { value: (flags) => readJsonObjectFlag(flags, "phantom") },
+		seer: { value: (flags) => seerFromFlags(flags) },
+	},
+	delete_composition: {
+		composition_id: { positional: 0, label: "composition-id", required: true },
+	},
+};
+
+export async function cmdCompositions(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return compositionsList(rest);
+		case "show":
+		case "get":
+			return compositionsShow(rest);
+		case "create":
+		case "new":
+			return compositionsCreate(rest);
+		case "update":
+			return compositionsUpdate(rest);
+		case "delete":
+		case "rm":
+			return compositionsDelete(rest);
+		case "resolve":
+			return compositionsResolve(rest);
+		default:
+			throw new CliError(
+				`Unknown compositions subcommand: ${sub ?? "(none)"}. Try: list, show, create, update, delete, resolve`
+			);
+	}
+}
+
+async function compositionsList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_compositions", {});
+	printResult(io, flags, result, (r) =>
+		(r.compositions ?? []).length
+			? (r.compositions ?? [])
+					.map((c) => `  ${c.key}  ${c.name}${c.seer ? " (+seer)" : ""} — id ${c.id}`)
+					.join("\n")
+			: "No compositions yet."
+	);
+	return 0;
+}
+
+async function compositionsShow(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "composition-id");
+	const result = await client.callTool("get_composition", argsFromFlags(ARGS.get_composition, flags, positionals));
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function compositionsCreate(ctx) {
+	const { client, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.create_composition, flags, []);
+	if (!args.name) throw new CliError("Missing required --name");
+	const result = await client.callTool("create_composition", args);
+	ok(ctx, `Composition created — key ${result.composition?.key}.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function compositionsUpdate(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "composition-id");
+	const result = await client.callTool(
+		"update_composition",
+		argsFromFlags(ARGS.update_composition, flags, positionals)
+	);
+	ok(ctx, "Composition updated.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function compositionsDelete(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "composition-id");
+	if (!flags.yes) {
+		throw new CliError(
+			"Non-destructive to phantoms already built from it (their resolved_from_composition becomes a name pointing at nothing). Re-run with --yes to delete."
+		);
+	}
+	const result = await client.callTool(
+		"delete_composition",
+		argsFromFlags(ARGS.delete_composition, flags, positionals)
+	);
+	ok(ctx, "Composition deleted.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+/**
+ * `compositions resolve <key>` — turn a composition into the sections `phantom create
+ * --composition` would merge in. Read-only, costs nothing. Preview a bundle, or build the
+ * sections yourself for a door that doesn't take `composition` directly yet (`collection
+ * config` / `seers create`).
+ */
+async function compositionsResolve(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	requirePositional(positionals, 0, "composition-key");
+	const result = await client.callTool(
+		"resolve_composition",
+		argsFromFlags(ARGS.resolve_composition, flags, positionals)
+	);
+	printResult(io, flags, result);
+	return 0;
+}

package/lib/commands/offerings.mjs

@@ -0,0 +1,423 @@
+// `offerings` — the org context hierarchy: org → offering → collection.
+//
+// An offering is anything the org would NAME when recommending it ("use Lettershred").
+// Each layer stores only what it overrides: an omitted field inherits, and
+// `--reset <field>` sends null (or an empty list), which puts the field back to
+// inheriting. Stances, avoid topics and blocked mentions ADD across layers; priority
+// topics REPLACE. Thin wrappers over the MCP tools, which call the same store functions
+// the app's /api/offerings routes do.
+
+import { CliError } from "../client.mjs";
+import {
+	flagStr,
+	flagNum,
+	flagList,
+	requirePositional,
+	printResult,
+	argsFromFlags,
+	refuseUnknownFlags,
+	readTextInput,
+	ok,
+} from "./shared.mjs";
+
+// What `--reset <field>` sends for each field: null where the schema reads null as
+// "inherit", an empty list where the field is additive (no additions = inherit).
+const OFFERING_RESETS = {
+	name: null,
+	aliases: null,
+	url: null,
+	manifesto: null,
+	identity: null,
+	default_framing: null,
+	priority_topics: null,
+	brand_profile_slug: null,
+	stances: [],
+	avoid_topics: [],
+	blocked_mentions: [],
+	detached_fields: [],
+};
+const COLLECTION_RESETS = {
+	priority_topics: null,
+	default_framing: null,
+	stances: [],
+	avoid_topics: [],
+	blocked_mentions: [],
+	detached_fields: [],
+};
+
+function resets(flags, allowed) {
+	const fields = flagList(flags.reset);
+	const unknown = fields.filter((f) => !(f in allowed));
+	if (unknown.length) {
+		throw new CliError(`--reset takes one of: ${Object.keys(allowed).join(", ")} (got ${unknown.join(", ")})`);
+	}
+	return new Set(fields);
+}
+
+const list = (flag) => (flags) => {
+	const v = flagList(flags[flag]);
+	return v.length ? v : undefined;
+};
+const str = (flag) => (flags) => flagStr(flags[flag]);
+
+// A field that `--reset <key>` can put back to inheriting. `read` is how the value is
+// taken from flags otherwise.
+function resettable(key, read, table) {
+	return {
+		value: (flags, positionals) => (flagList(flags.reset).includes(key) ? table[key] : read(flags, positionals)),
+	};
+}
+
+// identity is one field (nearest layer wins as a whole), so its four flags build one
+// object — and sending any of them replaces the whole identity.
+function readIdentity(flags) {
+	const out = {};
+	const oneLiner = flagStr(flags["one-liner"]);
+	if (oneLiner !== undefined) out.one_liner = oneLiner;
+	for (const [key, flag] of [
+		["is", "is"],
+		["is_not", "is-not"],
+		["descriptors", "descriptor"],
+	]) {
+		const v = flagList(flags[flag]);
+		if (v.length) out[key] = v;
+	}
+	return Object.keys(out).length ? out : undefined;
+}
+
+const offeringFields = (table) => ({
+	name: resettable("name", str("name"), table),
+	aliases: resettable("aliases", list("alias"), table),
+	url: resettable("url", str("link"), table),
+	manifesto: resettable("manifesto", (flags) => readTextInput(flags, "manifesto", "manifesto-file"), table),
+	identity: resettable("identity", readIdentity, table),
+	default_framing: resettable("default_framing", str("framing"), table),
+	stances: resettable("stances", list("stance"), table),
+	priority_topics: resettable("priority_topics", list("topic"), table),
+	avoid_topics: resettable("avoid_topics", list("avoid"), table),
+	blocked_mentions: resettable("blocked_mentions", list("block"), table),
+	brand_profile_slug: resettable("brand_profile_slug", str("brand-profile"), table),
+	// `--detach stances` = stop inheriting that field from the org (only this offering's
+	// own value, or none). `--reset detached_fields` = inherit everything again.
+	detached_fields: resettable("detached_fields", list("detach"), table),
+	position: { flag: "position", type: "num" },
+});
+
+// Flags the `value` sources above read (argsFromFlags can't list them for
+// refuseUnknownFlags, since a computed source names no single flag).
+const OFFERING_FIELD_FLAGS = [
+	"name",
+	"alias",
+	"link",
+	"manifesto",
+	"manifesto-file",
+	"one-liner",
+	"is",
+	"is-not",
+	"descriptor",
+	"framing",
+	"stance",
+	"topic",
+	"avoid",
+	"block",
+	"brand-profile",
+	"detach",
+	"reset",
+];
+
+// `--primary <id>` plus any `--also <id>[:weight]`; `--none` = the org itself.
+function readMentionSet(flags) {
+	if (flags.none === true) return [];
+	const primary = flagStr(flags.primary);
+	if (!primary) return undefined;
+	const also = flagList(flags.also).map((entry) => {
+		const [id, weight] = entry.split(":");
+		const out = { offering_id: id, is_primary: false };
+		if (weight !== undefined) out.weight = flagNum(weight);
+		return out;
+	});
+	return [{ offering_id: primary, is_primary: true }, ...also];
+}
+
+// How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.
+// `scripts/parity-check.ts` compares these keys against each tool's published input schema.
+export const ARGS = {
+	list_offerings: {},
+	get_offering: {
+		offering_id: { positional: 0, label: "offering-id", required: true },
+	},
+	create_offering: {
+		slug: { positional: 0, label: "slug", required: true },
+		// Nothing to reset on create: an omitted field already inherits.
+		...offeringFields({}),
+	},
+	update_offering: {
+		offering_id: { positional: 0, label: "offering-id", required: true },
+		slug: "slug",
+		...offeringFields(OFFERING_RESETS),
+	},
+	delete_offering: {
+		offering_id: { positional: 0, label: "offering-id", required: true },
+	},
+	set_offering_competitor: {
+		offering_id: { positional: 0, label: "offering-id", required: true },
+		competitor_domain_id: "competitor",
+		add: { object: { domain: "add-domain", name: "add-name" } },
+		mention_stance: { flag: "stance", required: true, enum: ["inherit", "mention", "avoid"] },
+	},
+	get_collection_context: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+	},
+	set_collection_context: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+		stances: resettable("stances", list("stance"), COLLECTION_RESETS),
+		priority_topics: resettable("priority_topics", list("topic"), COLLECTION_RESETS),
+		avoid_topics: resettable("avoid_topics", list("avoid"), COLLECTION_RESETS),
+		blocked_mentions: resettable("blocked_mentions", list("block"), COLLECTION_RESETS),
+		default_framing: resettable("default_framing", str("framing"), COLLECTION_RESETS),
+		detached_fields: resettable("detached_fields", list("detach"), COLLECTION_RESETS),
+	},
+	set_collection_offerings: {
+		collection_id: { positional: 0, label: "collection-id", required: true },
+		offerings: { value: readMentionSet },
+	},
+	set_topic_offering: {
+		topic_id: { positional: 0, label: "topic-id", required: true },
+		offering_id: {
+			value: (flags) => {
+				const v = flagStr(flags.offering);
+				if (v === undefined) throw new CliError("Missing required --offering <offering-id|none>");
+				return v === "none" ? null : v;
+			},
+		},
+	},
+};
+
+const USAGE = `Usage: offerings <list|show|create|update|delete|competitor|collection|collection-context|set-collection|topic>
+  offerings list
+  offerings show <offering-id>
+  offerings create <slug> [--name <n>] [--alias <a>…] [--link <url>] [--manifesto <text>|--manifesto-file <path>]
+                   [--one-liner <s>] [--is <fact>…] [--is-not <fact>…] [--descriptor <d>…] [--framing <f>]
+                   [--stance <s>…] [--topic <t>…] [--avoid <t>…] [--block <name>…] [--brand-profile <slug>] [--position <n>]
+  offerings update <offering-id> [same flags] [--slug <s>] [--reset <field>…]
+  offerings delete <offering-id> --yes
+  offerings competitor <offering-id> (--competitor <competitor-domain-id> | --add-domain <d> --add-name <n>)
+                   --stance inherit|mention|avoid
+  offerings collection <collection-id>
+  offerings collection-context <collection-id> [--stance <s>…] [--topic <t>…] [--avoid <t>…] [--block <name>…]
+                   [--framing <f>] [--reset <field>…]
+  offerings set-collection <collection-id> (--primary <offering-id> [--also <offering-id>[:weight]…] | --none)
+  offerings topic <topic-id> --offering <offering-id|none>`;
+
+export async function cmdOfferings(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "list":
+		case "ls":
+			return offeringsList(rest);
+		case "show":
+		case "get":
+			return offeringsShow(rest);
+		case "create":
+			return offeringsCreate(rest);
+		case "update":
+			return offeringsUpdate(rest);
+		case "delete":
+			return offeringsDelete(rest);
+		case "competitor":
+			return offeringsCompetitor(rest);
+		case "collection":
+			return offeringsCollection(rest);
+		case "collection-context":
+			return offeringsCollectionContext(rest);
+		case "set-collection":
+			return offeringsSetCollection(rest);
+		case "topic":
+			return offeringsTopic(rest);
+		default:
+			throw new CliError(USAGE);
+	}
+}
+
+const label = (o) => o.name ?? `${o.slug} (org name)`;
+
+function formatOffering(o) {
+	const lines = [`${o.id}  ${o.slug}  ${label(o)}`];
+	const set = (k, v) =>
+		v !== null && v !== undefined && (!Array.isArray(v) || v.length) && lines.push(`  ${k}: ${v}`);
+	set("url", o.url);
+	set("framing", o.default_framing);
+	set("one-liner", o.identity?.one_liner);
+	set("stances (+org)", o.stances?.join("; "));
+	set("priority topics (replaces org)", o.priority_topics?.join("; "));
+	set("avoid (+org)", o.avoid_topics?.join("; "));
+	set("never mention (+org)", o.blocked_mentions?.join("; "));
+	return lines.join("\n");
+}
+
+async function offeringsList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_offerings", argsFromFlags(ARGS.list_offerings, flags));
+	printResult(io, flags, result, (r) => {
+		const all = r.offerings ?? [];
+		if (!all.length) return "No offerings — the org itself is the subject everywhere.";
+		return all.map(formatOffering).join("\n\n");
+	});
+	return 0;
+}
+
+async function offeringsShow(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	const result = await client.callTool("get_offering", argsFromFlags(ARGS.get_offering, flags, positionals));
+	printResult(io, flags, result, (r) => {
+		const lines = [formatOffering(r.offering)];
+		for (const c of r.competitors ?? []) {
+			lines.push(
+				`  competitor ${c.name ?? c.competitor_domain_id}: ${c.mention_stance}${c.added_here ? " (only here)" : ""}`
+			);
+		}
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+async function offeringsCreate(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(
+		ctx,
+		ARGS.create_offering,
+		OFFERING_FIELD_FLAGS.filter((f) => f !== "reset")
+	);
+	const result = await client.callTool("create_offering", argsFromFlags(ARGS.create_offering, flags, positionals));
+	ok(ctx, `Created ${result.offering?.slug} (${result.offering?.id}).`);
+	printResult(io, flags, result, (r) => formatOffering(r.offering));
+	return 0;
+}
+
+async function offeringsUpdate(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.update_offering, OFFERING_FIELD_FLAGS);
+	resets(flags, OFFERING_RESETS);
+	const args = argsFromFlags(ARGS.update_offering, flags, positionals);
+	if (Object.keys(args).length === 1) throw new CliError("Nothing to update — pass a field flag or --reset <field>.");
+	const result = await client.callTool("update_offering", args);
+	ok(ctx, `Updated ${result.offering?.slug}.`);
+	printResult(io, flags, result, (r) => formatOffering(r.offering));
+	return 0;
+}
+
+async function offeringsDelete(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	const id = requirePositional(positionals, 0, "offering-id");
+	if (!flags.yes) {
+		io.error(`Re-run with --yes to confirm: ${ctx.bin} offerings delete ${id} --yes`);
+		return 1;
+	}
+	await client.callTool("delete_offering", argsFromFlags(ARGS.delete_offering, flags, positionals));
+	ok(ctx, "Offering deleted. Collections that published as it now fall back to the org.");
+	return 0;
+}
+
+async function offeringsCompetitor(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	// `add`'s nested flags aren't visible to refuseUnknownFlags (it reads top-level flags only).
+	refuseUnknownFlags(ctx, ARGS.set_offering_competitor, ["add-domain", "add-name"]);
+	const result = await client.callTool(
+		"set_offering_competitor",
+		argsFromFlags(ARGS.set_offering_competitor, flags, positionals)
+	);
+	ok(ctx, `Competitor ${result.competitor_domain_id}: ${result.mention_stance} for this offering.`);
+	if (flags.json) printResult(io, flags, result);
+	return 0;
+}
+
+function formatContext(c) {
+	const r = c.resolved;
+	const from = (field) => `  [${r.origin?.[field] ?? "org"}]`;
+	const lines = [
+		r.offering
+			? `Subject: ${r.offering.name ?? r.offering.slug} (offering ${r.offering.id})`
+			: "Subject: the org itself",
+		`name: ${r.name ?? "—"}${from("name")}`,
+	];
+	if (r.default_framing) lines.push(`framing: ${r.default_framing}${from("default_framing")}`);
+	if (r.stances.length) {
+		lines.push("stances (most targeted first):");
+		for (const s of r.stances) lines.push(`  - ${s.text}  [${s.origin}]`);
+	}
+	if (r.priority_topics.length)
+		lines.push(`priority topics${from("priority_topics")}: ${r.priority_topics.join("; ")}`);
+	if (r.avoid_topics.length) lines.push(`avoid: ${r.avoid_topics.join("; ")}`);
+	if (r.blocked_mentions.length) lines.push(`never mention: ${r.blocked_mentions.join("; ")}`);
+	lines.push("", "Mention set:");
+	if (!c.offerings.length) lines.push("  (none — the org is the subject)");
+	for (const m of c.offerings) {
+		lines.push(
+			`  ${m.is_primary ? "*" : " "} ${m.offering_id}  ${m.name ?? m.slug}${m.is_primary ? "" : `  weight ${m.weight}`}`
+		);
+	}
+	return lines.join("\n");
+}
+
+async function offeringsCollection(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	const result = await client.callTool(
+		"get_collection_context",
+		argsFromFlags(ARGS.get_collection_context, flags, positionals)
+	);
+	printResult(io, flags, result, (r) => formatContext(r.context));
+	return 0;
+}
+
+async function offeringsCollectionContext(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.set_collection_context, [
+		"stance",
+		"topic",
+		"avoid",
+		"block",
+		"framing",
+		"detach",
+		"reset",
+	]);
+	resets(flags, COLLECTION_RESETS);
+	const args = argsFromFlags(ARGS.set_collection_context, flags, positionals);
+	if (Object.keys(args).length === 1) throw new CliError("Nothing to update — pass a field flag or --reset <field>.");
+	const result = await client.callTool("set_collection_context", args);
+	ok(ctx, "Collection context saved.");
+	printResult(io, flags, result, (r) => formatContext(r.context));
+	return 0;
+}
+
+async function offeringsSetCollection(ctx) {
+	const { client, flags, positionals, io } = ctx;
+	refuseUnknownFlags(ctx, ARGS.set_collection_offerings, ["primary", "also", "none"]);
+	const args = argsFromFlags(ARGS.set_collection_offerings, flags, positionals);
+	if (!args.offerings) {
+		throw new CliError(
+			"Pass --primary <offering-id> (plus any --also <offering-id>), or --none for the org itself."
+		);
+	}
+	const result = await client.callTool("set_collection_offerings", args);
+	ok(ctx, args.offerings.length ? "Mention set saved." : "Cleared — the org is this collection's subject again.");
+	if (flags.json) printResult(io, flags, result);
+	return 0;
+}
+
+async function offeringsTopic(ctx) {
+	const { client, flags, positionals } = ctx;
+	refuseUnknownFlags(ctx, ARGS.set_topic_offering, ["offering"]);
+	const result = await client.callTool(
+		"set_topic_offering",
+		argsFromFlags(ARGS.set_topic_offering, flags, positionals)
+	);
+	ok(
+		ctx,
+		result.mention_offering_id
+			? `Topic now promotes ${result.mention_offering_id}.`
+			: "Override cleared — the topic falls back to the collection's primary offering."
+	);
+	if (flags.json) printResult(ctx.io, flags, result);
+	return 0;
+}

package/lib/commands/posts.mjs

@@ -141,7 +141,14 @@ async function publishedShow(ctx) {
 	const id = flagStr(flags.id);
 	const slug = flagStr(flags.slug);
 	if (id === undefined && slug === undefined) throw new CliError("Pass --id or --slug.");
-	const args = compact({ article_id: id, slug, format: flagStr(flags.format) });
+	// --collection scopes a slug lookup to one collection (slugs are only unique per
+	// collection once an org runs several blogs).
+	const args = compact({
+		article_id: id,
+		slug,
+		collection_id: flagStr(flags.collection),
+		format: flagStr(flags.format),
+	});
 	const result = await client.callTool("get_published", args);
 	printResult(io, flags, result);
 	return 0;

package/lib/commands.mjs

@@ -23,6 +23,7 @@ export * from "./commands/insights.mjs";
 export * from "./commands/covers.mjs";
 export * from "./commands/arena.mjs";
 export * from "./commands/templates.mjs";
+export * from "./commands/compositions.mjs";
 export * from "./commands/autopen.mjs";
 export * from "./commands/kernel.mjs";
 export * from "./commands/lede.mjs";
@@ -31,5 +32,6 @@ export * from "./commands/onboard.mjs";
 export * from "./commands/seers.mjs";
 export * from "./commands/shredder.mjs";
 export * from "./commands/landings.mjs";
+export * from "./commands/offerings.mjs";
 export * from "./commands/admin.mjs";
 export * from "./commands/feedback.mjs";

package/lib/documents.mjs

@@ -59,6 +59,8 @@ export const DOCUMENT_FLAG_PAIRS = [
 	["body", "file"],
 	["brief", "brief-file"],
 	["text", "text-file"],
+	// An offering's (or the company's) manifesto is prose — a PDF or a .docx is fair game.
+	["manifesto", "manifesto-file"],
 ];
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.35.0",
+	"version": "0.36.1",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",