@artblocks/abx-cli 0.1.0-alpha.40 → 0.1.0-alpha.41

package/skill/SKILL.md

@@ -9,7 +9,7 @@ description: >-
   change an ABX collection, or to determine whether ABX supports a mechanic.
 compatibility: Drives @artblocks/abx-cli on Node 22.13+. Co-versioned with the CLI; install or refresh with `abx skill install`.
 metadata:
-  version: "0.1.0-alpha.40"
+  version: "0.1.0-alpha.41"
 ---
 
 # ABX
@@ -106,8 +106,10 @@ Run `abx capabilities --json` for the current matrix, then load [deploy.md](refe
 
 Important boundaries:
 
-- `deploy-code --copies` supports `--script`, dependencies, and Solidity image/attributes renderers.
-  It does not currently support `--code-dir`, `--image-base`, or `--resume`.
+- `deploy-code --copies` supports `--script`, `--code-dir`, dependencies, Solidity image/attributes
+  renderers, `--image-base` (a deterministic per-id off-chain still, mutually exclusive with
+  `--image-renderer`), and `--resume` (a per-id mint diff — pass the same content flags plus
+  `--mint-amount` if the original deploy premint ids).
 - `--onchain-image` works for static 721s and editions in hot or wallet-signing lanes. It cannot be
   prepared as one cold `--unsigned` bundle because staged transactions depend on prior receipts.
 - A code project may need no public host when its image/traits are computed by Solidity renderers.
@@ -129,7 +131,7 @@ Before deploying, write down the promised value for each applicable row:
 | Animation/live view | the decoded `animation_url`, loaded with a real minted token |
 | Marketplace traits | decoded `attributes`, not merely console output from the program |
 | Parameters and values | `abx state` for schemas; `abx tokens --json` for token values |
-| Attached artifacts | resolver metadata and `/data/<key>`; attachments are not enumerable in bare on-chain metadata |
+| Attached artifacts | `abx artifacts <addr> --token <id>` (entries + current/stale effect rows); attachments are not enumerable in bare on-chain metadata |
 | Byte integrity | `abx verify <addr>` |
 | Hosted lifecycle | `abx status --remote <name> --watch` or provider status |
 

package/skill/reference/code.md

@@ -28,8 +28,11 @@ renderers, marketplace stills and traits, seeds, dependencies, parameters, and c
 
 Without `--copies`, the contract is SeriesCode (ERC-721). With `--copies <n|open>`, it is EditionCode
 (ERC-1155): N generated ids, each with multiple copies. EditionCode currently supports scripts,
-dependencies, and field renderers. It does not support `--code-dir`, `--image-base`, or `--resume`.
-Run `abx capabilities --json` immediately before planning.
+directory builds (`--code-dir`), dependencies, field renderers, deterministic per-id off-chain stills
+(`--image-base`), and `--resume` for an incomplete deployment (see
+[diagnose.md](diagnose.md#incomplete-deployments) — the mint leg diffs per id, with a new
+`--mint-amount` naming each premint id's intended copy count). Run `abx capabilities --json`
+immediately before planning.
 
 For one generated work with 100 copies, use `--max 1 --copies 100`. Omitting `--max 1` leaves the
 default multi-id space, producing multiple generated ids with 100 copies available for each id.
@@ -105,16 +108,22 @@ a still published to a deterministic public `--image-base` is a manual/backfill
 after relevant parameter changes. An on-chain animation plus automatically updating off-chain still
 requires an operator watching state.
 
-EditionCode does not currently accept `--image-base`. Give it an on-chain image renderer, or run a
-resolver/effects path (`deploy-effects` for continuous rendering; `render --remote` for one-shot
-publication). Do not treat its on-chain animation as a marketplace still.
+EditionCode now accepts `--image-base` too: the same `{base}/{id}.png` url-template, one id space
+finer — `{id}` is the EditionCode id, and every copy of that id shares the one image (there is no
+per-copy addressing). The effect runner never renders an id with zero live copies (no mint-time seed
+has been drawn yet for it), so an unminted premint id is skipped, not errored — it renders once the
+first copy mints. `--image-base` stays mutually exclusive with `--image-renderer` on both lanes.
 
 ### Build directory
 
 Use `--code-dir` for an application bundle whose files are uploaded and addressed as a code artifact.
-It requires external storage and public resolution. Inspect the built output, not only the source
-tree, and verify that every referenced asset is included. `--code-dir` is not yet supported with
-`--copies`.
+It requires external storage and public resolution — a backend without directory upload (`fs`, the
+local default) is refused; pick `--backend ipfs` or `--backend arweave`. Inspect the built output, not
+only the source tree, and verify that every referenced asset is included. The live view 302s through
+the gateway, so the gateway must serve HTML (the shared Pinata public gateway does not — use a
+dedicated gateway or Arweave). `--code-dir` works with `--copies` too (EditionCode): the same upload,
+the same on-chain `code` field, the same gateway rules — `--script` and `--code-dir` remain mutually
+exclusive on both lanes.
 
 ## Plan Solidity field renderers
 

package/skill/reference/deploy.md

@@ -51,7 +51,9 @@ Use `--onchain-uri --backend arweave|ipfs|cloud`. The CLI uploads media, bakes i
 on-chain JSON, and does not require an ABX resolver. This is often the simplest durable path for
 static collections:
 
-- Arweave provides pay-once permanent custody through the configured uploader.
+- Arweave provides pay-once permanent custody through the configured uploader, but needs the
+  optional `@artblocks/abx-storage-arweave` package installed alongside the CLI first (see
+  [hosting.md](hosting.md#arweave)) — it is not part of the default install.
 - IPFS requires maintained pinning and a public gateway; a local kubo gateway is development-only.
 - Cloud requires an authenticated upload endpoint and a distinct public read base/CDN URL.
 
@@ -154,7 +156,12 @@ Do not import code-edition limits into static editions or vice versa. Use the ca
 1. Run `abx doctor`, storage/remote checks needed by the selected path, and command help.
 2. Run the exact command with `--dry-run --json` and a known `--for` address when needed.
 3. Read back contract family, id/copy arithmetic, custody, resolution, public URLs, signer lane,
-   initial mint, transaction count, cost/reach warnings, and irreversible options.
+   initial mint, transaction count, cost/reach warnings, and irreversible options. The JSON payload's
+   `plan` object (every `deploy`/`deploy-series`/`deploy-code` emit, including `--resume`) carries
+   most of this pre-structured — `transactions`, `roles`, `royalty`, `custody`, `mint`, `estimate`,
+   `warnings`, and (code lanes) `surfaces`/`dependencies` — versioned via `plan.schemaVersion`. Prefer
+   it over parsing the human prose for anything it covers; a field it has no answer for is `null`, not
+   absent.
 4. Receive explicit confirmation.
 5. Run the same normalized command without `--dry-run`; do not start another write using the EOA.
 6. Capture the chain, contract address, deploy block, owner, storage locators, and resolver/remote.

package/skill/reference/diagnose.md

@@ -76,8 +76,15 @@ Before resume:
 - read the resume dry run and confirm every proposed transaction;
 - ensure no second writer is operating the same EOA.
 
-EditionCode resume is not currently supported. Inspect state and stop for an explicit recovery or new
-deployment decision rather than applying the 721 recipe.
+EditionCode (`--copies`) targets are supported too — pass the exact same content flags the original
+deploy used, minus `--copies` itself (the standard was fixed at creation and is read from chain, not
+re-specified). The one difference from a 721 resume: name the intended premint plan with
+`--mint-count`/`--mint-amount` if the original deploy premint any ids — the mint leg diffs **per id**
+against that id's own on-chain copy count, not a single whole-contract total, and each shortfall sends
+as one transaction regardless of how many copies are missing. Getting `--mint-count`/`--mint-amount`
+wrong under-reports (an id you meant to premint stays at zero) rather than over-mints (a token cannot
+be un-minted, so the diff only ever tops up a shortfall) — but confirm the intended plan with the
+human before sending if there is any doubt about what the original deploy meant to premint.
 
 ## RPC and chain failures
 
@@ -154,6 +161,12 @@ idempotently skip an existing current artifact. A PostParam change produces a ne
 the watcher or run the explicit one-shot path. Solidity image renderers have no effects job—diagnose
 their on-chain call instead.
 
+`abx artifacts <addr> --token <id> --json` is the direct check for steps 5–7: it reports every
+registered effect row (current and stale) against the token's active `inputsHash`, without fetching
+and parsing the whole served document. A row present but labeled `stale` means a param changed since
+it rendered — re-render, don't assume it's missing. Add `--remote <name|url>` for a hosted project;
+the real artifact set lives on the resolver that serves it, not in this node's local projection.
+
 ## Secret-safe reporting
 
 Include command name, CLI version, chain key, redacted host labels, contract address, transaction hash,

package/skill/reference/hosting.md

@@ -128,6 +128,13 @@ change that prefix without changing the content.
 
 ### Arweave
 
+`--backend arweave` (the default `turbo` provider) needs the optional
+`@artblocks/abx-storage-arweave` package installed alongside the CLI — it is not part of the
+default install, deliberately, so a default `abx` install stays free of Turbo's browser
+wallet-connector dependency tree. If it is missing, the CLI names the exact install command
+(`npm install @artblocks/abx-storage-arweave`) rather than failing unhelpfully; run that command
+once, then retry. `--provider http-bundler` needs neither this package nor any of its dependencies.
+
 The accepted upload and a retrievable gateway object are separate lifecycle states. Use
 `abx storage status <locator> --json`; wait for `ready` instead of uploading duplicates during
 propagation. Upload deduplication is success, not an instruction to top up or switch backends.
@@ -165,6 +172,25 @@ Verify the operational graph:
 5. Token metadata exposes the resulting image/attributes.
 6. A PostParam change reaches the watcher and creates the next inputs-hash render.
 
+### SQLite maintenance for a long-running node
+
+The self-hosted store is one SQLite file. `abx serve` already reclaims freed pages automatically in
+small bounded passes between chain-watch ticks — never inline with a request, so it never adds
+latency to a metadata read. Nothing to schedule for that half.
+
+The other half is explicit and never automatic: a store created before this maintenance shipped
+needs a one-time conversion.
+
+```bash
+abx vacuum                          # status: auto_vacuum mode, page count, freelist size
+abx vacuum convert                  # one-time full VACUUM — only when abx vacuum says the store needs it
+abx vacuum incremental [--pages n]  # one bounded reclaim pass on demand (not running abx serve? use this)
+```
+
+Run `abx vacuum convert` deliberately, not on a schedule: it rewrites the entire file and can briefly
+need up to ~2x its on-disk size. Check `abx vacuum` first; if it already reports `auto_vacuum:
+incremental`, there is nothing to convert.
+
 ## Use lifecycle states
 
 Prefer status over retries. Typical nonterminal states include deployment accepted, indexing,

package/skill/reference/operate.md

@@ -22,8 +22,17 @@ abx tokens <address> --json
 abx contracturi <address>
 abx tokenuri <address> --token <id>
 abx verify <address> --json
+abx artifacts <address> --token <id> --json
 ```
 
+`abx artifacts` reads a token's `artifacts` manifest directly, without fetching and parsing the whole
+served document — entries plus every registered effect row (current and stale, labeled against the
+token's active `inputsHash`). Report which surface answered: this node's local projection, or (with
+`--remote <name|url>`) the hosted resolver that actually owns a hosted project's real artifact set.
+Neither "not registered here" nor "not registered on that remote" is an error — both return a stable
+`{surface, registered, available, reason, entries, effects}` shape. Nothing it reports is onchain data
+itself; every entry is a resolver-published projection.
+
 Use `abx status` or its remote form for projection/render lifecycle. Record active chain, detected
 family, owner/admin, supply and pause state, minter/payee, royalty/cap, URI renderer/pointers, code
 dependencies, schemas/hooks, and lock state.
@@ -116,15 +125,29 @@ repoint is not a re-upload and does not change the committed CID/transaction id.
 
 ### Attachments versus parameters
 
-`abx attach <addr> <key> <locator>` records a named artifact. The resolver exposes the complete
-artifacts list and `/data/<key>` retrieval. Bare on-chain metadata cannot enumerate arbitrary field
-keys, so consumers need a resolver to discover all attachments even when each locator is durable and
-hash-anchored.
+`abx attach <addr> <key> <locator>` records a named artifact. It prints the CANONICAL fetch URL for
+every key (`{base}/{chainId}/{address}[/<id>]/data/<key>`) directly — never hand-build that route.
+It also distinguishes the on-chain field write from off-chain SERVING: an on-chain write can succeed
+while nothing can serve it. With no resolver base baked in at all, it warns there is no serving path
+whatsoever. With one baked in, it probes whether a resolver actually answers for this token right
+now (before the write, since the key itself doesn't exist yet) and warns if not — "the on-chain
+document carries reserved fields only" is a real gap creators hit; the write landing is not proof
+anything can serve it. Bare on-chain metadata cannot enumerate arbitrary field keys, so consumers
+need a resolver to discover all attachments even when each locator is durable and hash-anchored.
 
 PostParams are different: the parameter store enumerates schemas and values on-chain. Read schemas
 with `state` and values with `tokens --json`. Parameters do not require a resolver merely to be
 canonical or enumerable.
 
+### Replacing an unlocked script
+
+`abx replace-script <addr> --script <file>` ships a fix to a code project's on-chain program any
+time before `abx lock-script`. It refuses outright — never warns and proceeds — on a locked script
+or a target that isn't SeriesCode/EditionCode. It diffs by content against what's on-chain (an index
+that already matches is never re-sent), folds every write and remove into ONE atomic transaction (so
+a revert can never leave a half-applied script), and reads the completed script back to verify exact
+reassembly before reporting success. Prefer this over hand-encoding `setScriptChunk` calls.
+
 ### Refresh and URI events
 
 `abx refresh` asks external marketplaces to fetch metadata again; it does not fix the metadata or
@@ -179,3 +202,19 @@ Important qualifications:
 Use `abx verify` and direct state reads to enumerate what remains mutable. Describe the guarantee as
 specific stored values and addresses that can no longer change; do not promise immutable output unless
 every live input and external implementation has actually been bounded.
+
+`abx state <address> --json` reports every lock above in one `locks` object — token/contract URI,
+script, dependencies, param hooks, and the standard `METADATA_FIELD` set — each as `true` (frozen),
+`false` (open), or `null` (unread; never report an unread lock as off). A project's own custom field
+keys are real and independently lockable but are not enumerable from a bare head read; say so rather
+than implying the field scan is exhaustive. Every lock is independent: never infer one lock's state
+from another's.
+
+`abx verify --json` separates two verdicts that must not be conflated: `ok`/`contentIntegrity` is
+content-integrity ONLY (a hash mismatch, or none to check) and is the only field the exit code
+reflects; `availability` is a sibling verdict for render/serve readiness (`available` / `partial` /
+`unavailable` / `unknown`) that a missing render or an un-refetched `ipfs`/`arweave`/`url` locator
+moves, while `ok` stays unaffected by design. Report both, never collapse one into the other.
+`abx verify` also flags whether the project's stored `tokenURIRenderer`/generator pointers are the
+CURRENT canonical singletons — a `false` here means an older-but-working deployment (or a fully
+custom one), never "broken".

package/skill/reference/setup.md

@@ -70,6 +70,20 @@ The local projection and managed Arweave identity remain in `.abx-self-host/` un
 `ABX_DATA_DIR` overrides it. That runtime directory is separate from the renamed `abx` skill and is
 not being renamed. Back up the managed Arweave key with `abx storage backup-key`; never print it.
 
+Every WRITE command (`deploy*`, `add`, `index`, `mint`, `set-*`, …) resolves `.abx-self-host`
+strictly relative to the current directory — it never searches upward, so it never creates a
+project's state somewhere unexpected. A handful of READ commands (`status`, `state`, `verify`,
+`doctor`, `capabilities`, `tokens`, `tokenuri`, `contracturi`, `inspect`, `minter show`) DO search
+upward, git-style, for an already-existing `.abx-self-host` if the current directory doesn't have
+one of its own — bounded at the home directory, a `.git` root, or the filesystem root. Practical
+consequence: `cd`-ing into a project's `contracts/` subdirectory before `abx status` still finds
+that project; the same `cd` before `abx add`/`abx deploy*` creates a NEW, empty node right there
+instead. If a status/verify/etc. answer looks emptier than expected, or a write seems to have
+landed in the wrong place, run bare `abx status` — its `data: <path>` line names the exact
+directory that answered, including a note when it was found by searching upward — or set
+`ABX_DATA_DIR` explicitly rather than guessing. See [Local data
+directory](https://docs.abx.io/docs/using-abx/self-hosting#local-data-directory) for the full rule.
+
 ## Choose one signing lane
 
 Every write uses one of three lanes: