@warmhub/cli 0.129.0 → 0.131.0

package/dist/wh.js

@@ -17780,11 +17780,6 @@ var RESERVED_COLLECTION_SHAPE_NAMES = [
   ...BUILTIN_SHAPE_NAMES,
   ...RETIRED_COLLECTION_SHAPE_NAMES
 ];
-var COLLECTION_CLASSIFICATION_SHAPE_NAMES = [
-  "Collection",
-  ...RESERVED_COLLECTION_SHAPE_NAMES
-];
-var COLLECTION_CLASSIFICATION_SHAPE_NAME_SET = new Set(COLLECTION_CLASSIFICATION_SHAPE_NAMES);
 function isBuiltinCollectionShape(name) {
   return BUILTIN_SHAPE_NAMES.includes(name);
 }
@@ -18029,6 +18024,14 @@ var COMMIT_OPERATION_KINDS = [
   "assertion",
   "collection"
 ];
+var READ_KINDS = ["thing", "shape"];
+var LEGACY_COLLECTION_READ_KIND = "collection";
+var LEGACY_ASSERTION_READ_KIND = "assertion";
+var READ_KIND_FILTERS = [
+  ...READ_KINDS,
+  LEGACY_COLLECTION_READ_KIND,
+  LEGACY_ASSERTION_READ_KIND
+];
 function splitLocalPath(name) {
   const idx = name.indexOf("/");
   if (idx === -1)
@@ -24632,6 +24635,11 @@ var VALID_PRIMITIVE_TYPES = new Set([
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function dataAboutWref(data) {
+  if (!isPlainObject(data))
+    return;
+  return typeof data.about === "string" ? data.about : undefined;
+}
 var STRING_CONSTRAINT_KEYS = new Set([
   "minLength",
   "maxLength",
@@ -40652,7 +40660,7 @@ function compareUnsignedUtf8(left, right) {
 var CHECKPOINT_CHUNK_BYTE_LIMIT = 67108864;
 var CHECKPOINT_PART_DIGITS = 10;
 var CHECKPOINT_FORMAT = "warmhub-repository-checkpoint";
-var CHECKPOINT_FORMAT_VERSION = 3;
+var CHECKPOINT_FORMAT_VERSION = 4;
 var CHECKPOINT_MANIFEST_NAME = "repository-checkpoint.json";
 var checkpointSha256Schema = exports_external.string().regex(/^[0-9a-f]{64}$/);
 var nonnegativeSafeIntegerSchema = exports_external.number().int().nonnegative();
@@ -40696,14 +40704,13 @@ var checkpointRowSchema = exports_external.discriminatedUnion("kind", [
   checkpointRowBaseSchema.extend({
     kind: exports_external.literal("thing"),
     shapeName: exports_external.string().min(1),
-    collections: checkpointCollectionsSchema.optional()
-  }).strict(),
-  checkpointRowBaseSchema.extend({
-    kind: exports_external.literal("assertion"),
-    shapeName: exports_external.string().min(1),
-    aboutWref: pinnedWrefSchema,
-    affirmedWrefs: affirmedWrefsSchema
-  }).strict()
+    collections: checkpointCollectionsSchema.optional(),
+    aboutWref: pinnedWrefSchema.optional(),
+    affirmedWrefs: affirmedWrefsSchema.optional()
+  }).strict().refine((row) => row.aboutWref === undefined === (row.affirmedWrefs === undefined), {
+    message: "A checkpoint row carries aboutWref and affirmedWrefs together or not at all",
+    path: ["affirmedWrefs"]
+  })
 ]);
 var checkpointManifestChunkSchema = exports_external.object({
   part: nonnegativeSafeIntegerSchema,
@@ -40880,8 +40887,9 @@ function validateCheckpointStreamRow(state, input) {
   const row = input;
   assertCheckpointText(row.wref);
   assertCheckpointText(row.durableId);
-  if (row.kind === "assertion")
+  if (row.kind !== "shape" && row.aboutWref !== undefined) {
     assertCheckpointText(row.aboutWref);
+  }
   const rowShapeName = row.kind === "shape" ? row.wref : row.shapeName;
   if (rowShapeName !== state.shapeName) {
     throw new Error("Checkpoint row is grouped under the wrong Shape stream");
@@ -40915,16 +40923,12 @@ function addOneSafe(value) {
   return next;
 }
 // ../../packages/rules/src/repository-export/types.ts
-var REPOSITORY_EXPORT_FORMAT_VERSION = 4;
+var REPOSITORY_EXPORT_FORMAT_VERSION = 5;
 var REPOSITORY_EXPORT_MEDIA_TYPE = "application/x-ndjson";
 var repositoryExportSha256Schema = exports_external.string().regex(/^[0-9a-f]{64}$/);
 var nonnegativeSafeIntegerSchema2 = exports_external.number().int().nonnegative();
 var positiveSafeIntegerSchema2 = exports_external.number().int().positive();
-var REPOSITORY_EXPORT_ROW_KINDS = [
-  "shape",
-  "thing",
-  "assertion"
-];
+var REPOSITORY_EXPORT_ROW_KINDS = ["shape", "thing"];
 var REPOSITORY_EXPORT_MODES = ["heads", "ops"];
 var repositoryExportShapeCertificateSchema = exports_external.string().regex(/^[^\r\n]+@v[1-9]\d*(?![\s\S])/, "Shape certificate must be a pinned wref");
 var repositoryExportReferenceSchema = exports_external.object({
@@ -40980,15 +40984,13 @@ var activeRowSchema = exports_external.discriminatedUnion("kind", [
     ...activeRowFields,
     kind: exports_external.literal("thing"),
     shapes: shapesSchema,
-    collections: repositoryExportCollectionsSchema.optional()
-  }).strict(),
-  exports_external.object({
-    ...activeRowFields,
-    kind: exports_external.literal("assertion"),
-    shapes: shapesSchema,
-    about: repositoryExportReferenceSchema,
-    affirmed: affirmedSchema
-  }).strict()
+    collections: repositoryExportCollectionsSchema.optional(),
+    about: repositoryExportReferenceSchema.optional(),
+    affirmed: affirmedSchema.optional()
+  }).strict().refine((row) => row.about === undefined === (row.affirmed === undefined), {
+    message: "An export row carries `about` and `affirmed` together or not at all",
+    path: ["affirmed"]
+  })
 ]);
 var tombstoneRowSchema = exports_external.object({
   ...rowEnvelopeFields,
@@ -41691,6 +41693,9 @@ var COMPONENT_INSTALL_FIELDS = {
   "updatedAt?": "string"
 };
 var COMPONENT_CONFIG_FIELDS = {};
+var ASSERTION_FIELDS = {
+  about: "wref"
+};
 var SYSTEM_MANIFEST = {
   component: {
     id: SYSTEM_COMPONENT_ID,
@@ -41704,7 +41709,8 @@ var SYSTEM_MANIFEST = {
     { name: "Arc", ...COLLECTION_V2_SHAPE_DEFS.Arc },
     { name: "Bond", ...COLLECTION_V2_SHAPE_DEFS.Bond },
     { name: "Set", ...COLLECTION_V2_SHAPE_DEFS.Set },
-    { name: "List", ...COLLECTION_V2_SHAPE_DEFS.List }
+    { name: "List", ...COLLECTION_V2_SHAPE_DEFS.List },
+    { name: "Assertion", fields: ASSERTION_FIELDS }
   ],
   credentials: [],
   subscriptions: [],
@@ -41718,7 +41724,8 @@ var SYSTEM_MANIFEST = {
         "Arc",
         "Bond",
         "Set",
-        "List"
+        "List",
+        "Assertion"
       ]
     }
   },
@@ -41745,7 +41752,12 @@ var SYSTEM_COMPONENT = {
     { name: "Arc", ...COLLECTION_V2_SHAPE_DEFS.Arc },
     { name: "Bond", ...COLLECTION_V2_SHAPE_DEFS.Bond },
     { name: "Set", ...COLLECTION_V2_SHAPE_DEFS.Set },
-    { name: "List", ...COLLECTION_V2_SHAPE_DEFS.List }
+    { name: "List", ...COLLECTION_V2_SHAPE_DEFS.List },
+    {
+      name: "Assertion",
+      fields: ASSERTION_FIELDS,
+      priorVersions: [{ fields: {} }]
+    }
   ]
 };
 
@@ -41753,6 +41765,7 @@ var SYSTEM_COMPONENT = {
 var SYSTEM_COMPONENTS = [
   SYSTEM_COMPONENT
 ];
+var SYSTEM_PROTECTED_SHAPES = SYSTEM_COMPONENT.shapes.filter((shape) => shape.installInfra !== true);
 var SYSTEM_INFRA_SHAPE_NAMES = new Set(SYSTEM_COMPONENTS.flatMap((entry) => entry.shapes.filter((shape) => shape.installInfra === true).map((shape) => shape.name)));
 function findSystemComponent(componentId) {
   return SYSTEM_COMPONENTS.find((entry) => entry.componentId === componentId);
@@ -43328,6 +43341,7 @@ function normalizeOptionalName(value) {
 }
 
 // ../../packages/sdk-ts/src/operation-normalize.ts
+var THING_ENVELOPE_ABOUT_MESSAGE = "thing add operation does not accept top-level 'about' — put the target in data.about, or use kind: 'assertion' for the deprecated envelope form";
 function toBackendStreamOperation(operation) {
   if (operation.expectedVersion !== undefined && operation.operation !== "revise" && operation.operation !== "retract" && operation.operation !== "reaffirm") {
     throw new Error("expectedVersion is only valid on revise, retract, or reaffirm operations — set an explicit operation discriminator");
@@ -43400,6 +43414,9 @@ function toBackendStreamOperation(operation) {
     };
   }
   const kind = inferOperationKind(operation);
+  if (kind === "thing" && "about" in operation && operation.about !== undefined) {
+    throw new Error(THING_ENVELOPE_ABOUT_MESSAGE);
+  }
   const skipExisting = "skipExisting" in operation ? operation.skipExisting : undefined;
   if (kind !== "collection" && (("type" in operation) && operation.type !== undefined || ("members" in operation) && operation.members !== undefined)) {
     throw new Error(`add operation '${operation.name ?? ""}' has collection fields but resolved kind '${kind}' — collection adds require both 'type' and 'members', or set kind: 'collection'`);
@@ -43414,10 +43431,11 @@ function toBackendStreamOperation(operation) {
     throw new Error("add operation requires a name");
   }
   if (kind === "assertion") {
-    if (!("about" in operation) || operation.about === undefined) {
-      throw new Error("assertion add operation requires 'about'");
+    const about = "about" in operation && operation.about !== undefined ? operation.about : dataAboutWref(operation.data);
+    if (about === undefined) {
+      throw new Error("assertion add operation requires 'about', on the envelope or as data.about");
     }
-    if (typeof operation.about !== "string") {
+    if (typeof about !== "string") {
       throw new Error(COLLECTION_ABOUT_REMOVED_MESSAGE);
     }
     if (operation.data === undefined) {
@@ -43427,7 +43445,7 @@ function toBackendStreamOperation(operation) {
       operation: "add",
       kind: "assertion",
       name: operation.name,
-      about: operation.about,
+      about,
       data: operation.data,
       ...operation.affirmedTargets ? { affirmedTargets: operation.affirmedTargets } : {},
       ...skipExisting === true ? { skipExisting } : {}
@@ -45411,7 +45429,7 @@ function createStreamingSubmissionHandle(input, deps) {
 // ../../packages/sdk-ts/package.json
 var package_default = {
   name: "@warmhub/sdk-ts",
-  version: "0.127.0",
+  version: "0.129.0",
   private: false,
   type: "module",
   description: "The TypeScript SDK for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -45450,6 +45468,7 @@ var package_default = {
   files: [
     "dist",
     "CHANGELOG.md",
+    "changelog.json",
     "README.md"
   ],
   publishConfig: {
@@ -45534,7 +45553,7 @@ function sdkVersionIsDevelopment(version2) {
 var SDK_VERSION = typeof __SDK_VERSION__ !== "undefined" ? __SDK_VERSION__ : package_default.version;
 
 // ../../packages/sdk-ts/src/write-compatibility.ts
-var MINIMUM_WRITE_CONTRACT_VERSION = 1;
+var MINIMUM_WRITE_CONTRACT_VERSION = 2;
 function clientUpgradeHint(name) {
   if (name === WARMHUB_CLI_CLIENT_NAME)
     return "Run: wh update --yes";
@@ -45582,6 +45601,7 @@ function clientCompatibilityFailure(capabilities, identity2) {
       hint: "Upgrade the WarmHub backend before retrying this write."
     };
   }
+  return;
 }
 function isProductionApiUrl(apiUrl, productionApiUrl) {
   try {
@@ -45991,7 +46011,7 @@ class WarmHubClient {
     if (sdkVersionIsDevelopment(this.clientIdentity.version) && isProductionApiUrl(this.apiUrl, DEFAULT_API_URL)) {
       return Promise.reject(clientIncompatible(`Development client ${this.clientIdentity.name}/${this.clientIdentity.version} cannot write to production.`, "Install a released WarmHub client artifact before writing to api.warmhub.ai."));
     }
-    if (sdkVersionIsDevelopment(this.clientIdentity.version) && !isProductionApiUrl(this.apiUrl, DEFAULT_API_URL)) {
+    if (sdkVersionIsDevelopment(this.clientIdentity.version) && this.clientIdentity.name !== WARMHUB_CLI_CLIENT_NAME) {
       return Promise.resolve();
     }
     return this.diagnostics.assertCompatible();
@@ -46901,12 +46921,15 @@ class WarmHubClient {
         throw toWarmHubError(error51);
       }
     },
-    revise: async (orgName, repoName, shapeName, newFields, opts) => {
-      const preflight = shapeDefinitionPreflightError(shapeName, {
+    revise: async (...args) => {
+      const [orgName, repoName, shapeName] = args;
+      const newFields = args.length === 5 ? args[3] : undefined;
+      const opts = args.length === 5 ? args[4] : args[3];
+      const preflight = newFields ? shapeDefinitionPreflightError(shapeName, {
         fields: newFields,
         ...opts.description !== undefined ? { description: opts.description } : {},
         ...opts.composes !== undefined ? { composes: opts.composes } : {}
-      }, "revise");
+      }, "revise") : undefined;
       if (preflight)
         throw new WarmHubError("VALIDATION_ERROR", preflight);
       try {
@@ -53178,7 +53201,7 @@ function renderHead(out, c, chars, result, org, repo, shape, kind) {
     if (item.validatedShapes?.length) {
       out(`    ${c.dim}validates:${c.reset} ${refList(c, item.validatedShapes, decorations)}`);
     }
-    if (item.kind === "assertion" && item.aboutWref) {
+    if (item.aboutWref) {
       out(`    ${c.dim}about:${c.reset} ${refDisplay(c, item.aboutWref, decorations)}`);
     }
     if (item.affirmedWrefs?.length) {
@@ -57379,6 +57402,17 @@ function identifyCommitSubmitStreamRow(row) {
 // ../../packages/warmhub-cli/src/domains/commit-submit-template.ts
 import { writeFile } from "node:fs/promises";
 var WRITE_TEMPLATE_KINDS = ["thing", "assertion"];
+function composesLocalAssertion(shapeData, org, repo) {
+  const composes = shapeData?.composes;
+  if (!Array.isArray(composes))
+    return false;
+  return composes.some((entry) => {
+    if (typeof entry !== "string")
+      return false;
+    const unversioned = entry.replace(/@(HEAD|v\d+)$/i, "");
+    return unversioned === "Assertion" || unversioned === `wh:${org}/${repo}/Assertion`;
+  });
+}
 async function readTemplateShape(ctx, org, repo, shapeName) {
   try {
     const shape = await ctx.client.shape.get(org, repo, shapeName);
@@ -57528,22 +57562,25 @@ var handleTemplate = async (ctx, { flags, args }) => {
     if (templateKind === "assertion") {
       aboutPlaceholder = flags.about ? parseCollectionAboutFlag(flags.about) : "Shape/FILL_IN";
     }
+    const composesAssertion = composesLocalAssertion(shapeData, org, repo);
+    const emittedKind = templateKind === "assertion" && composesAssertion ? "thing" : templateKind;
     const data = buildTemplateData(fields);
+    const emittedData = aboutPlaceholder && emittedKind === "thing" ? { ...data, about: aboutPlaceholder } : data;
     const affirmedTargetsPlaceholder = templateKind === "assertion" ? { affirmedTargets: [] } : {};
     for (let i = 0;i < count; i++) {
       const op = operationType === "add" ? {
         operation: "add",
-        kind: templateKind,
+        kind: emittedKind,
         name: `${shapeName}/${nameSuffix(i)}`,
-        ...aboutPlaceholder ? { about: aboutPlaceholder } : {},
-        data,
-        ...affirmedTargetsPlaceholder
+        ...aboutPlaceholder && emittedKind === "assertion" ? { about: aboutPlaceholder } : {},
+        data: emittedData,
+        ...emittedKind === "assertion" ? affirmedTargetsPlaceholder : {}
       } : {
         operation: "revise",
-        kind: templateKind,
+        kind: emittedKind,
         name: `${shapeName}/FILL_IN`,
-        data,
-        ...affirmedTargetsPlaceholder
+        data: emittedData,
+        ...emittedKind === "assertion" ? affirmedTargetsPlaceholder : {}
       };
       operations.push(op);
     }
@@ -63000,7 +63037,7 @@ var ORG_DOMAIN = defineDomain({
 });
 
 // ../../packages/warmhub-cli/src/domains/prime-content.md
-var prime_content_default = "# WarmHub CLI Context\n> **Context Recovery**: Run `wh prime` after compaction or new session\n\n## Environment\n{{REPO_LINE}}\n\n## Core Concepts\n- **Thing**: A named entity versioned by writes. **Assertion**: A thing that makes a shape-validated claim about another thing.\n- **Shape**: A thing defining data structure; every other thing has one. **Write**: One or more add/revise/retract operations with per-operation results.\n- **wref**: A reference to a thing. Local: `Player` (the shape) or `Player/alice` (a thing with that shape). Cross-repo: `wh:org/repo/Shape` or `wh:org/repo/Shape/name`.\n\n## Versioned Wrefs\n- `Shape` addresses the shape itself; `Shape/name` addresses a thing with that shape. `@vN` pins either.\n- Floating write refs to retracted targets fail; existing pinned versions remain valid.\n- Rename invalidates old spellings, including `@vN`; the new name resolves history.\n- Untyped wrefs accept any thing. `wref<T>` requires the target's shape to be `T`; a shape has no shape, so never satisfies it. `wref?` coalesces only `thing_absent`, never a missing shape.\n- Wref `binding`: `identity` follows the Thing, `versioned` pins.\n\n## Key Workflows\n\n**Write data** (discover shapes → scaffold ops → submit):\n```bash\nwh shape list --repo org/repo                             # list available shapes\nwh shape view ShapeName --repo org/repo                   # inspect fields\nwh shape template ShapeName -o ops.json --repo org/repo   # scaffold write ops (supports --kind assertion)\n# edit ops.json — fill FILL_IN placeholders — then:\nwh commit submit --file ops.json --dry-run --repo org/repo  # preview; remove --dry-run to submit\n# or single assertion (no file needed):\nwh assertion create --shape ShapeName --about Target/name --name my-assertion --data '{\"field\":1}' --repo org/repo\n# Relay failed operation details when present. Never hand-guess ops JSON — use `wh shape template <Shape>`.\n```\n\n**Read data:**\n```bash\nwh thing list --repo org/repo                 # all things at HEAD\nwh thing view Shape/name --repo org/repo      # inspect a thing\nwh thing query --shape MyShape --repo org/repo  # find things by shape\nwh thing about Shape --repo org/repo          # assertions about a shape\nwh assertion list --repo org/repo             # all assertions at HEAD\nwh thing history Shape/name --repo org/repo   # version history\n\n# Batch read — wh thing view is variadic (max 500 wrefs/call):\nwh thing view Player/alice Player/bob               # variadic positionals\nwh thing view --file wrefs.txt --json               # one wref per line\ncat wrefs.txt | wh thing view --format jsonl        # one JSON line per *deduped* requested wref\n```\n\n## Wref Quick Reference\n\nWrites use explicit names and wrefs. Untyped fields, collection members,\nassertion `about`, and committers accept any thing. Create a deterministic\ntarget before referencing it in the same commit.\n\n## Command Reference\n\n**Global flags**: `--repo`, `--format`, `--json`, `--live`\n### thing — Things\n- `wh thing list [--shape] [--kind] [--match] [--include-retracted]` — Current HEAD state\n- `wh thing view [<wref>...] [--file <path>] [--version] [--depth] [--include-retracted] [--data-mode auto|full]` — Thing details. Variadic (max 500). `--version` implies `--include-retracted`. Batch JSON returns `{ requested, items, missing }`; jsonl emits one row per deduped requested wref. Large Set/List bodies summarize by default; use `--data-mode full` for canonical collection JSON.\n- `wh thing history [wref] [--shape] [--about] [--include-retracted]` — Version history\n- `wh thing resolve <wref>` — Resolve a wref to its canonical thing identity\n- `wh thing create <name|Shape/name> (--data|--file) [--shape]` — Create\n- `wh thing revise <name> [--data] [--message] [--committer] [--expected-version]` — Revise (CONFLICT if HEAD≠n)\n- `wh thing retract <wref> -m <message> [--reason] [--kind] [--expected-version]` — Retract\n- `wh thing query [--shape] [--kind] [--about] [--match]` — Query by filters\n- `wh thing search <query> [--shape] [--kind] [--about] [--mode]` — Search text\n- `wh thing rename <Shape/oldName> <newName>` — Rename\n- `wh thing refs <wref> [--inbound] [--outbound] [--field]` — Show field references; use `wh thing about` for assertions about the target thing\n- `wh thing about <wref> [--shape] [--match] [--depth] [--resolve-collections] [--role from|to|ends] [--limit] [--include-retracted]` — Show assertions about the target identity; `--resolve-collections` expands bare/@HEAD/@ALL members, `--role` filters direction; not pinned @vN\n\n- `wh view evaluate VIEW [--limit N] [--cursor TOK] [--all]`\n### commit — Write operations\n- `wh commit submit [--ops|--file|--add|--revise|--retract] [--dry-run] [--skip-existing]` — Submit operations, or evaluate the complete bounded input without durable changes under `--dry-run`. JSONL preview emits one operation row per input plus one summary.\n- `wh shape template <shape> [shape2 ...] [--kind] [--operation add|revise|retract] [-o file]` — Generate sample ops\n\n### assertion — Assertion operations\n- `wh assertion list [--about wref] [--shape] [--match] [--include-retracted]` — Browse assertions\n- `wh assertion view <wref> [--version] [--include-retracted]` — Assertion details\n- `wh assertion create --shape <s> --name <n> --about <wref> [--data] [-m] [--committer]` — Create assertion\n- `wh assertion revise <wref> --data <json> [--message] [--committer]` — Revise assertion\n- `wh assertion retract <wref> -m <message> [--reason] [--committer] [--expected-version]` — Retract assertion\n- `wh assertion history <wref> [--include-retracted]` — Assertion history\n\n### shape — Shape management\n- `wh shape list [--match] [--include-retracted]` — List all shapes\n- `wh shape view <name> [--include-retracted]` — Shape details\n- `wh shape revise <name> (--fields|--file)`\n- `wh shape create <name> (--fields|--file)`\n- `wh shape retract <name> -m <message> [--reason] [--expected-version]` — Retract shape\n- `wh shape history <name> [--include-retracted]` — Shape history\n- `wh shape rename <oldName> <newName>` — Rename shape\n\n### repo — Repository management\n- `wh repo create <org/name> [--display-name] [--description] [--visibility]` — Create repo\n- `wh repo list [org]` — List repos\n- `wh repo view [org/repo]` — Repo details\n\n### org — Organization management\n- `wh org create <name> [--display-name]` — Create a new organization\n- `wh org view <name>` — View organization details (alias: info)\n- `wh org list` — List all organizations\n\n### sub — Subscription management\n- `wh sub create <name> [flags]` — Create a subscription\n- `wh sub view <name>` — View subscription details\n- `wh sub list` — List all subscriptions\n- `wh sub log <name>` — Tail subscription delivery feed\n- `wh sub attempts <runId>` — Show attempt history for a run\n- `wh sub pause <name>` — Pause a subscription\n- `wh sub resume <name>` — Resume a paused subscription\n- `wh sub bind <name> [--credentials]` — Bind a credential set to a subscription for webhook auth\n- `wh sub unbind <name>` — Remove credential binding from a subscription\n- `wh sub delete <name>` — Retire; name reserved\n\n### notifications — Action notification listing\n- `wh notifications [--limit] [--since]` — List repo-scoped action notifications\n\n### credential — Credential set management\n- `wh credential create <name> [--repo org/repo | --org org] [--scope] [--description]` — Create an empty credential set\n- `wh credential list [--repo org/repo | --org org]` — List credential sets accessible from a repo or org\n- `wh credential view <name> [--repo org/repo | --org org]` — View a credential set (key names only, no values)\n- `wh credential delete <name> [--repo org/repo | --org org]` — Delete a credential set and its Vault object\n- `wh credential set <setName> [<keyName>] [--repo org/repo | --org org] [--value]` — Set credential key(s). With `<keyName>`: single-key form (reads value from `--value` or stdin). Without `<keyName>`: batch form (reads JSON object from stdin, e.g. `{\"KEY\":\"val\"}`)\n- `wh credential unset <setName> <keyName> [--repo org/repo | --org org]` — Remove a key from a credential set\n- `wh credential audit <setName> [--repo org/repo | --org org]` — View audit log for a credential set\n- `wh credential revoke <setName> [--repo org/repo | --org org] [--reason]` — Revoke a credential set (blocks new binds and stops bound webhook deliveries)\n\n### component — Component management\n- `wh component validate <path>` — Validate package\n- `wh component install <org/name>` — Install a registered component\n- `wh component register <name> --org <org> --manifest <path> [flags]` — Register component identity\n- `wh component unregister <org/name>` — Remove a registered component identity\n- `wh component registry list --org <org>` — List registered components\n- `wh component registry view <org/name>` — View a registered component\n- `wh component registry update <org/name> [flags]` — Update a registered component\n- `wh component list` — List installed components\n- `wh component update <org/name>` — Update installed component\n- `wh component view <org/name>` — Show component details (alias: show)\n- `wh component doctor <org/name>` — Run component health checks\n- `wh component teardown <org/name>` — Pause component subscriptions\n\n### Getting More Info\n- `wh help` — help overview\n- `wh <domain>` — domain verbs\n- `wh <domain> <verb> --help` — verb flags and examples\n- `wh help --format json` — `CliSpecV2` (`schemaVersion: 2`): global/contextual/root tables and command overrides\n\n## Common Workflows\n\n**Explore a repo:**\n```bash\nwh thing list --repo org/repo             # see all things in HEAD\nwh thing view Shape/name --repo org/repo  # inspect a specific thing\nwh thing history Shape/name --repo org/repo # inspect version history\nwh thing about Shape/name                 # assertions about thing/shape\n```\n\n**Create an assertion** (most common write):\n```bash\n# --about takes an untyped target wref: Shape or Shape/name.\nwh assertion create --shape MyShape --about TargetShape/target-name \\\n  --name my-assertion --data '{\"field_a\":1,\"field_b\":\"value\"}' --repo org/repo\n# Output includes per-operation status; relay failures when present.\n```\n\n**Create via write entrypoint** (alternative, supports batches and streams):\n```bash\nwh commit submit --add my-item --shape MyShape --kind assertion \\\n  --about TargetShape/target-name --data '{\"field_a\":1}' --repo org/repo\n```\n\n**Batch write via file** (generate template → edit → submit):\n```bash\nwh shape template Hypothesis Evidence -o ops.json    # add --kind assertion --about TargetShape/name for assertions\n# edit ops.json — fill FILL_IN placeholders\nwh commit submit --file ops.json -m \"batch update\"   # submit all operations (bare `wh commit` is equivalent)\n# --file format: docs.warmhub.ai/cli-reference/commit-operations\n```\n\n**Bulk write (JSONL stream, >1k ops)** — one chunked stream beats per-record commits (~60× faster):\n```bash\nwh shape template MyShape -o ops.jsonl                          # one op per line (.jsonl)\nID=\"bulk-$(date +%s)\"   # caller id for chunk correlation\nwh commit submit --file ops.jsonl --stream-id \"$ID\" --chunk-size 5000 \\\n  --skip-existing --progress -m \"bulk ingest\" --repo org/repo\n# --chunk-size: ops per append chunk (default 1000, max 10000); chunk≈1 is ~60× slower\n# --skip-existing: skips already-written add ops (drops per-row read-before-write)\n# --stream-id identifies the submission but provides no receipt or resume.\n# After an outcome-unknown append, stop writes and reconcile attempted + unsent\n# work from a later verified checkpoint; never blindly replay revise/retract.\n```\n\n**Create collections:**\n```bash\nwh commit submit --add route --shape Arc --data '{\"from\":\"Location/a\",\"to\":\"Location/b\"}'\nwh assertion create --shape Supports --name route-support --about Arc/route --data '{\"confidence\":0.8}' --repo org/repo\n```\n\n**Modify data:**\n```bash\nwh thing revise Shape/name --data '{\"x\":5,\"y\":3}' -m \"update\" --repo org/repo\nwh thing retract Shape/old-item -m \"withdrawn\" --reason \"data feed contaminated\" --repo org/repo\n```\n\n**Query and filter:**\n```bash\nwh thing query --shape MyShape                       # by shape\nwh thing query --kind assertion --about Shape/name   # by kind + target\nwh thing history Shape/name --limit 10               # version history\n```\n\n## Built-in Content shape\n\nWarmHub repos expose three well-known content wrefs:\n- `Content/Readme`  — stored markdown for humans\n- `Content/Agents`  — stored markdown guidance for AI agents\n- `Content/LlmsTxt` — synthesized per-request sitemap (read-only)\n\nFetch via `wh repo content get --kind readme|agents|llms-txt`,\n`client.repo.getReadme/getAgents/getLlmsTxt`, MCP `warmhub_repo_content_get`,\nor raw HTTP `GET /{org}/{repo}/readme.md|agents.md|llms.txt`.\nSee `wh repo describe` → `additionalInformation` for the discovery field.\n\n## Query Discipline\n- Plan the repo, shapes, and wrefs you need before the first query.\n- Gather the needed facts from one repo before switching to another.\n- Do the queries first, then write one complete answer.\n\n## Agent Tips\n- **Always run commands for live data** — this context describes the CLI, not repo contents\n- **Before writing, discover wrefs** — run `wh thing list` or `wh shape list`\n- **Shape field types**: `string`, `number`, `boolean`, `wref`, arrays, optionals, nested objects\n- **Write commands return per-operation results** — relay failures and affected wrefs to the user\n- **Pass data inline** with `--data '{...}'` — do NOT create temp files\n- Add `--json` to any command for machine-readable JSON output\n- **Aliases teach canonical commands** — executing aliases emit a status hint; misleading lifecycle aliases reject and point to `retract`\n- Writes go through `wh commit submit` (or bare `wh commit`) or wrappers (`create`, `revise`, `retract`, `assertion create`). `retract` irreversibly withdraws an identity and creates a history entry.\n- Use `wh doctor` to check environment health\n";
+var prime_content_default = "# WarmHub CLI Context\n> **Context Recovery**: Run `wh prime` after compaction or new session\n\n## Environment\n{{REPO_LINE}}\n\n## Core Concepts\n- **Thing**: A named entity versioned by writes. **Assertion**: A thing that makes a shape-validated claim about another thing.\n- **Shape**: A thing defining data structure; every other thing has one. **Write**: One or more add/revise/retract operations with per-operation results.\n- **wref**: A reference to a thing. Local: `Player` (the shape) or `Player/alice` (a thing with that shape). Cross-repo: `wh:org/repo/Shape` or `wh:org/repo/Shape/name`.\n\n## Versioned Wrefs\n- `Shape` addresses the shape itself; `Shape/name` addresses a thing with that shape. `@vN` pins either.\n- Floating write refs to retracted targets fail; existing pinned versions remain valid.\n- Rename invalidates old spellings, including `@vN`; the new name resolves history.\n- Untyped wrefs accept any thing. `wref<T>` requires the target's shape to be `T`; a shape has no shape, so never satisfies it. `wref?` coalesces only `thing_absent`, never a missing shape.\n- Wref `binding`: `identity` follows the Thing, `versioned` pins.\n\n## Key Workflows\n\n**Write data** (discover shapes → scaffold ops → submit):\n```bash\nwh shape list --repo org/repo                             # list available shapes\nwh shape view ShapeName --repo org/repo                   # inspect fields\nwh shape template ShapeName -o ops.json --repo org/repo   # scaffold write ops (supports --kind assertion)\n# edit ops.json — fill FILL_IN placeholders — then:\nwh commit submit --file ops.json --dry-run --repo org/repo  # preview; remove --dry-run to submit\n# or single assertion (no file needed):\nwh assertion create --shape ShapeName --about Target/name --name my-assertion --data '{\"field\":1}' --repo org/repo\n# Relay failed operation details when present. Never hand-guess ops JSON — use `wh shape template <Shape>`.\n```\n\n**Read data:**\n```bash\nwh thing list --repo org/repo                 # all things at HEAD\nwh thing view Shape/name --repo org/repo      # inspect a thing\nwh thing query --shape MyShape --repo org/repo  # find things by shape\nwh thing about Shape --repo org/repo          # assertions about a shape\nwh assertion list --repo org/repo             # all assertions at HEAD\nwh thing history Shape/name --repo org/repo   # version history\n\n# Batch read — wh thing view is variadic (max 500 wrefs/call):\nwh thing view Player/alice Player/bob               # variadic positionals\nwh thing view --file wrefs.txt --json               # one wref per line\ncat wrefs.txt | wh thing view --format jsonl        # one JSON line per *deduped* requested wref\n```\n\n## Wref Quick Reference\n\nWrites use explicit names and wrefs. Untyped fields, collection members,\nassertion `about`, and committers accept any thing. Create a deterministic\ntarget before referencing it in the same commit.\n\n## Command Reference\n\n**Global flags**: `--repo`, `--format`, `--json`, `--live`\n### thing — Things\n- `wh thing list [--shape] [--kind] [--match] [--include-retracted]` — Current HEAD state\n- `wh thing view [<wref>...] [--file <path>] [--version] [--depth] [--include-retracted] [--data-mode auto|full]` — Thing details. Variadic (max 500). `--version` implies `--include-retracted`. Batch JSON returns `{ requested, items, missing }`; jsonl emits one row per deduped requested wref. Large Set/List bodies summarize by default; use `--data-mode full` for canonical collection JSON.\n- `wh thing history [wref] [--shape] [--about] [--include-retracted]` — Version history\n- `wh thing resolve <wref>` — Resolve a wref to its canonical thing identity\n- `wh thing create <name|Shape/name> (--data|--file) [--shape]` — Create\n- `wh thing revise <name> [--data] [--message] [--committer] [--expected-version]` — Revise (CONFLICT if HEAD≠n)\n- `wh thing retract <wref> -m <message> [--reason] [--kind] [--expected-version]` — Retract\n- `wh thing query [--shape] [--kind] [--about] [--match]` — Query by filters\n- `wh thing search <query> [--shape] [--kind] [--about] [--mode]` — Search text\n- `wh thing rename <Shape/oldName> <newName>` — Rename\n- `wh thing refs <wref> [--inbound] [--outbound] [--field]` — Show field references; use `wh thing about` for assertions about the target thing\n- `wh thing about <wref> [--shape] [--match] [--depth] [--resolve-collections] [--role from|to|ends] [--limit] [--include-retracted]` — Show assertions about the target identity; `--resolve-collections` expands bare/@HEAD/@ALL members, `--role` filters direction; not pinned @vN\n\n- `wh view evaluate VIEW [--limit N] [--cursor TOK] [--all]`\n### commit — Write operations\n- `wh commit submit [--ops|--file|--add|--revise|--retract] [--dry-run] [--skip-existing]` — Submit operations, or evaluate the complete bounded input without durable changes under `--dry-run`. JSONL preview emits one operation row per input plus one summary.\n- `wh shape template <shape> [shape2 ...] [--kind] [--operation add|revise|retract] [-o file]` — Generate sample ops\n\n### assertion — Assertion operations\n- `wh assertion list [--about wref] [--shape] [--match] [--include-retracted]` — Browse assertions\n- `wh assertion view <wref> [--version] [--include-retracted]` — Assertion details\n- `wh assertion create --shape <s> --name <n> --about <wref> [--data] [-m] [--committer]` — Create assertion\n- `wh assertion revise <wref> --data <json> [--message] [--committer]` — Revise assertion\n- `wh assertion retract <wref> -m <message> [--reason] [--committer] [--expected-version]` — Retract assertion\n- `wh assertion history <wref> [--include-retracted]` — Assertion history\n\n### shape — Shape management\n- `wh shape list [--match] [--include-retracted]` — List all shapes\n- `wh shape view <name> [--include-retracted]` — Shape details\n- `wh shape revise <name> (--fields|--file)`\n- `wh shape create <name> (--fields|--file)`\n- `wh shape retract <name> -m <message> [--reason] [--expected-version]` — Retract shape\n- `wh shape history <name> [--include-retracted]` — Shape history\n- `wh shape rename <oldName> <newName>` — Rename shape\n\n### repo — Repository management\n- `wh repo create <org/name> [--display-name] [--description] [--visibility]` — Create repo\n- `wh repo list [org]` — List repos\n- `wh repo view [org/repo]` — Repo details\n\n### org — Organization management\n- `wh org create <name> [--display-name]` — Create a new organization\n- `wh org view <name>` — View organization details (alias: info)\n- `wh org list` — List all organizations\n\n### sub — Subscription management\n- `wh sub create <name> [flags]` — Create a subscription\n- `wh sub view <name>` — View subscription details\n- `wh sub list` — List all subscriptions\n- `wh sub log <name>` — Tail subscription delivery feed\n- `wh sub attempts <runId>` — Show attempt history for a run\n- `wh sub pause <name>` — Pause a subscription\n- `wh sub resume <name>` — Resume a paused subscription\n- `wh sub bind <name> [--credentials]` — Bind a credential set to a subscription for webhook auth\n- `wh sub unbind <name>` — Remove credential binding from a subscription\n- `wh sub delete <name>` — Retire; name reserved\n\n### notifications — Action notification listing\n- `wh notifications [--limit] [--since]` — List repo-scoped action notifications\n\n### credential — Credential set management\n- `wh credential create <name> [--repo org/repo | --org org] [--scope] [--description]` — Create an empty credential set\n- `wh credential list [--repo org/repo | --org org]` — List credential sets accessible from a repo or org\n- `wh credential view <name> [--repo org/repo | --org org]` — View a credential set (key names only, no values)\n- `wh credential delete <name> [--repo org/repo | --org org]` — Delete a credential set and its Vault object\n- `wh credential set <setName> [<keyName>] [--repo org/repo | --org org] [--value]` — Set credential key(s). With `<keyName>`: single-key form (reads value from `--value` or stdin). Without `<keyName>`: batch form (reads JSON object from stdin, e.g. `{\"KEY\":\"val\"}`)\n- `wh credential unset <setName> <keyName> [--repo org/repo | --org org]` — Remove a key from a credential set\n- `wh credential audit <setName> [--repo org/repo | --org org]` — View audit log for a credential set\n- `wh credential revoke <setName> [--repo org/repo | --org org] [--reason]` — Revoke a credential set (blocks new binds and stops bound webhook deliveries)\n\n### component — Component management\n- `wh component validate <path>` — Validate package\n- `wh component install <org/name>` — Install a registered component\n- `wh component register <name> --org <org> --manifest <path> [flags]` — Register component identity\n- `wh component unregister <org/name>` — Remove a registered component identity\n- `wh component registry list --org <org>` — List registered components\n- `wh component registry view <org/name>` — View a registered component\n- `wh component registry update <org/name> [flags]` — Update a registered component\n- `wh component list` — List installed components\n- `wh component update <org/name>` — Update installed component\n- `wh component view <org/name>` — Show component details (alias: show)\n- `wh component doctor <org/name>` — Run component health checks\n- `wh component teardown <org/name>` — Pause component subscriptions\n\n### Getting More Info\n- `wh help` — help overview\n- `wh <domain>` — domain verbs\n- `wh <domain> <verb> --help` — verb flags and examples\n- `wh help --format json` — `CliSpecV2` (`schemaVersion: 2`): global/contextual/root tables and command overrides\n\n## Common Workflows\n\n**Explore a repo:**\n```bash\nwh thing list --repo org/repo             # see all things in HEAD\nwh thing view Shape/name --repo org/repo  # inspect a specific thing\nwh thing history Shape/name --repo org/repo # inspect version history\nwh thing about Shape/name                 # assertions about thing/shape\n```\n\n**Create an assertion** (most common write):\n```bash\n# Assertion = Shape with composes:[\"Assertion\"]; write a thing with data.about.\n# --about is window sugar; a wref Shape/name.\nwh assertion create --shape MyShape --about TargetShape/target-name \\\n  --name my-assertion --data '{\"field_a\":1,\"field_b\":\"value\"}' --repo org/repo\n# Output includes per-operation status; relay failures.\n```\n\n**Write entrypoint** (batches and streams):\n```bash\nwh commit submit --add my-item --shape MyShape --kind assertion \\\n  --about TargetShape/target-name --data '{\"field_a\":1}' --repo org/repo\n```\n\n**Batch write via file** (generate template → edit → submit):\n```bash\nwh shape template Hypothesis Evidence -o ops.json    # --kind assertion --about X for assertions\n# edit ops.json — fill FILL_IN placeholders\nwh commit submit --file ops.json -m \"batch update\"   # submit all ops (bare `wh commit` is equivalent)\n# --file format: docs.warmhub.ai/cli-reference/commit-operations\n```\n\n**Bulk write (JSONL stream, >1k ops)** — one chunked stream beats per-record commits (~60× faster):\n```bash\nwh shape template MyShape -o ops.jsonl                          # one op per line (.jsonl)\nID=\"bulk-$(date +%s)\"   # caller id for chunk correlation\nwh commit submit --file ops.jsonl --stream-id \"$ID\" --chunk-size 5000 \\\n  --skip-existing --progress -m \"bulk ingest\" --repo org/repo\n# --chunk-size: ops per append chunk (default 1000, max 10000); chunk≈1 is ~60× slower\n# --skip-existing: skips already-written add ops (drops per-row read-before-write)\n# --stream-id identifies the submission but provides no receipt or resume.\n# After an outcome-unknown append, stop writes and reconcile attempted + unsent\n# work from a later verified checkpoint; never blindly replay revise/retract.\n```\n\n**Create collections:**\n```bash\nwh commit submit --add route --shape Arc --data '{\"from\":\"Location/a\",\"to\":\"Location/b\"}'\nwh assertion create --shape Supports --name route-support --about Arc/route --data '{\"confidence\":0.8}' --repo org/repo\n```\n\n**Modify data:**\n```bash\nwh thing revise Shape/name --data '{\"x\":5,\"y\":3}' -m \"update\" --repo org/repo\nwh thing retract Shape/old-item -m \"withdrawn\" --reason \"data feed contaminated\" --repo org/repo\n```\n\n**Query and filter:**\n```bash\nwh thing query --shape MyShape                       # by shape\nwh thing query --kind assertion --about Shape/name   # by kind + target\nwh thing history Shape/name --limit 10               # version history\n```\n\n## Built-in Content shape\n\nWarmHub repos expose three well-known content wrefs:\n- `Content/Readme`  — stored markdown for humans\n- `Content/Agents`  — stored markdown guidance for AI agents\n- `Content/LlmsTxt` — synthesized per-request sitemap (read-only)\n\nFetch via `wh repo content get --kind readme|agents|llms-txt`,\n`client.repo.getReadme/getAgents/getLlmsTxt`, MCP `warmhub_repo_content_get`,\nor raw HTTP `GET /{org}/{repo}/readme.md|agents.md|llms.txt`.\nSee `wh repo describe` → `additionalInformation` for the discovery field.\n\n## Query Discipline\n- Plan the repo, shapes, and wrefs you need before the first query.\n- Gather the needed facts from one repo before switching to another.\n- Do the queries first, then write one complete answer.\n\n## Agent Tips\n- **Always run commands for live data** — this context describes the CLI, not repo contents\n- **Before writing, discover wrefs** — run `wh thing list` or `wh shape list`\n- **Shape field types**: `string`, `number`, `boolean`, `wref`, arrays, optionals, nested objects\n- **Write commands return per-operation results** — relay failures and affected wrefs to the user\n- **Pass data inline** with `--data '{...}'` — do NOT create temp files\n- Add `--json` to any command for machine-readable JSON output\n- **Aliases teach canonical commands** — executing aliases emit a status hint; misleading lifecycle aliases reject and point to `retract`\n- Writes go through `wh commit submit` (or bare `wh commit`) or wrappers (`create`, `revise`, `retract`, `assertion create`). `retract` irreversibly withdraws an identity and creates a history entry.\n- Use `wh doctor` to check environment health\n";
 
 // ../../packages/warmhub-cli/src/domains/prime.ts
 function buildMarkdown(config2) {
@@ -66153,16 +66190,19 @@ var handleRevise3 = async (ctx, { flags, args }) => {
   if (!shapeName) {
     usageError("Usage: wh shape revise <name> (--fields '<json>' | --file <path>)", `wh shape revise Location --fields '{"x":"number","y":"number","z":"number"}'`, "wh shape revise Location --file fields.json", `wh shape revise Review --fields '{"score":"number","reason?":"string","tags":["string"]}'`);
   }
-  const newFields = await readJsonObjectInput({
+  if (flags.compose !== undefined && flags["clear-composition"]) {
+    usageError("--compose and --clear-composition cannot be used together", "wh shape revise Location --fields '{}' --clear-composition");
+  }
+  const hasFieldInput = flags.fields !== undefined || flags.file !== undefined;
+  if (!hasFieldInput && flags.description === undefined && flags.compose === undefined && !flags["clear-composition"]) {
+    usageError("Usage: wh shape revise <name> (--fields '<json>' | --file <path> | --description <text> | --compose <shape> | --clear-composition)", 'wh shape revise Location --description "Updated description"');
+  }
+  const suppliedFields = hasFieldInput ? await readJsonObjectInput({
     inline: flags.fields,
     file: flags.file,
     inlineFlag: "--fields",
-    missingMessage: "Usage: wh shape revise <name> (--fields '<json>' | --file <path>)",
     example: "wh shape revise Location --file fields.json"
-  });
-  if (flags.compose !== undefined && flags["clear-composition"]) {
-    usageError("--compose and --clear-composition cannot be used together", "wh shape revise Location --fields '{}' --clear-composition");
-  }
+  }) : undefined;
   const { org, repo: repo2 } = parseOrgRepo(getRepoRef(ctx), ctx.config);
   const c = ctx.colors;
   const previousShape = flags["show-diff"] ? await ctx.client.shape.get(org, repo2, shapeName) : undefined;
@@ -66179,18 +66219,18 @@ var handleRevise3 = async (ctx, { flags, args }) => {
     await assertCompositeShapesEnabled(ctx, "--compose");
     opts.composes = flags.compose;
   }
-  const response = await ctx.client.shape.revise(org, repo2, shapeName, newFields, opts);
+  const response = await ctx.client.shape.revise(org, repo2, shapeName, suppliedFields, opts);
   const result = shapeChangeFromReceipt(response.receipt);
   let diff;
-  if (previousFields) {
+  if (flags["show-diff"] && previousFields) {
     let committedBaseFields = previousFields;
     if (result.operation === "noop") {
-      committedBaseFields = newFields;
+      committedBaseFields = suppliedFields ?? previousFields;
     } else if (previousVersion !== result.version - 1) {
       const committedBase = await ctx.client.thing.get(org, repo2, shapeName, result.version - 1);
       committedBaseFields = fieldsFromShapeData(committedBase.data);
     }
-    diff = diffShapeFields(committedBaseFields, newFields);
+    diff = diffShapeFields(committedBaseFields, suppliedFields ?? previousFields);
   }
   writeOutput(ctx, diff ? { ...response, diff } : response, () => {
     if (result.operation === "noop") {
@@ -69808,7 +69848,7 @@ function resolveLogLevel(flagLevel, env) {
 // package.json
 var package_default3 = {
   name: "@warmhub/cli",
-  version: "0.129.0",
+  version: "0.131.0",
   private: false,
   type: "module",
   description: "The wh CLI for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -70433,5 +70473,5 @@ process.exitCode = interceptedExitCode === undefined ? await runPreparedCli(laun
   version: package_default3.version
 }) : interceptedExitCode;
 
-//# debugId=F15B1FBD1F7B2AAF64756E2164756E21
-//# warmhub-cli-build-info {"cliVersion":"0.129.0","sdkVersion":"0.127.0"}
+//# debugId=D045842965BC157364756E2164756E21
+//# warmhub-cli-build-info {"cliVersion":"0.131.0","sdkVersion":"0.129.0"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmhub/cli",
-  "version": "0.129.0",
+  "version": "0.131.0",
   "private": false,
   "type": "module",
   "description": "The wh CLI for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",