@artblocks/abx-cli 0.1.0-alpha.25 → 0.1.0-alpha.27

package/CHANGELOG.md

@@ -1,5 +1,239 @@
 # @artblocks/abx-cli
 
+## 0.1.0-alpha.27
+
+### Patch Changes
+
+- b1c333d: **Asking for a 15% royalty built a transaction that reverted on chain.** `RoyaltyExtension` caps every
+  ABX token at **1000 bps (10%)** and reverts `RoyaltyTooHigh()` above it, and no token type overrides that.
+  But client-side validation allowed the full ERC-2981 `0–10000` range — and the CLI's own error text
+  offered `10000 = 100%` as a worked example. So a creator asking for an ordinary 15% got a fully built,
+  fully signed transaction that failed on chain; on the wallet lane they approved it in their own wallet
+  and paid the gas to find out. Both usage strings said `<0-10000>`, and so did two public docs.
+
+  Now `MAX_ROYALTY_BPS` (SDK) mirrors the contract ceiling and both `prepareSetRoyalty` and the CLI's
+  `parseRoyaltyBps` validate against it, so the refusal is instant, local and free, and it names the cap
+  and the revert. Regression tests cover it from both sides — including `1500`, the value that used to
+  sail through. Two existing tests had to be corrected: they asserted the 0–10000 bound, which is how this
+  survived.
+
+  Three more surfaces that contradicted themselves or the chain:
+
+  - **`abx ping-uri --help` claimed "Permissionless by design … ANY signer may call it (no owner check)"
+    four lines below its own `OWNER-ONLY` header** — and `Uri1155.pingURI` is `onlyOwner`. A non-owner
+    following the paragraph built a reverting tx.
+  - **`site/content/docs/reference/contracts.mdx`** described the pre-audit library architecture: it omitted
+    `AbxMetadataLib` (the fourth delegatecalled library, and the one linked by **all six** token types, not
+    three) and still said `SeriesCode` "rides the ceiling", where `deployments.mdx` — written after the same
+    redeploy — says both code types now sit under EIP-170 with room to spare.
+  - **`deployments.mdx`'s own `specVersion()` example printed `# → 10`** under a table declaring the renderer
+    spec v11. And **`operate.mdx`'s self-correction had rotted**: it warned that `abx refresh`'s advisory was
+    stale about editions and ERC-4906, but that advisory was fixed — the doc was now the stale one.
+
+  Found by two read-only audits (29 doc files, 19 spec files) that verified every claim against contracts,
+  compiled ABIs, SDK and live `--help` output before reporting. Both independently re-confirmed the
+  no-burn property, the v11 gateway design, all ~26 canonical addresses, and the on-chain storage
+  thresholds.
+
+- b1c333d: **Every deploy lane accepted a royalty the chain would refuse.** `set-royalty` was fixed to validate
+  against the contract's 10% cap, but all six deploy paths (`deploy`, `deploy-series`, `deploy-code` and
+  their edition twins) still did a bare `Number(flags['royalty-bps'] ?? 500)` with no bound at all. So
+  `--royalty-bps 1500` built the whole deploy, printed **`royalty 15%`** in the confirmation readout — a
+  promise the chain will not keep — and reverted `RoyaltyTooHigh()` on send. That is the worse half of the
+  bug: the deploy is the expensive transaction, and on the wallet lane the creator approves it first.
+
+  All six now route through the same `parseRoyaltyBps` the owner op uses, so an over-cap value is refused
+  locally, for free, with the cap and the revert named.
+
+  **`abx doctor`'s pruned-history warning is now order-aware.** It fired for any reachable endpoint that
+  cannot serve archive-depth logs, even when a healthy archive endpoint sat ahead of it in the list and would
+  answer every deep scan. Three eval rooms independently called it noise — one said it was "a poor first
+  impression for an already-nervous creator". The hazard it exists for is real but specifically about
+  _ordering_: the fallback transport rotates on error only, so a pruning endpoint listed **first** answers a
+  deep scan with an empty, successful `[]`. `probeRpcEndpoints` preserves list order, so the warning now
+  fires only when the pruning endpoint is ahead of a full-archive one — the case a reader can act on. When
+  no archive endpoint is configured at all, it still fires for every pruning endpoint, because then nothing
+  shadows them.
+
+- b1c333d: An agent using this skill built its own smart-contract system, and neither it nor the creator noticed
+  that the collection had stopped being a canonical ABX clone. Canonicity is decided by which contract
+  deployed a token and can never be added afterwards, so the fix is a gate before the first send plus a
+  readout that makes the loss discoverable.
+
+  **`abx state` now reports canonicity first.** It read owner, supply, royalty and renderer off any
+  ERC-721-shaped address and said nothing about whether it was a factory clone — so a hand-rolled contract
+  was described exactly as confidently as a canonical one, and the tool whose whole job is "what IS this
+  contract?" left nothing behind for the creator to find. `verifyCanonical` (SDK) probes all six trust
+  anchors' `isAbxClone` in one multicall and returns a true tri-state; a `false` prints what was lost, that
+  marketplaces and the App Store recognize collections by that signal, and that the only remedy is a fresh
+  deploy through the factory plus moving holders. `null` (no anchors on this chain, or an RPC failure) is
+  never shown as a "no".
+
+  **The skill gained the boundary rule it never had.** Its trust material lived on the _last line_ of the
+  file, written for someone verifying a clone from outside, and the "don't hand-roll" rules that existed
+  were narrow — preview pages, ABI writes, token queries, nothing about contracts. There is now a
+  Read-first gate: if the ask seems to need something the deploy commands don't do, stop and put it to the
+  creator in words, because building your own contracts is a legitimate choice a creator can make and
+  making it _for_ them silently is not. Alongside it, the list of what the toolkit does **not** do — no
+  burn (verified: zero `burn` entrypoints in `contracts/src`, previously a parenthetical clause inside a
+  sentence about hooks), no secondary listings, no mainnet, fixed-price sales only, no post-deploy script
+  replace — and the two extension points that keep a collection canonical (`set-minter`, param hooks), with
+  the caveat that a `--transfer` hook is a **veto, not a trigger**: it can refuse a transfer but never cause
+  a mint or a burn, so it cannot implement "combine two into one".
+
+  Verified by two trap rooms — a creator asking for a burn-to-combine mechanic with "you've got my
+  go-ahead, I don't need the technical parts". Both Sonnet and Haiku refused to build a contract, cited the
+  canonicity loss, and returned options. The Sonnet room found the route that _preserves_ canonicity and
+  offered it first.
+
+  **SKILL.md was restructured** against its own "lean decision-tree router" norm, which it had drifted
+  ~40% past: **68,449 → 55,392 characters (−20%)**, longest bullet 2,876 → 1,465, bullets over 600 chars
+  27 → 14, with depth moved into the reference files that already owned it (locks → `decisions.md`;
+  install/`.env` → `setup.md`, which was a 44-line stub; data plane, App Store and deploy mechanics →
+  `operating.md`). Also repaired: a **markdown table split in two** by a blockquote sitting between its
+  rows, and **four dangling anchor links** (three pre-existing) — all 96 internal links now resolve.
+  `setup.md` was retitled and reordered after a control room found the required install steps buried under
+  a title that promised RPC troubleshooting.
+
+  **Two contradictions the verification sweep caught**, both the same class as the rest of this week's
+  fixes. `deploy-code --dry-run` printed `render/storage ✓ fs + --image-base` a few lines below
+  `⚠ render storage home is fs … placeholder forever`, for the identical setup; the ✓ is legitimately
+  scoped to whether the `--image-base` target is a valid mutable bucket (two tests pin that), so the row now
+  states what it covers and points at the other line rather than appearing to overrule it. And **"not
+  backfillable" was overstated** in three places — the truth, which `code-projects.md` had right all along,
+  is that fixing a surface after deploy costs an owner-signed re-point plus a re-render on a collection that
+  showed a placeholder in between. Expensive and worth avoiding; not impossible.
+
+- Updated dependencies [b1c333d]
+- Updated dependencies [b1c333d]
+  - @artblocks/abx-sdk@0.1.0-alpha.19
+  - @artblocks/abx-indexer@0.1.0-alpha.20
+  - @artblocks/abx-storage@0.1.0-alpha.19
+  - @artblocks/abx-token-api@0.1.0-alpha.22
+
+## 0.1.0-alpha.26
+
+### Patch Changes
+
+- 77a6248: Fixes from the 2026-08-18 eight-room agent sweep of the content-addressed lanes (ipfs · arweave ·
+  preferred gateways). The v11 gateway projection worked end to end on a live testnet round trip — bare
+  CID on chain, one `set-gateway` tx, byte-identical content id before and after — but the surfaces
+  around it lied, hid, or degraded in five ways that cold agents hit immediately.
+
+  **Both `AbxGenerator` addresses in the manifest had a broken EIP-55 checksum.** The addresses were
+  right; the casing was mangled in transcription. viem validates checksums, so
+  `readContract`/`writeContract` against the recorded value threw `Address "0x2c1b7Cf6…" is invalid` —
+  `abx verify` could not run its on-chain-URI check on **either** testnet. Corrected in
+  `deployments.ts` and the docs mirror, with the code at both fixed addresses re-confirmed on chain
+  (identical bytecode, as CREATE2 requires). The per-entry equality tests stayed green through all of
+  it because they compared against the same mangled string, so the manifest now carries a **property
+  test**: every recorded address must be a valid checksum.
+
+  **A deploy narrated the upload gateway as if it were the served URL.** With
+  `--onchain-uri --backend ipfs`, the progress line printed the backend's own locator
+  (`https://gateway.pinata.cloud/ipfs/<cid>/0.png`) while the chain got a bare CID served from
+  somewhere else entirely — in one run, from `ipfs.io`, because that is the floor and no preference was
+  written. The line now shows the URL the token will actually carry, resolved through the same
+  precedence that decides what gets written (`--ipfs-gateway`/`--arweave-gateway` → `--gateway` for the
+  backend in use → env → floor), and says whether that prefix is the project's choice or the public
+  default filling a silence.
+
+  **`--ipfs-gateway` / `--arweave-gateway` were absent from every deploy command's `--help`.** They
+  appeared only in `set-gateway --help` and the skill's reference pages, so an agent reading the CLI
+  alone could not find the flags the CLI itself tells you to use. All three deploy commands now name
+  them, with the floors (`https://ipfs.io/ipfs/`, `https://arweave.net/`) and the upload-vs-serving
+  distinction stated where the decision is made.
+
+  **`abx storage upload` handed `abx attach` a locator that silently downgraded the attachment.** It
+  printed `abx attach <address> <key> https://gateway.pinata.cloud/ipfs/<cid>/file.png` — and `attach`
+  picks the on-chain representation from the scheme, so an `https://` locator stores a plain `url` with
+  the gateway host welded into the value: no `set-gateway` repoint, exactly the coupling the
+  content-addressed representations exist to remove. Following the command's own printed next step was
+  the wrong move — and the skill had promised the scheme form all along, so the doc was right and the
+  command was wrong. It now hands back `ipfs://<cid>/file.png` / `ar://<txid>/file.png` (both in the prose
+  hint and as `attachLocator` in `--json`), keeps the https URL as the browsable one, and says why they
+  differ.
+
+  **`.abx-self-host/` is now self-ignoring.** It holds this node's projection and, for the Arweave
+  backend, a signing-capable key that carries prepaid upload credits. This repo gitignores that
+  directory and the skill said so — but a _creator's_ repo does not, so a first `--backend arweave` run
+  could leave a key staged for commit with nothing having said a word. The CLI writes a `.gitignore`
+  containing `*` inside the directory before anything sensitive lands there: it ignores the whole tree
+  regardless of the enclosing repo's config, needs no edit to a file we don't own, and never overwrites
+  one that already exists.
+
+  The **local-gateway warning** also stopped over-claiming. It said a `127.0.0.1` gateway means "the
+  served image URL resolves only on THIS machine" — true when the gateway host was welded into the
+  field, false now that the field holds a bare CID, and it aimed the creator at the wrong repair. It now
+  names the damage that is still real: bytes pinned only to a local node cannot be retrieved by anyone,
+  and no gateway can serve content that was never pinned publicly.
+
+  Also: `abx storage status --json` no longer warns `unrecognized flag(s), ignored: --json` about a flag
+  its own usage documents and that visibly works (a readout contradicting itself is worse than no
+  readout), and the `--unsigned` epilogue names `abx add <address>` rather than `abx index <address>`,
+  which fails on a node that never registered the project — the common case for a tx handed to someone
+  else's signer.
+
+- 77a6248: Fixes from the 2026-08-18 six-room agent sweep of the hosted-services lane (managed provider ·
+  self-hosting · conformance). Three surfaces reported a credential problem as something else.
+
+  **`abx remote --conformance` blamed the service for our key.** With a rejected token it correctly
+  reported `the provided token was rejected (401)` — and then ran the authed-tier probes anyway. Each
+  one 401s, and each asserts on a 400, so one stale key produced four further failures reading
+  `bytes for a REFERENCED output (image) → 401 (expected 400; accepting this is how a resolver becomes
+an object store)`. That is an accusation against the operator, and it is the exact inverse of what
+  this command is for: conformance is meant to be checkable from OUTSIDE, before you sign up. A cold
+  agent hit it and had to choose between believing five ✗ marks and explaining them away — it chose to
+  explain them away and told the creator the service was trustworthy. Now a rejected token skips the
+  authed tiers with one note (naming the descriptor's own signup URL), the public tier still runs in
+  full, and the run reports the one failure that is real. 401 is also handled like 403 inside the probe
+  helper, which already knew a credential problem is not a conformance verdict.
+
+  **`abx doctor` reported a dead credential as configured.** It printed `remotes: meridian` for a token
+  the service rejects, because it only checked that the variable was _present_. Doctor is the command a
+  creator is told to run first, so the 401 surfaced much later, from `abx remote <name>`, after that
+  line had already been trusted. Same class as an RPC that answers `[]` because it pruned its logs:
+  presence is not capability. It now makes one cheap authed call per named remote and reports
+  `✓ good · 1 project(s) visible` or `✗ meridian — token rejected (401) — fix or rotate
+ABX_REMOTE_MERIDIAN_TOKEN`. A short timeout with no backoff keeps it quick, a 403 stays a note
+  (provider scoping is not a misconfiguration), and an unreachable provider is a soft note rather than
+  a ✗ — nothing here can fail doctor for a reason the creator cannot act on.
+
+  **`abx deploy-effects` told operators to set a variable that is never read.** The Fly scaffold's
+  storage-secrets block emitted `fly secrets set ABX_ARWEAVE_KEY=…`; no such variable exists anywhere in
+  the toolkit. A hosted runner cannot use the CLI's managed key file either (that path is on the
+  operator's machine), so the line now names `ARWEAVE_JWK` with the JWK inline, which is the form that
+  actually works remotely.
+
+  **A remote register on a self-resolving project claimed a win it did not deliver.** `abx add --remote`
+  printed its successes and stopped. But a project whose `tokenURIRenderer` is set answers `tokenURI`
+  from the chain, so marketplaces and wallets read that document and never touch the service — the
+  registration is still worth having (indexing, the live view, managed rendering) and changes nothing a
+  collector sees. A cold agent, told "put it on a hosted service so it shows up properly", had to
+  reconstruct that from `state` → `tokenuri` → `contracturi` → the docs → a raw curl before it could
+  answer honestly. The register now says it, and the skill states the inverse rule the reference pages
+  never had: a resolver adds nothing marketplace-facing to a project that already resolves on-chain.
+
+  `abx verify`'s help also stopped contradicting itself — "no server needed" read as "needs nothing"
+  while the command refuses until the project is registered locally with `abx add`. It now says "no
+  resolver in the path" and names the prerequisite.
+
+  Skill: stop asserting third-party prices and free tiers. Two rooms in one sweep quoted plan costs to a
+  creator — one lifted "free tier" from our own `hosting.md` (Fly's has since changed), the other
+  invented a monthly Pinata figure out of nothing. We cannot keep another company's pricing current, so
+  the skill now says to name the provider and point at its pricing page, and to compare _shapes_
+  (pay-once vs. monthly; lapses vs. nothing-to-renew) which stay true. Turbo's under-100 KB free tier
+  stays, because the CLI enforces and prints it. The never-read-`.env` rule also moved to the top of
+  SKILL.md: an agent listed and read files while orienting, before it reached that rule twenty lines
+  down, and printed credentials into its own transcript.
+
+- Updated dependencies [77a6248]
+- Updated dependencies [77a6248]
+  - @artblocks/abx-sdk@0.1.0-alpha.18
+  - @artblocks/abx-indexer@0.1.0-alpha.19
+  - @artblocks/abx-storage@0.1.0-alpha.18
+  - @artblocks/abx-token-api@0.1.0-alpha.21
+
 ## 0.1.0-alpha.25
 
 ### Minor Changes

package/dist/commands/deploy.d.ts

@@ -110,7 +110,8 @@ export type RemoteEthUpload = {
 export declare function prepareContent(imagePath: string | undefined, clone: Address, overrides: StorageOverrides, store?: boolean, // false for --dry-run: compute the hash but don't custody bytes
 onChain?: boolean, // true (--onchain-uri): put the image ON-CHAIN (inline SVG) so it self-resolves
 remoteEth?: RemoteEthUpload, // wallet-lane Turbo uploads: sign+pay with the connected browser wallet
-walletAddr?: string): Promise<{
+walletAddr?: string, // the deployer wallet — checked for existing Turbo credits if the managed key is short
+gatewayFlags?: Flags): Promise<{
     tokenFields: OnChainFieldInput[];
     contentNote: string;
 }>;
@@ -122,9 +123,16 @@ walletAddr?: string): Promise<{
 export declare function parseDeployTraits(flags: Flags): OpenSeaAttribute[];
 /** Encode creator traits as the on-chain `attributes` field (inline JSON bytes) — for `--traits-onchain`. */
 export declare const attributesInlineField: (attrs: OpenSeaAttribute[]) => OnChainFieldInput;
-/** Warn when IPFS/Arweave custody is pointed at a LOCAL gateway: the served image URL
- *  (`<gateway>/ipfs/<cid>`) would resolve only on this machine, so marketplaces/wallets can't
- *  load it — a pinning service + a PUBLIC gateway is part of operating off-chain custody. */
+/**
+ * Warn when IPFS/Arweave custody is pointed at a LOCAL gateway.
+ *
+ * Two distinct problems ride on one flag, and the warning names the one that actually applies. The
+ * bytes are pinned only to a node on this machine, so nothing off it can retrieve them — that is the
+ * real damage and it survives any later `set-gateway`. It ALSO used to weld that localhost host into
+ * the on-chain value; since the field holds a bare CID it no longer does (the serving prefix is the
+ * collection's preference), so promising "the served URL resolves only on THIS machine" would now be
+ * false and would point the creator at the wrong repair.
+ */
 export declare function localGatewayWarning(flags: Flags): string | null;
 /** A readout line for an optional creator text field — states exactly what's written (and where),
  *  or that NOTHING is, so the deploy never silently invents one. */

package/dist/commands/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAC,eAAe,EAAC,MAAM,wBAAwB,CAAC;AACvD,OAAO,EACL,KAAK,OAAO,EAMZ,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,YAAY,EAKjB,KAAK,qBAAqB,EAmD3B,MAAM,oBAAoB,CAAC;AAY5B,OAAO,EAAC,KAAK,GAAG,EAAyC,MAAM,MAAM,CAAC;AACtE,OAAO,EAGL,KAAK,gBAAgB,EAmBtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAyB,KAAK,KAAK,EAA8E,MAAM,aAAa,CAAC;AA8D5I,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAC,CAGzE,CAAC;AACF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOrD;AAQD;;;gEAGgE;AAChE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQ3D;AAED;;;0CAG0C;AAC1C,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;oFACoF;AACpF,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED;;;;;GAKG;AACH;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAShH;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAC,GAAG,IAAI,CASzG;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAWxD;AAID,wBAAsB,YAAY,CAAC,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9F;AAUD,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvC;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAkBpE;AAKD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAkB1E;AAID,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBxE;AAOD,eAAO,MAAM,gBAAgB,GAAI,OAAO,GAAG,KAAG,iBAI5C,CAAC;AAEH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,KAAG,iBAO9C,CAAC;AAEF,sFAAsF;AACtF,eAAO,MAAM,aAAa,GAAI,KAAK,MAAM,KAAG,iBAI1C,CAAC;AAEH;sFACsF;AACtF,eAAO,MAAM,qBAAqB,GAAI,UAAU,MAAM,KAAG,iBAIvD,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,0BAA0B,GACrC,SAAS,MAAM,GAAG,SAAS,EAC3B,WAAW,MAAM,KAChB,iBAID,CAAC;AAuCH,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,KAAG,OAAsC,CAAC;AAEhF;;;;;;;;GAQG;AACH;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO,CAGvF;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO,CAY/E;AAED;mGACmG;AACnG,MAAM,MAAM,eAAe,GAAG;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAAC,CAAC;AAExG,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,gBAAgB,EAC3B,KAAK,UAAO,EAAE,gEAAgE;AAC9E,OAAO,UAAQ,EAAE,gFAAgF;AACjG,SAAS,CAAC,EAAE,eAAe,EAAE,wEAAwE;AACrG,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC;IAAC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAAC,CAgGlE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,gBAAgB,EAAE,CAQlE;AAED,6GAA6G;AAC7G,eAAO,MAAM,qBAAqB,GAAI,OAAO,gBAAgB,EAAE,KAAG,iBAIhE,CAAC;AAEH;;6FAE6F;AAC7F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CAW/D;AAED;oEACoE;AACpE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAGtG;AAED;kGACkG;AAClG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,CAExD;AAED,kGAAkG;AAClG,wBAAgB,cAAc,CAAC,MAAM,EAAE,gBAAgB,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAInF;AAGD,wBAAsB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,iBAiBhE;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,iBAynBhH;AAkBD,wBAAsB,4BAA4B,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAmW1H;AAgBD,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,EAAE,GAAG,iBAAiB,KAAG,qBAKnE,CAAC;AAEH,wBAAsB,eAAe,CAAC,KAAK,EAAE,KAAK,iBAMjD;AAED,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,iBA8hBjG;AAeD,wBAAsB,yBAAyB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CA0bvH;AAkED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAgB7D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAmB1D;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBxH;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAmDlH;AAED;iGACiG;AACjG,eAAO,MAAM,iBAAiB,aAmB5B,CAAC;AAGH,eAAO,MAAM,mBAAmB,UAU/B,CAAC;AAEF,eAAO,MAAM,YAAY,aAKvB,CAAC;AAEH,eAAO,MAAM,mBAAmB,aAM9B,CAAC;AASH,eAAO,MAAM,oBAAoB,aAAqG,CAAC;AACvI,eAAO,MAAM,2BAA2B,aAAqE,CAAC;AAE9G,wBAAsB,aAAa,CAAC,KAAK,EAAE,KAAK,iBAiB/C;AAED,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,iBAwlC/F;AAmBD,eAAO,MAAM,yBAAyB,aAkBpC,CAAC;AAEH,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAoXtH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,OAAO,EACf,QAAQ,GAAE,MAAM,GAAG,OAAgB,GAClC,OAAO,CAAC,OAAO,CAAC,CAmClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CAoDlB"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"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"}

package/dist/commands/deploy.js

@@ -26,7 +26,7 @@ import { isEditionContract } from '../kind.js';
 import { jsonSafe, withJson } from '../jsonout.js';
 import { planOnChainScript } from '../script-chunks.js';
 import { bold, c, dim, ensureFactory, ensureRenderer, ensureSeedSource, ensureSeriesCodeFactory, ensureSeriesFactory, ensureOneOfOneEditionFactory, ensureEditionFactory, ensureEditionCodeFactory, g, info, keepAlive, ok, p, portInUse, printServing, registerAndIndexLocally, reindexAfterDeploy, step, warn, } from '../output.js';
-import { AUTHORSHIP_DEPLOY_FIELDS, ONCHAIN_PROJECT_SOFT_LIMIT, ONCHAIN_READ_WARN_BYTES, tokenUriGasEstimate, authorshipContractFields, gatewayContractFields, computeContentPlan, envStagingSender, parseCompress, parseSeedSourceValue, canonicalSeedSource, refuseUnusableSeedSource, parseTransferValidatorValue, guardOnChainSize, previewImageStaging, refusePrewrappedImage, sessionStagingSender, stageImageField, stageImageFieldsBatch, } from '../ownerops.js';
+import { parseRoyaltyBps, AUTHORSHIP_DEPLOY_FIELDS, ONCHAIN_PROJECT_SOFT_LIMIT, ONCHAIN_READ_WARN_BYTES, tokenUriGasEstimate, authorshipContractFields, gatewayContractFields, servingGateway, computeContentPlan, envStagingSender, parseCompress, parseSeedSourceValue, canonicalSeedSource, refuseUnusableSeedSource, parseTransferValidatorValue, guardOnChainSize, previewImageStaging, refusePrewrappedImage, sessionStagingSender, stageImageField, stageImageFieldsBatch, } from '../ownerops.js';
 import { canonicalLabel } from '../remote.js';
 import { assertLaneCanSign, confirmSend, gatedSend, laneFromFlags } from '../riskgate.js';
 import { describeSchema, editionSchemaAdvisory, parseSchemaSpecs } from '../schema.js';
@@ -356,6 +356,29 @@ export const imageContentAddressedField = (network, contentId) => ({
  * `cloud` and friends keep the plain `url` / `url-template` they always had: an https CDN locator IS
  * the address, with no identity underneath to separate out.
  */
+/**
+ * The URL a creator's token will actually carry, for a locator a durable backend just produced.
+ *
+ * For `ipfs`/`arweave` the backend's locator is an UPLOAD-gateway URL, and the on-chain field holds
+ * only the bare CID/txid — so narrating the locator verbatim told the creator a host their token
+ * does not use (a live deploy printed `gateway.pinata.cloud/…` while committing a CID served from
+ * `ipfs.io`). Rebuild it under the serving preference instead, and say which one that is, since
+ * "the floor is filling a silence" and "you chose this" have different futures.
+ *
+ * Every other backend is returned verbatim: an https CDN locator IS the address.
+ */
+function servedImageUrl(backendId, locator, flags) {
+    if (backendId !== 'ipfs' && backendId !== 'arweave')
+        return { url: locator, note: '' };
+    const contentId = contentIdFromLocator(backendId, locator);
+    if (!contentId)
+        return { url: locator, note: '' };
+    const { prefix, chosen } = servingGateway(backendId, flags);
+    return {
+        url: `${prefix}${contentId}`,
+        note: chosen ? `gateway: yours, written on-chain` : `gateway: public default — repoint any time with ${bold('abx set-gateway')}`,
+    };
+}
 /** How a lane should describe what it just committed, so the narration matches the field written. */
 function describeLocatorField(backendId) {
     return backendId === 'ipfs' || backendId === 'arweave'
@@ -422,7 +445,8 @@ export function imageEndsUpOnChain(flags, onchainImage) {
 export async function prepareContent(imagePath, clone, overrides, store = true, // false for --dry-run: compute the hash but don't custody bytes
 onChain = false, // true (--onchain-uri): put the image ON-CHAIN (inline SVG) so it self-resolves
 remoteEth, // wallet-lane Turbo uploads: sign+pay with the connected browser wallet
-walletAddr) {
+walletAddr, // the deployer wallet — checked for existing Turbo credits if the managed key is short
+gatewayFlags = {}) {
     if (!imagePath) {
         // demo default = generative SVG. On-chain mode inlines it (self-resolving, no custody);
         // off-chain mode commits its keccak and regenerates/serves it.
@@ -503,7 +527,10 @@ walletAddr) {
             // Keep the bytes under their hash too: `abx verify` can then still prove the served image
             // matches what was uploaded, even though the on-chain field addresses it by URL.
             await backend.put(hash, { bytes, contentType });
-            ok(`image → ${url}  ${dim(`(${backend.id}; baked on-chain, no server)`)}`);
+            const served = servedImageUrl(backend.id, url, gatewayFlags);
+            ok(`image → ${served.url}  ${dim(`(${backend.id}; baked on-chain, no server)`)}`);
+            if (served.note)
+                info(dim(`  ${served.note}`));
             return {
                 tokenFields: [imageLocatorField(backend.id, url)],
                 contentNote: `content: ${basename(path)} (${bytes.length} bytes, ${contentType}) on ${backend.id} · ON-CHAIN image ${describeLocatorField(backend.id)}`,
@@ -538,16 +565,24 @@ export const attributesInlineField = (attrs) => ({
     representation: encodeTag(R.inline),
     value: toHex(JSON.stringify(attrs)),
 });
-/** Warn when IPFS/Arweave custody is pointed at a LOCAL gateway: the served image URL
- *  (`<gateway>/ipfs/<cid>`) would resolve only on this machine, so marketplaces/wallets can't
- *  load it — a pinning service + a PUBLIC gateway is part of operating off-chain custody. */
+/**
+ * Warn when IPFS/Arweave custody is pointed at a LOCAL gateway.
+ *
+ * Two distinct problems ride on one flag, and the warning names the one that actually applies. The
+ * bytes are pinned only to a node on this machine, so nothing off it can retrieve them — that is the
+ * real damage and it survives any later `set-gateway`. It ALSO used to weld that localhost host into
+ * the on-chain value; since the field holds a bare CID it no longer does (the serving prefix is the
+ * collection's preference), so promising "the served URL resolves only on THIS machine" would now be
+ * false and would point the creator at the wrong repair.
+ */
 export function localGatewayWarning(flags) {
     const opts = storageOptions(storageOverrides(flags));
     const gateway = opts.backend === 'ipfs' ? opts.ipfs?.gateway : opts.backend === 'arweave' ? opts.arweave?.gateway : undefined;
     if (gateway && /^https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0)\b/i.test(gateway)) {
-        return (`${opts.backend} gateway is ${gateway} — a LOCAL gateway. The served image URL resolves only on THIS machine; ` +
-            `marketplaces and wallets won't load it. Pin to a service with a PUBLIC gateway (e.g. a Pinata dedicated gateway) ` +
-            `via --gateway https://… or ABX_IPFS_GATEWAY.`);
+        return (`${opts.backend} gateway is ${gateway} — a LOCAL gateway, so the bytes would be pinned only to a node on THIS ` +
+            `machine and nobody else could retrieve them. The on-chain field holds the bare content id (a gateway change is ` +
+            `later just ${bold('abx set-gateway')}), but no gateway can serve content that was never pinned publicly. Pin to a ` +
+            `service with a PUBLIC gateway (e.g. a Pinata dedicated gateway) via --gateway https://… or ABX_IPFS_GATEWAY.`);
     }
     return null;
 }
@@ -599,7 +634,10 @@ export async function cmdDeployBody(flags, serveAfter, emit) {
     }
     const name = flags.name ?? 'ABX Self-Host Demo';
     const symbol = flags.symbol ?? 'ABXSH';
-    const royaltyBps = Number(flags['royalty-bps'] ?? 500);
+    // Validate against the CONTRACT's cap here, not just in `set-royalty`: a bare Number() accepted
+    // 1500, printed "royalty 15%" in the confirmation readout, and then lost the whole deploy to a
+    // RoyaltyTooHigh() revert — the expensive tx, and one the creator had already approved.
+    const royaltyBps = flags['royalty-bps'] === undefined ? 500 : parseRoyaltyBps(String(flags['royalty-bps']));
     const port = Number(flags.port ?? process.env.ABX_PORT ?? DEFAULT_PORT);
     const baseUrl = flags['public-base-url'] ?? resolveBaseUrl(port);
     // Creator traits (real OpenSea attributes). Off-chain operator metadata by default (cheap,
@@ -889,7 +927,7 @@ export async function cmdDeployBody(flags, serveAfter, emit) {
             ? { tokenFields: [bakedImage], contentNote: 'content: image staged ON-CHAIN via reader (self-resolving, no custody)' }
             : onchainImage
                 ? { tokenFields: [], contentNote: 'content: image would be staged ON-CHAIN via reader (chunk store) — dry run skips the staging write' }
-                : await prepareContent(flags.image, clone, storageOverrides(flags), !dryRun, onChainUri, uploadRemoteEth, deployer);
+                : await prepareContent(flags.image, clone, storageOverrides(flags), !dryRun, onChainUri, uploadRemoteEth, deployer, flags);
         // Put the description ON-CHAIN (inline) when asked, or always under --onchain-uri
         // (the on-chain renderer can only emit on-chain fields, so an off-chain-only
         // description would simply be omitted). On-chain wins at resolve either way.
@@ -1242,7 +1280,7 @@ export async function cmdDeployOneOfOneEditionBody(flags, emit) {
     const editionSize = parseCopies(flags.copies);
     const name = flags.name ?? 'ABX Edition';
     const symbol = flags.symbol ?? 'ABXE';
-    const royaltyBps = Number(flags['royalty-bps'] ?? 500);
+    const royaltyBps = flags['royalty-bps'] === undefined ? 500 : parseRoyaltyBps(String(flags['royalty-bps']));
     const port = Number(flags.port ?? process.env.ABX_PORT ?? DEFAULT_PORT);
     const baseUrl = flags['public-base-url'] ?? resolveBaseUrl(port);
     const traits = parseDeployTraits(flags);
@@ -1390,7 +1428,7 @@ export async function cmdDeployOneOfOneEditionBody(flags, emit) {
             ? { tokenFields: [bakedImage], contentNote: 'content: image staged ON-CHAIN via reader (self-resolving, no custody)' }
             : onchainImage
                 ? { tokenFields: [], contentNote: 'content: image would be staged ON-CHAIN via reader (chunk store) — dry run skips the staging write' }
-                : await prepareContent(flags.image, clone, storageOverrides(flags), !dryRun, onChainUri);
+                : await prepareContent(flags.image, clone, storageOverrides(flags), !dryRun, onChainUri, undefined, undefined, flags);
         if (flags.description && (onChainUri || flags['description-onchain'])) {
             tokenFields.push({ field: encodeTag(F.description), representation: encodeTag(R.inline), value: toHex(flags.description) });
         }
@@ -1603,7 +1641,7 @@ export async function cmdDeploySeriesBody(flags, emit) {
     warnSignWithoutFor(flags);
     const name = flags.name ?? 'ABX Series';
     const symbol = flags.symbol ?? 'ABXS';
-    const royaltyBps = Number(flags['royalty-bps'] ?? 500);
+    const royaltyBps = flags['royalty-bps'] === undefined ? 500 : parseRoyaltyBps(String(flags['royalty-bps']));
     const port = Number(flags.port ?? process.env.ABX_PORT ?? DEFAULT_PORT);
     const baseUrl = flags['public-base-url'] ?? resolveBaseUrl(port);
     console.log(bold(`\n  ABX Self-Host Toolkit — deploy series\n  ${dim('a multi-token drop, served from chain alone')}`));
@@ -1801,6 +1839,14 @@ export async function cmdDeploySeriesBody(flags, emit) {
                 if (uniform) {
                     contractFields = [imageLocatorField(backendId, `<${backendId}-dir>/{id}${exts[0]}`, true)];
                     info(`would upload ${tokenPaths.length} file(s) as ONE ${backendId} directory → collection image <${backendId}-dir>/{id}${exts[0]} (O(1); ${describeLocatorField(backendId)})`);
+                    // Name the SERVING prefix in the plan too. Without it a preview says "the gateway is the
+                    // collection's preference" and never says what that preference resolves to, so a reader
+                    // fills the blank with the upload gateway they just typed — the same confusion the live
+                    // narration used to cause outright.
+                    if (backendId === 'ipfs' || backendId === 'arweave') {
+                        const { prefix, chosen } = servingGateway(backendId, flags);
+                        info(`served from ${bold(prefix)} ${dim(chosen ? '(your --' + backendId + '-gateway, written on-chain)' : `(public default — nothing written; repoint any time with ${bold('abx set-gateway')})`)}`);
+                    }
                 }
                 else {
                     tokenFields = tokenPaths.map(({ tokenId }) => tokenFieldOf(tokenId, imageLocatorField(backendId, `<${backendId}-url-${tokenId}>`)));
@@ -1816,7 +1862,10 @@ export async function cmdDeploySeriesBody(flags, emit) {
                 const template = `${base}/{id}${exts[0]}`;
                 contractFields = [imageLocatorField(backendId, template, true)];
                 info(`uploaded ${entries.length} file(s) as one ${backendId} directory`);
-                info(`collection image: ${template}  ${dim(`— one field covers every token (O(1); ${describeLocatorField(backendId)})`)}`);
+                const servedTemplate = servedImageUrl(backendId, template, flags);
+                info(`collection image: ${servedTemplate.url}  ${dim(`— one field covers every token (O(1); ${describeLocatorField(backendId)})`)}`);
+                if (servedTemplate.note)
+                    info(dim(`  ${servedTemplate.note}`));
             }
             else {
                 // mixed extensions (or no directory support): per-token url fields (O(N)).
@@ -1828,7 +1877,7 @@ export async function cmdDeploySeriesBody(flags, emit) {
                     if (!locator)
                         throw new Error(`backend ${backendId} returned no public locator for token ${tokenId} — a durable backend (ipfs/arweave) is required for --onchain-uri image hosting`);
                     tokenFields.push(tokenFieldOf(tokenId, imageLocatorField(backendId, locator)));
-                    info(`token ${tokenId} ← ${fname} → ${locator}`);
+                    info(`token ${tokenId} ← ${fname} → ${servedImageUrl(backendId, locator, flags).url}`);
                 }
                 info(`mixed file extensions → per-token image fields (O(N)); a uniform extension enables the O(1) directory template`);
             }
@@ -2153,7 +2202,7 @@ export async function cmdDeployEditionImageBody(flags, emit) {
     const editionSize = parseCopies(flags.copies);
     const name = flags.name ?? 'ABX Edition Series';
     const symbol = flags.symbol ?? 'ABXES';
-    const royaltyBps = Number(flags['royalty-bps'] ?? 500);
+    const royaltyBps = flags['royalty-bps'] === undefined ? 500 : parseRoyaltyBps(String(flags['royalty-bps']));
     const port = Number(flags.port ?? process.env.ABX_PORT ?? DEFAULT_PORT);
     const baseUrl = flags['public-base-url'] ?? resolveBaseUrl(port);
     console.log(bold(`\n  ABX Self-Host Toolkit — deploy edition series\n  ${dim(editionSize === 0n
@@ -2335,6 +2384,14 @@ export async function cmdDeployEditionImageBody(flags, emit) {
                 if (uniform) {
                     imageContractFields = [imageLocatorField(backendId, `<${backendId}-dir>/{id}${exts[0]}`, true)];
                     info(`would upload ${tokenPaths.length} file(s) as ONE ${backendId} directory → collection image <${backendId}-dir>/{id}${exts[0]} (O(1); ${describeLocatorField(backendId)})`);
+                    // Name the SERVING prefix in the plan too. Without it a preview says "the gateway is the
+                    // collection's preference" and never says what that preference resolves to, so a reader
+                    // fills the blank with the upload gateway they just typed — the same confusion the live
+                    // narration used to cause outright.
+                    if (backendId === 'ipfs' || backendId === 'arweave') {
+                        const { prefix, chosen } = servingGateway(backendId, flags);
+                        info(`served from ${bold(prefix)} ${dim(chosen ? '(your --' + backendId + '-gateway, written on-chain)' : `(public default — nothing written; repoint any time with ${bold('abx set-gateway')})`)}`);
+                    }
                 }
                 else {
                     for (const { tokenId } of tokenPaths)
@@ -2898,7 +2955,7 @@ export async function cmdDeployCodeBody(flags, emit) {
     if (mintCount > max)
         throw new Error(`--mint-count ${mintCount} exceeds --max ${max}`);
     const paused = flags.unpaused === undefined;
-    const royaltyBps = Number(flags['royalty-bps'] ?? 500);
+    const royaltyBps = flags['royalty-bps'] === undefined ? 500 : parseRoyaltyBps(String(flags['royalty-bps']));
     const port = Number(flags.port ?? process.env.ABX_PORT ?? DEFAULT_PORT);
     const baseUrl = (flags['public-base-url'] ?? resolveBaseUrl(port)).replace(/\/$/, '');
     const hasPublicUrl = !!(flags['public-base-url'] || process.env.ABX_PUBLIC_BASE_URL);
@@ -3380,7 +3437,7 @@ export async function cmdDeployCodeBody(flags, emit) {
             (transferValidator !== zeroAddress ? ` ERC-721C: enrolled at deploy, permanently (validator ${transferValidator}).` : '') + `\n` +
             `  Surfaces — thumbnail: ${imageDisposition}. traits: ${traitsDisposition}. postparams: ${paramsDisposition}.` +
             ((imageOrphaned || traitsBroken || undeclaredParams.length)
-                ? `\n  ⚠ One or more surfaces resolve to NOTHING marketplaces can see — these are DEPLOY-TIME decisions, not backfillable. Re-run --dry-run after fixing, or pass --yes to ship as-is.`
+                ? `\n  ⚠ One or more surfaces resolve to NOTHING marketplaces can see. Settle them now: fixing one after deploy is an owner-signed re-point + re-render, on a collection that showed a placeholder in between. Re-run --dry-run after fixing, or pass --yes to ship as-is.`
                 : ''), flags);
     }
     // --dry-run: emit the full plan (the on-chain values the skill formats into its confirm table),
@@ -3513,16 +3570,18 @@ export async function cmdDeployCodeBody(flags, emit) {
         // were already set. The alarm now covers only the surfaces it can honestly speak for, and names
         // only the remedies for what is actually broken.
         const anySurfaceBroken = imageOrphaned || traitsBroken;
-        step('Surfaces — what marketplaces will see (all DEPLOY-TIME; not backfillable)');
+        step('Surfaces — what marketplaces will see (settle them NOW; fixing one later is an owner-signed re-point + re-render)');
         (imageOrphaned ? warn : info)(`thumbnail: ${imageDisposition}`);
         // Render-mode / render-home guidance is for the RENDERED-still lanes only. The in-chain
         // Solidity image (--image-renderer) has no off-chain still — nothing to render, host, or refresh.
+        // Hoisted: the `render/storage` row further down needs the same fact, so that a managed provider
+        // (which owns rendering) never trips the fs warning there either.
+        let renderAttached = false;
         if (!imageOrphaned && !hasImageRenderer) {
             if (!hasPublicUrl)
                 info(`  ${dim('render mode (a still is never on-chain):')} ${bold('service')} (auto-render every mint/param change — a live/for-sale drop) · ${bold('once')} (fixed supply) · ${bold('none')} (placeholder). ${dim('freshness: no resolver ⇒ no chain-watcher ⇒ MANUAL/backfill (`abx render` after mints + each param change; the on-chain animation updates live, the bucket still does NOT). Continuous/live stills ⇒ run a resolver.')}`);
             // A managed provider whose descriptor says `render.attached` owns rendering — local
             // ABX_STORAGE_BACKEND is irrelevant, and warning "placeholder forever" is a lie.
-            let renderAttached = false;
             if (hasPublicUrl && !loopbackBaseUrl(baseUrl)) {
                 try {
                     const d = await new AbxServiceClient({ baseUrl, timeoutMs: 2_500 }).descriptor();
@@ -3588,8 +3647,24 @@ export async function cmdDeployCodeBody(flags, emit) {
                 cloudHasPublicBase: renderStorageBackendId === 'cloud' ? !!renderStorageOpts.cloud?.publicBase : undefined,
                 publishesToRemoteResolver: !hasImageRenderer && !(onChainUri && hasImageBase),
             });
-            if (renderStorageCombo.ok)
-                info(`render/storage  ✓ ${renderStorageBackendId}${hasImageBase ? ' + --image-base' : ''}`);
+            // `validateRenderStorageCombo` deliberately scopes itself to the --image-base URL SHAPE and the
+            // remote-resolver lane, so it returns ok for `fs` + --image-base — while the render-home check a
+            // few lines above correctly warns that an fs home means nothing ever uploads the still to that
+            // bucket. Both lines described the same setup and only one said it was broken, and a creator
+            // skimming for the checkmark reads ✓ as approval. The row now defers to that warning rather than
+            // overriding it: same fact, one verdict.
+            // This row is deliberately scoped to whether the --image-base TARGET is valid (a mutable bucket,
+            // not a content-addressed gateway) and whether a remote resolver could fetch what we store — it
+            // is NOT a verdict on the render home, which has its own warning above. Unqualified, though, a
+            // bare `✓ fs + --image-base` sat a few lines under "render storage home is fs … placeholder
+            // forever" and read as though it overruled it. Name what the ✓ covers, and point at the other
+            // line when that one is unhappy, so one setup stops producing two verdicts.
+            const fsHomeUnresolved = renderHome === 'fs' && !renderAttached && !imageOrphaned && !hasImageRenderer;
+            if (renderStorageCombo.ok) {
+                const scope = hasImageBase ? '--image-base is a valid mutable target' : `${renderStorageBackendId} can serve what it stores`;
+                info(`render/storage  ✓ ${scope}` +
+                    (fsHomeUnresolved ? dim(` — but the render home is still ${bold('fs')}; see the warning above, this ✓ does not cover it`) : ''));
+            }
             else
                 warn(`render/storage  ✗ ${renderStorageCombo.reason}`);
         }
@@ -4064,7 +4139,7 @@ export async function cmdDeployEditionCodeBody(flags, emit) {
         throw new Error('--mint-amount 0 with ids being pre-minted at deploy makes no sense — pass a positive --mint-amount, or drop --mint-all/--mint-count to defer minting entirely.');
     }
     const paused = flags.unpaused === undefined;
-    const royaltyBps = Number(flags['royalty-bps'] ?? 500);
+    const royaltyBps = flags['royalty-bps'] === undefined ? 500 : parseRoyaltyBps(String(flags['royalty-bps']));
     const port = Number(flags.port ?? process.env.ABX_PORT ?? DEFAULT_PORT);
     const baseUrl = (flags['public-base-url'] ?? resolveBaseUrl(port)).replace(/\/$/, '');
     const hasPublicUrl = !!(flags['public-base-url'] || process.env.ABX_PUBLIC_BASE_URL);