@helix3/helix-cli 0.1.13-helix3.85 → 0.1.13-helix3.87

package/README.md

@@ -44,7 +44,8 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix publish [dir] [--thumbnail <file>] [--upload-source] [--source-dir <path>]` | Validate → resolve/create the world → upload files → finalize → set the cover image → print the play URL. `--upload-source` additionally sends the project's source through a separate private channel so the world can be edited on the website later — **off by default**. |
 | `helix list` | List your worlds. |
 | `helix item list-slots [--json]` | Print the Character-Creator vocabulary a wearable declares: the cosmetic slot tags, and the genders. |
-| `helix item publish <mesh.glb> --title <t> [--kind <k>] [--slot <tag>] [--gender <g>] [--price-lix <n> \| --personal] [--thumbnail <f>] [--dry-run]` | Publish a universal item (wearable / avatar / home item) from one `.glb`; the server verifies the mesh inline. |
+| `helix item publish <mesh.glb> --title <t> [--collectible-supply <n>] [initial distribution flags] [--dry-run\|--quote]` | Publish a Standard item by default, or one fixed-supply Collectible. The item definition is separate from acquisition routes. |
+| `helix item distribution create\|list\|update\|disable …` | Manage Marketplace/World Claim or Buy routes without republishing the item or paying another publish fee. |
 | `helix preview-video <slug> <youtube-url>` | Set or clear a published world's YouTube preview. |
 | `helix thumbnail set <slug> <file>` | Upload a thumbnail or preview image through the CLI-owned media path. |
 | `helix assets search\|get\|versions\|track\|install\|update` | Search the typed Vault with explainable ranking; inspect/manage annotations and immutable versions; install by durable ID with verified SHA-256 receipts. Material installs default to lean runtime KTX2 maps; use `--material-renditions source` for source PNGs or `all` for both families. |
@@ -239,19 +240,63 @@ would filter nothing.
 
 ## Item publish flow
 
-`helix item publish` is a different shape from a world publish: one mesh, one round trip, an
-inline verdict — which is what an editor (Helix Studio) needs when an artist clicks Publish.
+`helix item publish` creates an item definition. It defaults to **Standard**: unlimited issuance,
+no public serial, and no resale. `--collectible-supply N` is the only edition selector: it fixes a
+positive supply, assigns public serials, makes instances Marketplace-resellable, and reserves
+serial `#1` for the creator. There are no separate tradable, serial, giftable, personal, or
+discoverability switches.
 
 1. Local validation, before anything leaves the machine: the `--kind`, the Character-Creator
    `--slot` and `--gender` (**both required** for a wearable, exact-match), the title/slug/tag
    limits, and the GLB container magic. `--dry-run` stops here and prints exactly what would be
    sent.
-2. `POST /api/v1/universal-items/upload` — `multipart/form-data` with a `mesh` file part, an
+2. `--quote` asks the server for the definition publish fee, the creator tier's included free-
+   Collectible units, excess issuance authorization cost, creator serial `#1`, price floor and
+   resale policy. It uploads nothing and charges nothing.
+3. `POST /api/v1/universal-items/upload` — `multipart/form-data` with a `mesh` file part, an
    optional `thumbnail` file part, and the metadata as ONE JSON string in `payload`.
