@hypersoniclabs/helix-cli 0.1.25-helix3.496 → 0.1.25-helix3.497

package/README.md

@@ -71,9 +71,9 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix item list-slots [--json]` | Print the Character-Creator vocabulary a wearable declares: the cosmetic slot tags, and the genders. |
 
 | `helix item distribution create\|list\|update\|disable …` | Manage Marketplace/World Claim or Buy routes without republishing the item or paying another publish fee. |
-| `helix item visual-qa <item-id> [--submit] [--local-critic] [--storage-state <file>] [--host <id…>]` | Render the item's current package version headless in the real runtime (test-grounds world for vehicles and whole avatars, the customiser for add-ons and wearables on every declared host/base, the item viewer for props), measure it, and with `--submit` record the backend's verdict (numeric asserts + vision critic) against that exact version. **Marketplace/Vault listing, distributions and version moves on a public item require a pass.** See [docs/visual-qa.md](docs/visual-qa.md). |
-| `helix item visual-qa <item-id> --package-version <v> [--vehicle-package <file>]` | Render a version the item is **not pinned to yet**, so a refused version move can pass the gate before the pointer moves. Vehicles and avatars go through Try Now (vehicles also need the move's vehicle package), add-ons and wearables through the customiser; the bundle names the candidate, and the vehicle checksum is the one the server minted for that trial. Never falls back to the current version. See [docs/visual-qa-candidate-versions.md](docs/visual-qa-candidate-versions.md). With `--submit`, a PASS prints the next command (`helix item set-version …`); a 403 for a non-creator says so on the first line; `--status` also lists the item's pending (sealed, not current) versions. |
-| `helix item set-version <item-id> --package-version <v> --reason <text> [--expected-current-version-id <uuid>] [--as-admin] [--json]` | Move an item to a sealed Package Version of its own package (pin resolved from the public Package API; `POST /api/v1/universal-items/<id>/versions`). The flow for a **listed** item: `continuum publish-package` seals vN → `item visual-qa <id> --package-version vN --submit` → `item set-version`. A refusal prints the server's message first (it names the next command), then the remedy and any hosted render it queued. An unknown version lists the sealed ones. A **vehicle** moves its car with the pin: the version's sealed root (role `vehicle-definition`) is verified against the manifest and sent as `vehiclePackage`, the same rider `vehicle publish --item` sends; a version without one is refused with a pointer to that resume. A version the item **already had** is a rollback: `PUT /api/v1/universal-items/<id>/versions/current { revision, reason }` (the server restores that revision's retained `vehiclePackage`; a pin-only revision has none and is refused). `--as-admin` (platform admins, for an item another account created) posts the same body to `POST /api/v1/admin/universal-items/<id>/versions`: same gates (visual QA included, no override), `--reason` recorded with you as the actor. |
+| `helix item visual-qa <item-id> [--submit] [--local-critic] [--storage-state <file>] [--host <id…>]` | Render the item's current package version headless in the real runtime (test-grounds world for vehicles and whole avatars, the customiser for add-ons and wearables on every declared host/base, the item viewer for props), measure it, and with `--submit` record the backend's verdict (numeric asserts + vision critic) against that exact version. **The visual check is advisory: it records notes with fix hints and never gates listing, distributions or version moves. Only a technical failure (an unusable file, with its plain reason) or content safety blocks.** See [docs/visual-qa.md](docs/visual-qa.md). |
+| `helix item visual-qa <item-id> --package-version <v> [--vehicle-package <file>]` | Render a version the item is **not pinned to yet** and record advisory notes for it before (or after) the pointer moves; the move itself never waits on it. Vehicles and avatars go through Try Now (vehicles also need the move's vehicle package), add-ons and wearables through the customiser; the bundle names the candidate, and the vehicle checksum is the one the server minted for that trial. Never falls back to the current version. See [docs/visual-qa-candidate-versions.md](docs/visual-qa-candidate-versions.md). With `--submit`, a PASS prints the next command (`helix item set-version …`) for a version not moved yet; a 403 for a non-creator says so on the first line; `--status` also lists the item's pending (sealed, not current) versions. |
+| `helix item set-version <item-id> --package-version <v> --reason <text> [--expected-current-version-id <uuid>] [--as-admin] [--json]` | Move an item to a sealed Package Version of its own package (pin resolved from the public Package API; `POST /api/v1/universal-items/<id>/versions`). The flow for a **listed** item: `continuum publish-package` seals vN → `item set-version`; the visual check is advisory and never gates the move. A refusal (a technical failure or content safety) prints the server's plain reason first, then the remedy. An unknown version lists the sealed ones. A **vehicle** moves its car with the pin: the version's sealed root (role `vehicle-definition`) is verified against the manifest and sent as `vehiclePackage`, the same rider `vehicle publish --item` sends; a version without one is refused with a pointer to that resume. A version the item **already had** is a rollback: `PUT /api/v1/universal-items/<id>/versions/current { revision, reason }` (the server restores that revision's retained `vehiclePackage`; a pin-only revision has none and is refused). `--as-admin` (platform admins, for an item another account created) posts the same body to `POST /api/v1/admin/universal-items/<id>/versions`: same gates (visual QA included, no override), `--reason` recorded with you as the actor. |
 | `helix item thumbnail refresh <item-id> [--force] [--dry-run] [--json]` | Re-render a published item's canonical thumbnail from its **active Package Version** with the standard server renderer (`POST /api/v1/universal-items/<id>/thumbnail/regenerate`, owner or admin). Prints the status (`generated` / `current` / `dry-run`), old -> new thumbnail URL, renderer version and the source lane + Package Version. `--dry-run` writes nothing; `--force` re-renders even when the stored thumbnail is current. Moving an item to a new Package Version now refreshes the thumbnail automatically unless you uploaded one. An older backend answers 404 and the CLI says it does not support thumbnail refresh yet. Not the world `helix thumbnail set <slug>` command. |
 | `helix item thumbnail set <item-id> <image> [--json]` | Upload your own thumbnail (png/jpg/webp, up to 10 MiB, checked locally) for a published item (`PUT /api/v1/universal-items/<id>/thumbnail`, moderated). A creator upload stays in place across version moves until you run `thumbnail refresh --force`. 403 = you are not the item's owner. |
 | `helix device create <dir> --id <slug> --title <t> --model <mesh.glb> --template standing-desk\|clock\|television` | Scaffold a GLB-backed `helix.device/1` definition, including the interactive TV/media-player template. There is intentionally no website Device editor. |

package/dist/index.js

@@ -1130,7 +1130,7 @@ vehicleCommand
     .description('Publish a vehicle package directory: validate (package, GLB, host manifest, audio), upload the model and samples, seal a '
     + 'public Vehicle Package whose root pins them, make the vehicle Item from that exact Version, and read it back (pin, package '
     + 'identity, mesh pin, every audio URL, and the host board: hostKind vehicle, sockets, tunable paths). Resumable from '
-    + '<dir>/.helix-publish/ledger.json. With --item: seal a STAGED new Version of that car and move it (visual QA gates the move). '
+    + '<dir>/.helix-publish/ledger.json. With --item: seal a STAGED new Version of that car and move it (the visual check is advisory and never gates the move). '
     + 'Directory: vehicle-package.json + model.glb (asset.extras.HELIX_vehicle with sockets) + WAVs; optional publish.json '
     + '{ title, description, tags, version, contentRating, provenance, hostGrantExtensions }. '
     + 'Exit 0 = published and verified, 1 = a check or read-back failed, 2 = could not run')
@@ -1241,7 +1241,7 @@ vehicleAddOnCommand
     + 'Package (root: the helix.vehicle-addon-definition/1 JSON; a tune-only part seals no model), make the add-on Item from that exact '
     + 'Version, and read it back: pinned, the backend fit lists every host, every host\'s add-on rail lists it. No offer is opened. '
     + 'A CHANGED part is a new Version of the SAME Item: --package-version <semver> with --item <id> (or in the directory that first published it) '
-    + 'seals a staged Version and moves the Item to it (visual QA gates a listed meshed part; re-run the same command to finish the move); '
+    + 'seals a staged Version and moves the Item to it (the visual check is advisory and never gates the move; re-run the same command to retry one the server refused); '
     + 'sealing a version name that already holds different bytes is refused. --dry-run also runs the seal-side validation '
     + '(provenance.source <= 256 chars, contentRating, Package shape, version clash). '
     + 'Resumable from <dir>/.helix-publish/ledger.json. Exit 0 = published and verified, 1 = a check or read-back failed, 2 = could not run')
@@ -2032,9 +2032,8 @@ itemThumbnail
     }
 });
 // Ship a corrected mesh onto an already-published GLB add-on/prop/avatar IN PLACE: seal a new Version of the item's
-// own Continuum Package, then move the item pointer. On a listed item the move is refused by the visual-QA gate (the
-// sealed Version stays behind), and the refusal names the two finishing steps: `item visual-qa --package-version vN
-// --submit`, then `item set-version`. This is step 1 of `VERSION_MOVE_FLOW_HELP`.
+// own Continuum Package, then move the item pointer. The visual check is advisory and never gates the move; a refusal
+// (technical failure or content safety) leaves the sealed Version behind and says why. See `VERSION_MOVE_FLOW_HELP`.
 item
     .command('publish-version')
     .description('Ship a corrected mesh onto an already-published GLB add-on/prop/avatar, IN PLACE — new Package Version, same item id/owner/listings; every existing owner gets it at their next spawn')