-3. The server verifies the mesh **inline** (triangles, texture edges, materials, and — for a
+4. The server verifies the mesh **inline** (triangles, texture edges, materials, and — for a
    wearable — whether it is a skinned garment or a rigid socketed accessory) and returns the
    created item together with the verification verdict and warnings.
 
+Price, world, schedule and limits live on a separate distribution. Price `0` means a shell-
+confirmed **Claim**; a positive price means **Buy** and must meet the server-owned floor. A world
+route also has a stable key, which world code passes to
+`Helix.marketplace.purchaseDistributionKey(key)`. `--max-per-player unlimited` explicitly clears a
+cap; free Collectibles default to one per player when omitted. Distribution changes never republish
+the definition.
+
+```bash
+# Standard, free Marketplace Claim
+helix item publish ./postcard.glb --title "Harbor Postcard"
+helix item distribution create <item-id> --channel marketplace --price-lix 0
+
+# Standard, paid World Buy
+helix item distribution create <item-id> --channel world --world fishing-cove \
+  --key fishing_rod --price-lix 250 --max-per-player unlimited
+
+# Collectible, free World Claim (creator receives #1 from the 500 fixed units)
+helix item publish ./trophy.glb --title "Season One Trophy" --collectible-supply 500 \
+  --distribution-channel world --distribution-price-lix 0 --world tournament \
+  --distribution-key season_one --max-per-player 1 --quote
+# Review the quote, then run the same command without --quote to publish.
+
+# Collectible, paid Marketplace Buy
+helix item publish ./bluefin.glb --title "Legendary Bluefin" --collectible-supply 10000
+helix item distribution create <item-id> --channel marketplace --price-lix 500 --max-claims 9000
+
+helix item distribution update <distribution-id> --price-lix 600 --ends-at 2026-12-01T00:00:00Z
+helix item distribution disable <distribution-id>
+```
+
+Collectible resale uses Marketplace escrow. The creator royalty is fixed at 5%; the launch seller
+platform fee is 10% for Free and 5% for Plus (future Gold 2.5%, Diamond 0%). The buyer pays no
+surcharge, creator self-sale omits a redundant royalty leg, and self-purchase is prohibited.
+Every acquisition has one 24-hour relisting cooldown. Basic requires email; Verified means a unique
+verified mobile plus good standing and may resell immediately subject to that cooldown. Identity Verified
+is reserved for later high-risk capability, and tooling accepts future Business Verified. Payout holds are
+separate: 3 days base, risk-extendable up to 15 days.
+
 The slot table in `src/item.ts` MIRRORS `helix-backend-api → src/universal-items/cc-wearable-slot.ts`,
 and the gender list mirrors `src/universal-items/cc-gender.ts` the same way. They are a local fast
 path so a typo costs no upload; the server remains the authority and its 400 lists every valid

package/dist/distribution.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Canonical universal-item distribution vocabulary.
+ *
+ * An item definition says what the item is. A distribution is one creator-
+ * authorized primary acquisition route. Keeping this builder network-free
+ * lets `--dry-run` exercise exactly the payload the real command sends.
+ */
+export declare const ITEM_EDITION_MODES: readonly ["standard", "collectible"];
+export type ItemEditionMode = (typeof ITEM_EDITION_MODES)[number];
+export declare const ITEM_DISTRIBUTION_CHANNELS: readonly ["marketplace", "world"];
+export type ItemDistributionChannel = (typeof ITEM_DISTRIBUTION_CHANNELS)[number];
+export declare const DISTRIBUTION_KEY_PATTERN: RegExp;
+export type ItemDistributionInput = {
+    itemId?: string;
+    channel: ItemDistributionChannel;
+    priceLix: number;
+    worldId?: string;
+    worldSlug?: string;
+    key?: string;
+    maxPerPlayer?: number | null;
+    maxClaims?: number | null;
+    startsAt?: string | null;
+    endsAt?: string | null;
+};
+export type ItemDistributionFields = {
+    itemId?: string;
+    channel: ItemDistributionChannel;
+    priceLix: number;
+    worldId?: string;
+    /** Offline plan only; the CLI resolves it to worldId before a network write. */
+    worldSlug?: string;
+    key?: string;
+    maxPerPlayer?: number | null;
+    maxClaims?: number | null;
+    startsAt?: string | null;
+    endsAt?: string | null;
+};
+export type ItemDistributionUpdateInput = {
+    priceLix?: number;
+    maxPerPlayer?: number | null;
+    maxClaims?: number | null;
+    startsAt?: string | null;
+    endsAt?: string | null;
+};
+export type ItemDistributionPatch = ItemDistributionUpdateInput;
+export declare function buildItemDistribution(input: ItemDistributionInput): ItemDistributionFields;
+export declare function buildItemDistributionUpdate(input: ItemDistributionUpdateInput): ItemDistributionPatch;
+export declare function editionFields(collectibleSupply?: number): {
+    editionMode: ItemEditionMode;
+    collectibleSupply?: number;
+};

package/dist/distribution.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Canonical universal-item distribution vocabulary.
+ *
+ * An item definition says what the item is. A distribution is one creator-
+ * authorized primary acquisition route. Keeping this builder network-free
+ * lets `--dry-run` exercise exactly the payload the real command sends.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DISTRIBUTION_KEY_PATTERN = exports.ITEM_DISTRIBUTION_CHANNELS = exports.ITEM_EDITION_MODES = void 0;
+exports.buildItemDistribution = buildItemDistribution;
+exports.buildItemDistributionUpdate = buildItemDistributionUpdate;
+exports.editionFields = editionFields;
+exports.ITEM_EDITION_MODES = ['standard', 'collectible'];
+exports.ITEM_DISTRIBUTION_CHANNELS = ['marketplace', 'world'];
+exports.DISTRIBUTION_KEY_PATTERN = /^[a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?$/;
+const positiveInt = (name, value) => {
+    if (value === undefined || value === null)
+        return;
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`${name} must be a whole number >= 1, or unlimited`);
+    }
+};
+const price = (value) => {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`--price-lix must be a number >= 0 LIX (got ${value})`);
+    }
+    return value;
+};
+const timestamp = (name, value) => {
+    if (value === undefined || value === null)
+        return value;
+    const parsed = new Date(value);
+    if (!Number.isFinite(parsed.valueOf())) {
+        throw new Error(`${name} must be an ISO-8601 timestamp (got "${value}")`);
+    }
+    return parsed.toISOString();
+};
+function buildItemDistribution(input) {
+    if (!exports.ITEM_DISTRIBUTION_CHANNELS.includes(input.channel)) {
+        throw new Error(`--channel must be marketplace or world (got "${input.channel}")`);
+    }
+    const priceLix = price(input.priceLix);
+    positiveInt('--max-per-player', input.maxPerPlayer);
+    positiveInt('--max-claims', input.maxClaims);
+    const startsAt = timestamp('--starts-at', input.startsAt);
+    const endsAt = timestamp('--ends-at', input.endsAt);
+    if (startsAt && endsAt && new Date(startsAt) >= new Date(endsAt)) {
+        throw new Error('--ends-at must be later than --starts-at');
+    }
+    const worldId = input.worldId?.trim();
+    const worldSlug = input.worldSlug?.trim();
+    const key = input.key?.trim();
+    if (input.channel === 'world') {
+        if (!worldId && !worldSlug) {
+            throw new Error('a world distribution requires --world <slug>');
+        }
+        if (!key)
+            throw new Error('a world distribution requires --distribution-key <key>');
+        if (!exports.DISTRIBUTION_KEY_PATTERN.test(key)) {
+            throw new Error(`--distribution-key "${key}" must use lowercase letters, digits, _ or - (1-64 characters)`);
+        }
+    }
+    else if (worldId || input.worldSlug || key) {
+        throw new Error('a marketplace distribution cannot carry --world or --distribution-key');
+    }
+    return {
+        ...(input.itemId ? { itemId: input.itemId } : {}),
+        channel: input.channel,
+        priceLix,
+        ...(worldId ? { worldId } : {}),
+        ...(!worldId && worldSlug ? { worldSlug } : {}),
+        ...(key ? { key } : {}),
+        ...(input.maxPerPlayer !== undefined ? { maxPerPlayer: input.maxPerPlayer } : {}),
+        ...(input.maxClaims !== undefined ? { maxClaims: input.maxClaims } : {}),
+        ...(startsAt !== undefined ? { startsAt } : {}),
+        ...(endsAt !== undefined ? { endsAt } : {}),
+    };
+}
+function buildItemDistributionUpdate(input) {
+    if (input.priceLix === undefined && input.maxPerPlayer === undefined &&
+        input.maxClaims === undefined && input.startsAt === undefined && input.endsAt === undefined) {
+        throw new Error('no distribution changes supplied');
+    }
+    if (input.priceLix !== undefined)
+        price(input.priceLix);
+    positiveInt('--max-per-player', input.maxPerPlayer);
+    positiveInt('--max-claims', input.maxClaims);
+    const startsAt = timestamp('--starts-at', input.startsAt);
+    const endsAt = timestamp('--ends-at', input.endsAt);
+    if (startsAt && endsAt && new Date(startsAt) >= new Date(endsAt)) {
+        throw new Error('--ends-at must be later than --starts-at');
+    }
+    return {
+        ...(input.priceLix !== undefined ? { priceLix: input.priceLix } : {}),
+        ...(input.maxPerPlayer !== undefined ? { maxPerPlayer: input.maxPerPlayer } : {}),
+        ...(input.maxClaims !== undefined ? { maxClaims: input.maxClaims } : {}),
+        ...(startsAt !== undefined ? { startsAt } : {}),
+        ...(endsAt !== undefined ? { endsAt } : {}),
+    };
+}
+function editionFields(collectibleSupply) {
+    if (collectibleSupply === undefined)
+        return { editionMode: 'standard' };
+    if (!Number.isInteger(collectibleSupply) || collectibleSupply < 1) {
+        throw new Error('--collectible-supply must be a whole number >= 1');
+    }
+    return { editionMode: 'collectible', collectibleSupply };
+}
+//# sourceMappingURL=distribution.js.map

package/dist/distribution.js.map

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

package/dist/index.js

@@ -524,6 +524,56 @@ function parsePriceLix(value) {
         fail(`✖ --price-lix must be a number, got '${value}'`);
     return price;
 }
+function parsePositiveInt(value, flag) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1)
+        fail(`✖ ${flag} must be a whole number >= 1`);
+    return parsed;
+}
+function parseLimit(value, flag) {
+    if (value.trim().toLowerCase() === 'unlimited')
+        return null;
+    return parsePositiveInt(value, flag);
+}
+function renderItemQuote(q) {
+    const lines = [
+        `  edition: ${q.editionMode}${q.collectibleSupply !== null ? ` · fixed supply ${q.collectibleSupply} · creator serial #${q.creatorSerial ?? 1}` : ' · unlimited · no serials'}`,
+        `  publish total: ${q.publishFeeLix} LIX`,
+        `    review fee: ${q.reviewFeeLix} LIX · normally non-refundable`,
+        `    compliance bond: ${q.complianceBondLix} LIX · returned after approval + ${q.complianceBondReleaseDays} days in good standing`,
+    ];
+    if (q.editionMode === 'collectible') {
+        lines.push(`  free Collectible allowance: ${q.includedCollectibleUnits} included · ${q.chargeableCollectibleUnits} additionally authorized`, `  issuance authorization: ${q.issuanceAuthorizationFeeLix} LIX`, `  resale: ${q.creatorRoyaltyPercent}% creator royalty · seller fee ${q.sellerPlatformFeePercentByTier.free}% Free / ${q.sellerPlatformFeePercentByTier.plus}% Plus (future ${q.sellerPlatformFeePercentByTier.gold}% Gold / ${q.sellerPlatformFeePercentByTier.diamond}% Diamond)`, `  buyer surcharge: ${q.buyerSurchargePercent}% · self-purchase prohibited · ${q.resaleCooldownHours}h relisting cooldown`, `  resale eligibility: Basic email; Verified unique mobile + good standing (immediate); Identity Verified reserved for later high-risk capability; Business Verified supported`, `  payout hold: ${q.payoutHoldBaseDays} days base · risk-extension up to ${q.payoutHoldMaxDays} days`);
+    }
+    if (q.distribution) {
+        lines.push(`  initial ${q.distribution.channel}: ${q.distribution.priceLix === 0 ? 'Claim (free)' : `Buy at ${q.distribution.priceLix} LIX`} · floor ${q.distribution.priceFloorLix} LIX`);
+    }
+    lines.push(`  total due now: ${q.totalDueLix} LIX`);
+    return lines;
+}
+function initialDistributionFromFlags(opts) {
+    const any = opts.distributionChannel !== undefined || opts.distributionPriceLix !== undefined ||
+        opts.world !== undefined || opts.distributionKey !== undefined || opts.maxPerPlayer !== undefined ||
+        opts.maxClaims !== undefined || opts.startsAt !== undefined || opts.endsAt !== undefined;
+    if (!any)
+        return undefined;
+    if (!opts.distributionChannel)
+        fail('✖ initial distribution flags require --distribution-channel');
+    if (opts.distributionPriceLix === undefined)
+        fail('✖ an initial distribution requires --distribution-price-lix');
+    const input = {
+        channel: opts.distributionChannel,
+        priceLix: parsePriceLix(opts.distributionPriceLix),
+        worldSlug: opts.world,
+        key: opts.distributionKey,
+        maxPerPlayer: opts.maxPerPlayer !== undefined ? parseLimit(opts.maxPerPlayer, '--max-per-player') : undefined,
+        maxClaims: opts.maxClaims !== undefined ? parseLimit(opts.maxClaims, '--max-claims') : undefined,
+        startsAt: opts.startsAt,
+        endsAt: opts.endsAt,
+    };
+    (0, lib_1.buildItemDistribution)(input);
+    return input;
+}
 item
     .command('publish')
     .description('Publish a universal item from a local .glb — the server verifies the mesh inline and returns the verdict in the same round trip')
@@ -541,11 +591,19 @@ item
     .option('--slug <slug>', 'url slug (default: derived from the title)')
     .option('--description <text>', 'item description')
     .option('--thumbnail <file>', 'thumbnail image (png/jpg/webp); rendered from the mesh when omitted, required for an avatar')
-    .option('--price-lix <n>', 'list on the marketplace at this LIX price (charges a non-refundable publish fee)')
-    .option('--personal', 'keep it private and free instead of listing it (no publish fee)')
+    .option('--collectible-supply <n>', 'select Collectible edition with this fixed positive supply; omitted means Standard')
+    .option('--distribution-channel <channel>', 'create one initial route: marketplace or world')
+    .option('--distribution-price-lix <n>', 'initial route price; 0 is Claim, positive is Buy')
+    .option('--world <slug>', 'world that owns an initial world route')
+    .option('--distribution-key <key>', 'stable key world code passes to purchaseDistributionKey')
+    .option('--max-per-player <n|unlimited>', 'initial route per-player cap; free Collectibles default to 1 server-side')
+    .option('--max-claims <n|unlimited>', 'initial route-wide issuance cap')
+    .option('--starts-at <iso>', 'initial route activation time (ISO-8601)')
+    .option('--ends-at <iso>', 'initial route end time (ISO-8601)')
     .option('--tags <a,b,c>', 'comma-separated search keywords')
     .option('--allow-oversize', 'relax the mesh size/polycount ceilings for a deliberately heavy asset')
     .option('--dry-run', 'validate everything locally and print what WOULD be sent; no upload, no fee')