@@ -2069,7 +2068,7 @@ item
             return;
         }
         console.log(`✔ Sealed ${result.packageId}@${result.version} — a new Version of ${itemId} (manifest ${result.manifestCid}).`);
-        console.log(`  The move is gated by visual QA; the seal is left in place and is reused by a retry with the same mesh.`);
+        console.log(`  The item was not moved; the seal is left in place and is reused by a retry with the same mesh.`);
         if (result.refusal)
             console.log((0, itemSetVersion_1.renderSetVersionError)(result.refusal));
         process.exitCode = 1;
@@ -2078,16 +2077,16 @@ item
         fail(error instanceof lib_1.ApiError ? error.render() : `✖ ${error instanceof Error ? error.message : String(error)}`);
     }
 });
-// Move a (listed) item to an already-sealed Package Version of its own package. The visual-QA gate refuses the move
-// until that version has a passing run; a refusal prints the server's message first because it names the next command.
+// Move a (listed) item to an already-sealed Package Version of its own package. The visual check is advisory and never
+// gates the move; a refusal (technical failure or content safety) prints the server's plain reason first.
 item
     .command('set-version')
-    .description('Move an item to a sealed Package Version of its own package (the version-move step after `item visual-qa --package-version <v> --submit` passed). A vehicle moves its car with the pin: the version\'s sealed vehicle definition is sent as properties.vehiclePackage (refused if the version has none). A version the item already had is a rollback (PUT versions/current), so moving back to an older version works too')
+    .description('Move an item to a sealed Package Version of its own package (the visual check is advisory and never gates the move; only a technical failure or content safety refuses it). A vehicle moves its car with the pin: the version\'s sealed vehicle definition is sent as properties.vehiclePackage (refused if the version has none). A version the item already had is a rollback (PUT versions/current), so moving back to an older version works too')
     .argument('<item-id>', 'universal item UUID')
     .requiredOption('--package-version <version>', 'the sealed version to move to, e.g. 1.0.12')
     .requiredOption('--reason <text>', 'required, lands in the audit ledger')
     .option('--expected-current-version-id <uuid>', 'refuse if the item has moved off this Package Version since you last read it')