+    .option('--quote', 'request the server-owned publish/issuance quote; no upload or fee')
     .option('--json', 'machine-readable output')
     .action(async (mesh, opts) => {
     const publishOptions = {
@@ -557,11 +615,15 @@ item
         genders: opts.gender !== undefined ? (0, lib_1.parseGenders)(opts.gender) : undefined,
         slug: opts.slug,
         description: opts.description,
-        priceLix: opts.priceLix !== undefined ? parsePriceLix(opts.priceLix) : null,
-        keepPersonal: opts.personal === true,
+        collectibleSupply: opts.collectibleSupply !== undefined
+            ? parsePositiveInt(opts.collectibleSupply, '--collectible-supply')
+            : undefined,
+        initialDistribution: initialDistributionFromFlags(opts),
         tags: opts.tags !== undefined ? (0, lib_1.parseTags)(opts.tags) : undefined,
         allowOversize: opts.allowOversize === true,
     };
+    if (opts.dryRun && opts.quote)
+        fail('✖ choose --dry-run (offline) or --quote (server-owned fees), not both');
     // --dry-run stops before ANY network call, so it works logged out — the
     // point is to check the mesh and the metadata, not the account.
     if (opts.dryRun) {
@@ -594,6 +656,23 @@ item
         }
         return;
     }
+    if (opts.quote) {
+        const creds = requireAuth();
+        try {
+            const quote = await (0, lib_1.quoteItemPublish)(publishOptions, creds);
+            if (opts.json)
+                console.log(JSON.stringify({ quote }, null, 2));
+            else {
+                console.log('✔ Publish quote — nothing uploaded or charged.');
+                for (const line of renderItemQuote(quote))
+                    console.log(line);
+            }
+        }
+        catch (err) {
+            fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return;
+    }
     const creds = requireAuth();
     const mismatch = (0, config_1.credsEnvMismatchWarning)(creds.apiUrl);
     if (mismatch)
@@ -614,9 +693,11 @@ item
         if (result.genders.length)
             console.log(`  gender: ${result.genders.join(', ')}`);
         console.log(`  status: ${result.status}`);
-        console.log(result.priceLix === null
-            ? '  price:  (personal — not listed)'
-            : `  price:  ${result.priceLix} LIX (publish fee ${result.publishFeeLix} LIX)`);
+        console.log(`  edition: ${result.editionMode}${result.collectibleSupply !== null ? ` · supply ${result.collectibleSupply} · creator serial #${result.creatorSerial ?? 1}` : ''}`);
+        console.log(`  publish fee: ${result.publishFeeLix} LIX`);
+        if (result.initialDistribution) {
+            console.log(`  route: ${result.initialDistribution.channel} · ${result.initialDistribution.priceLix === 0 ? 'Claim' : `Buy ${result.initialDistribution.priceLix} LIX`}`);
+        }
         console.log(`  id:     ${result.id}`);
         for (const warning of result.verification.warnings)
             console.log(`  ⚠ ${warning}`);
@@ -627,6 +708,145 @@ item
             : `✖ ${err instanceof Error ? err.message : String(err)}`);
     }
 });
+const itemDistribution = item
+    .command('distribution')
+    .description('Create and manage primary Claim/Buy routes for one published item definition');
+const renderDistribution = (d) => [
+    `${d.id} · ${d.channel}${d.worldSlug ? `:${d.worldSlug}/${d.key}` : ''}`,
+    `${d.priceLix === 0 ? 'Claim' : `Buy ${d.priceLix} LIX`}${d.active ? '' : ' · DISABLED'}`,
+    `max/player ${d.maxPerPlayer ?? 'unlimited'} · max claims ${d.maxClaims ?? 'unlimited'}`,
+].join(' · ');
+itemDistribution
+    .command('create')
+    .description('Create one creator-authorized primary acquisition route; no second publish fee')
+    .argument('<item-id>', 'published universal item definition id')
+    .requiredOption('--channel <marketplace|world>', 'route channel')
+    .requiredOption('--price-lix <n>', '0 is Claim; positive is Buy and must meet the server-owned floor')
+    .option('--world <slug>', 'required for a world route')
+    .option('--key <key>', 'stable world route key')
+    .option('--max-per-player <n|unlimited>', 'per-player cap')
+    .option('--max-claims <n|unlimited>', 'distribution-wide cap')
+    .option('--starts-at <iso>', 'activation time')
+    .option('--ends-at <iso>', 'end time')
+    .option('--dry-run', 'validate and print the request; no network')
+    .option('--json', 'machine-readable output')
+    .action(async (itemId, opts) => {
+    const input = {
+        itemId,
+        channel: opts.channel,
+        priceLix: parsePriceLix(opts.priceLix),
+        worldSlug: opts.world,
+        key: opts.key,
+        maxPerPlayer: opts.maxPerPlayer !== undefined ? parseLimit(opts.maxPerPlayer, '--max-per-player') : undefined,
+        maxClaims: opts.maxClaims !== undefined ? parseLimit(opts.maxClaims, '--max-claims') : undefined,
+        startsAt: opts.startsAt,
+        endsAt: opts.endsAt,
+    };
+    try {
+        const fields = (0, lib_1.buildItemDistribution)(input);
+        if (opts.dryRun) {
+            const out = { dryRun: true, endpoint: '/api/v1/item-distributions', fields };
+            if (opts.json)
+                console.log(JSON.stringify(out, null, 2));
+            else
+                console.log(`✔ Dry run — nothing sent.\n  POST ${out.endpoint}\n  ${JSON.stringify(fields)}`);
+            return;
+        }
+        const created = await (0, lib_1.createItemDistribution)(input, requireAuth());
+        if (opts.json)
+            console.log(JSON.stringify(created, null, 2));
+        else
+            console.log(`✔ Created ${created.priceLix === 0 ? 'Claim' : 'Buy'} route.\n  ${renderDistribution(created)}`);
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+itemDistribution
+    .command('list')
+    .description('List every active or disabled primary route drawing from an item')
+    .argument('<item-id>')
+    .option('--json', 'machine-readable output')
+    .action(async (itemId, opts) => {
+    try {
+        const rows = await (0, lib_1.listItemDistributions)(itemId, requireAuth());
+        if (opts.json)
+            console.log(JSON.stringify({ distributions: rows }, null, 2));
+        else if (!rows.length)
+            console.log(`No distributions exist for ${itemId}.`);
+        else
+            console.log(rows.map(renderDistribution).join('\n'));
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+const clearableTimestamp = (value) => value?.toLowerCase() === 'none' ? null : value;
+itemDistribution
+    .command('update')
+    .description('Reprice or change schedule/caps. Item, channel, world and key remain fixed')
+    .argument('<distribution-id>')
+    .option('--price-lix <n>')
+    .option('--max-per-player <n|unlimited>')
+    .option('--max-claims <n|unlimited>')
+    .option('--starts-at <iso|none>', 'replace or clear the activation time')
+    .option('--ends-at <iso|none>', 'replace or clear the end time')
+    .option('--dry-run', 'validate and print the patch; no network')
+    .option('--json', 'machine-readable output')
+    .action(async (id, opts) => {
+    const input = {
+        priceLix: opts.priceLix !== undefined ? parsePriceLix(opts.priceLix) : undefined,
+        maxPerPlayer: opts.maxPerPlayer !== undefined ? parseLimit(opts.maxPerPlayer, '--max-per-player') : undefined,
+        maxClaims: opts.maxClaims !== undefined ? parseLimit(opts.maxClaims, '--max-claims') : undefined,
+        startsAt: clearableTimestamp(opts.startsAt),
+        endsAt: clearableTimestamp(opts.endsAt),
+    };
+    try {
+        const patch = (0, lib_1.buildItemDistributionUpdate)(input);
+        if (opts.dryRun) {
+            const out = { dryRun: true, endpoint: `/api/v1/item-distributions/${id}`, patch };
+            if (opts.json)
+                console.log(JSON.stringify(out, null, 2));
+            else
+                console.log(`✔ Dry run — nothing sent.\n  PATCH ${out.endpoint}\n  ${JSON.stringify(patch)}`);
+            return;
+        }
+        const updated = await (0, lib_1.updateItemDistribution)(id, input, requireAuth());
+        if (opts.json)
+            console.log(JSON.stringify(updated, null, 2));
+        else
+            console.log(`✔ Updated distribution.\n  ${renderDistribution(updated)}`);
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+itemDistribution
+    .command('disable')
+    .description('Disable an acquisition route without deleting its history or republishing the item')
+    .argument('<distribution-id>')
+    .option('--dry-run', 'print the request; no network')
+    .option('--json', 'machine-readable output')
+    .action(async (id, opts) => {
+    if (opts.dryRun) {
+        const out = { dryRun: true, endpoint: `/api/v1/item-distributions/${id}/disable` };
+        if (opts.json)
+            console.log(JSON.stringify(out, null, 2));
+        else
+            console.log(`✔ Dry run — nothing sent.\n  POST ${out.endpoint}`);
+        return;
+    }
+    try {
+        const disabled = await (0, lib_1.disableItemDistribution)(id, requireAuth());
+        if (opts.json)
+            console.log(JSON.stringify(disabled, null, 2));
+        else
+            console.log(`✔ Disabled distribution.\n  ${renderDistribution(disabled)}`);
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError ? err.render() : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
 // --- helix achievement -----------------------------------------------------
 // A world's achievement registry lives OUTSIDE its bundle — helix.json cannot
 // declare one and publish cannot check that a key exists, so a rule awarding an
@@ -847,7 +1067,7 @@ achievement
 // they cannot enter. Worlds are named by SLUG, products by their key.
 const product = program
     .command('product')
-    .description("Register and manage a world's in-world products (what Helix.purchase sells). Registration works on a Draft (`helix world create` first); buying needs the world Published");
+    .description("Register world-local consumables, passes and currencies. Universal items use `helix item distribution` instead");
 function renderProduct(p, indent = '  ') {
     // An authored-grants product's stored type is server-DERIVED — the effect list is the truth,
     // so the "your world applies it" hint only fits legacy consumables.
@@ -897,12 +1117,11 @@ product
     .argument('<world-slug>', 'the world that sells it')
     .requiredOption('--title <title>', 'name the purchase popup shows the player (max 120 chars)')
     .requiredOption('--price <lix>', 'price in LIX; 0 registers a free "Claim" (a confirmation, no spend)')
-    .option('--type <type>', `what the purchase does: ${lib_1.WORLD_PRODUCT_TYPES.join(' | ')} — required unless you author --grants`)
-    .option('--grants <json>', `JSON array of what the purchase hands over, instead of --type/--item-id: item | pass | currency, max ${lib_1.MAX_GRANT_EFFECTS} ` +
+    .option('--type <type>', 'legacy world-local effect type: consumable (required unless you author --grants)')
+    .option('--grants <json>', `JSON array of world-local entitlements instead of --type: pass | currency, max ${lib_1.MAX_GRANT_EFFECTS} ` +
     "(e.g. '[{\"kind\":\"currency\",\"code\":\"coin\",\"amount\":500}]'; [] = a tip jar). Fixed at registration")
     .option('--key <key>', 'stable slug world code buys as `pkey:<key>` (max 64 chars, lowercase a-z0-9_-); it cannot be renamed later')
     .option('--description <text>', 'what the player is buying')
-    .option('--item-id <uuid>', 'the universal item handed over — REQUIRED for item_grant and non_consumable, refused for consumable')
     .option('--max-per-user <n>', 'cap on how many one player may own (whole number >= 1)')
     .option('--dry-run', 'validate everything locally and print what WOULD be sent; no network, works logged out')
     .option('--json', 'machine-readable output')
@@ -914,10 +1133,15 @@ product
         description: opts.description,
         priceLix: Number(opts.price),
         type: opts.type,
-        itemId: opts.itemId,
         grants: opts.grants !== undefined ? parseGrantsFlag(opts.grants) : undefined,
         maxPerUser: opts.maxPerUser !== undefined ? parseWholeNumber(opts.maxPerUser, '--max-per-user') : undefined,
     };
+    if (registration.type !== undefined && registration.type !== 'consumable') {
+        fail('✖ World Products do not mint universal items. Use `helix item distribution create`; legacy --type accepts only consumable.');
+    }
+    if (registration.grants?.some((grant) => grant.kind === 'item')) {
+        fail('✖ World Product grants accept pass/currency only. Publish the item and create an ItemDistribution instead.');
+    }
     // Stops before ANY network call, so it works logged out — the point is to
     // check the vocabulary and the type/item coherence, not the account.
     if (opts.dryRun) {