-    .option('--as-admin', 'platform admins only: move an item another account created (POST /api/v1/admin/universal-items/<id>/versions). Same gates as the creator move, including visual QA; --reason is recorded with you as the actor')
+    .option('--as-admin', 'platform admins only: move an item another account created (POST /api/v1/admin/universal-items/<id>/versions). Same gates as the creator move (technical failure, content safety); --reason is recorded with you as the actor')
     .option('--json', 'machine-readable output')
     .addHelpText('after', moveUx_1.VERSION_MOVE_FLOW_HELP)
     .action(async (itemId, opts) => {
@@ -2289,16 +2288,16 @@ function initialDistributionInputFromPackFlags(opts) {
 // Distinct from `item distribution disable` below: a distribution is ONE
 // acquisition route (you can have several); delist takes the whole item
 // definition off browse/marketplace regardless of how many routes it has.
-// Visual QA: the publish/listing gate judges an item RENDERED, in the real runtime, not its numbers. This command is
+// Visual QA: an advisory check that looks at an item RENDERED, in the real runtime, not its numbers; it never gates. This command is
 // the harness: it renders the item's current package version headless (test-grounds world for vehicles, the
 // customiser for add-ons and wearables, the item viewer for props), measures it, and with --submit hands it to the
-// backend, which runs the vision critic, records the verdict against that exact version and serves a contact sheet.
+// backend, which records the advisory notes against that exact version and serves a contact sheet.
 item
     .command('visual-qa')
-    .description('Render an item headless in the real HELIX runtime, measure it, and (with --submit) record the visual-QA verdict that Marketplace/Vault listing requires. --hosted asks the platform to render it on a GPU runner instead')
+    .description('Render an item headless in the real HELIX runtime, measure it, and (with --submit) record the advisory visual-QA notes (never a gate on publishing, listing or moving; only an unusable file or content safety blocks). --hosted asks the platform to render it on a GPU runner instead')
     .argument('[item-id]', 'universal item UUID (its CURRENT package version is rendered, or --package-version); omit with --hosted-worker')
     .option('--submit', 'submit frames + measurements to the backend, which judges and records the verdict (needs `helix login`)')
-    .option('--hosted', 'queue a hosted render on the platform GPU runner and wait for the verdict (needs `helix login`; exit 0 pass, 0 warn (an avatar judged with generator-limit warnings only: released privately, `verdict: "warn"` + `warnings` in --json), 1 fail, 2 error)')
+    .option('--hosted', 'queue a hosted render on the platform GPU runner and wait for the verdict (needs `helix login`; exit 0 pass, 0 warn (advisory notes only: `verdict: "warn"` + `warnings` in --json), 1 fail (notes, never a gate), 2 error)')
     .option('--retry', 'with --hosted: REQUEUE this version after a failed, errored or exhausted hosted run (a fresh job, attempts start again; inside the backend cooldown it waits it out, up to --timeout)')
     .option('--no-wait', 'with --hosted: queue the render and return without waiting')
     .option('--timeout <minutes>', 'with --hosted: how long to wait for the verdict', '30')
@@ -2404,7 +2403,7 @@ item
                 else if (!req.job)
                     console.log(`✖ nothing queued${req.skipped ? ` (${req.skipped})` : ''}${req.message ? `: ${req.message}` : ''}`);
                 else if (req.skipped === 'warned_run')
-                    console.log(`! this version already has a WARN run (judged, nothing blocks; released privately with warnings): nothing to re-queue. Read the warnings with: helix item visual-qa ${id} --status`);
+                    console.log(`! this version already has a WARN run (advisory notes only, nothing blocks): nothing to re-queue. Read the warnings with: helix item visual-qa ${id} --status`);
                 else if (req.skipped)
                     console.log(`✖ not re-queued (${req.skipped})${req.message ? `: ${req.message}` : ''}${req.retryAfter ? ` Retry after ${req.retryAfter}.` : ''} Showing the existing job: ${hosted.describeJob(req.job)}`);
                 else
@@ -2479,12 +2478,12 @@ item
             if (outcome.server?.contactSheetUrl)
                 console.log(`  recorded: ${outcome.server.contactSheetUrl}`);
             if (!opts.submit)
-                console.log('  (local run only — add --submit to record the verdict the listing gate checks)');
+                console.log('  (local run only — add --submit to record the advisory notes; nothing waits on them)');
             for (const line of (0, moveUx_1.nextStepAfterPass)({ itemId: id, packageVersion: outcome.bundle.item.packageVersion, candidate: !!outcome.candidate, submitted: !!outcome.server, verdict: outcome.verdict, vehiclePackageFile: opts.vehiclePackage }))
                 console.log(line);
             console.log(`  ${(outcome.timings.totalMs / 1000).toFixed(1)} s (render ${(outcome.timings.renderMs / 1000).toFixed(1)} s)`);
         }
-        // pass 0 · warn 0 (an avatar judged with generator-limit warnings: released privately, nothing blocks) · fail 1 · error 2
+        // pass 0 · warn 0 (advisory notes only, nothing blocks) · fail 1 · error 2
         process.exitCode = (await Promise.resolve().then(() => __importStar(require('./visualQa/verdictText')))).exitCodeForVerdict(outcome.verdict);
     }
     catch (error) {