@artblocks/abx-cli 0.1.0-alpha.9 → 0.2.0

package/skill/reference/operate.md

@@ -0,0 +1,237 @@
+# Operating an existing ABX project
+
+Use this reference for inspection, minting and sales, transfers, fields, gateways, URI pointers,
+royalties, supply, attachments, refreshes, ownership transfer, and locks.
+
+## Contents
+
+- [Read before writing](#read-before-writing)
+- [Mint and run primary sales](#mint-and-run-primary-sales)
+- [Transfer tokens and authority](#transfer-tokens-and-authority)
+- [Operate metadata and data](#operate-metadata-and-data)
+- [Manage economics and supply](#manage-economics-and-supply)
+- [Lock precisely](#lock-precisely)
+
+## Read before writing
+
+Never infer contract type or current authority from the original launch notes. Read the contract:
+
+```bash
+abx state <address>
+abx tokens <address> --json
+abx contracturi <address> --json
+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.
+
+Before every write, run its help and dry-run form when available. Confirm sender, target, value,
+token/id/amount, and permanence. Let the CLI validate contract type; do not send raw ABI calls to make
+an operation fit the wrong family.
+
+## Mint and run primary sales
+
+`abx mint` follows the detected family:
+
+- A 1/1 issues its single token.
+- A Series mints the next id in order; `--count` can mint multiple sequential ids.
+- An edition requires `--token-id` except where the contract has only the single 1/1-edition id, and
+  uses `--amount` for copies. `--count` is not an edition synonym.
+
+Confirm the recipient. Minting may trigger a transfer hook; a hook that vetoes mint will revert the
+whole transaction.
+
+### Shared fixed-price minter
+
+Use the shared minter commands for ordinary ETH primary sales:
+
+1. `abx minter configure <token> …` sets price and allocation. Editions require a token id and use a
+   per-id sale configuration.
+2. `abx set-minter <token> --minter <address>` authorizes the minter.
+3. `abx set-primary-payee <token> --payee <address>` declares payout.
+4. `abx unpause <token>` opens minting when the family supports the pause gate.
+5. `abx minter show <token> …` verifies the public sale state.
+6. `abx minter buy <token> …` is the public purchase path; editions use quantity and token id.
+
+Do not call a sale live until price units, allocation, payee, minter address, pause state, and a
+representative purchase are verified. `abx mint-page` scaffolds a client for the shared minter; it does
+not configure the on-chain sale for you.
+
+Use a custom minter for auctions, allowlists, raffles, free claims, ERC-20 pricing, or other issuance
+rules. The custom contract calls the canonical token's mint authority; the token itself remains a
+factory clone. Read [capabilities.md](capabilities.md).
+
+## Transfer tokens and authority
+
+`abx transfer` moves token ownership/copies, not contract administration.
+
+- A 721 transfer names token id and destination.
+- An edition transfer names token id, amount, destination, and source holder because an id can have
+  multiple holders.
+- Creator-token validation or a transfer hook may reject the move. Diagnose the actual revert; do not
+  bypass or clear an enforcement mechanism without the owner's explicit intent.
+
+`abx set-admin --to <address>` transfers contract authority. Treat it as a high-risk, potentially
+irrecoverable handoff:
+
+1. Verify the recipient is correct for the active chain.
+2. Inventory unfinished operations and unlocked surfaces.
+3. State which powers move and which external controllers remain separate.
+4. Receive exact human confirmation.
+5. Execute once, then read state from chain to prove the new owner.
+
+Never interpret a token transfer as a sale listing. ABX has no secondary order book; a marketplace or
+manual transfer handles secondary exchange.
+
+## Operate metadata and data
+
+### URI pointers and renderers
+
+Use `set-token-uri`, `set-contract-uri`, and `set-renderer` only after reading the current configuration
+and verifying the destination. Switching `set-renderer --off` can place an HTTP resolver in front of
+content that remains stored on-chain. Switching to the canonical renderer makes configured on-chain
+fields self-resolving when the contract supports them.
+
+Never hand-build a resolver path. Read `tokenURI`/`contractURI`, decode it, and follow what the
+contract actually returns. A correct-looking URL constructed from memory is not evidence.
+
+### Fields
+
+`abx set-field` writes one metadata field representation at token or collection scope. Representations
+include inline data, reader/chunk pointers, hashes, public locators, and renderer pointers as supported
+by the contract. Collection-scope values act as shared defaults; token-scope values override them.
+
+Use reserved fields such as description, attributes, creator, license, display notes, and links
+according to command help. Verify the resulting provenance in decoded metadata. On-chain-wins means a
+new on-chain value can intentionally supersede a resolver projection.
+
+### Gateways
+
+`abx set-gateway` changes the serving prefix for IPFS/Arweave locator representations without moving
+the content. Verify a representative locator through the new gateway before changing it. A gateway
+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. 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.
+
+`--chunk-size <bytes>` overrides the default on-chain split size (~22 KB) — the same flag
+`deploy-code` accepts (see [code.md](code.md#choose-the-runtime-lane)). A small value forces a
+multi-chunk layout, which is the cheap way to exercise growing/shrinking a program across several
+chunks (including the on-chain removal of surplus chunks when shrinking) without needing a large
+real program.
+
+### Refresh and URI events
+
+`abx refresh` asks external marketplaces to fetch metadata again; it does not fix the metadata or
+mutate canonical state. First prove that the current URI resolves and returns the intended document.
+For editions, `ping-uri` re-emits native URI events for selected ids after a repoint. Use the smallest
+id set needed and verify the new path before signalling indexers.
+
+## Manage economics and supply
+
+Use `set-royalty` to change receiver/rate within the collection's permanent royalty ceiling. Use
+`set-royalty-cap` only to lower that ceiling. State the old and new values and confirm the irreversible
+loss of future headroom.
+
+Series supply caps and edition per-id caps are monotonic downward. Before lowering one, read the
+Series issuance cursor or the edition id's live supply, respectively; never propose a value below that
+floor. For editions, name the id and distinguish its live per-id cap from aggregate collection supply.
+
+Pause/unpause controls the supported mint gate, not transfers or every external minter behavior.
+Read state after changing it.
+
+Primary payee declares sale proceeds; royalty receiver handles secondary royalty reporting. Keep them
+separate. Changing one does not update the other.
+
+## Lock precisely
+
+Lock last, after production-path verification. Every lock freezes a different surface:
+
+**Never lock a token or collection URI to a domain the creator does not own.** A managed remote's
+URL is not creator custody. Route a creator-controlled domain only when the provider supports it,
+verify the route, then lock that domain. ABX Services does not currently support custom-domain
+routing, so never lock an `abx.io` URI. The CLI refuses to do so.
+
+| Lock | Freezes | Does not necessarily freeze |
+|---|---|---|
+| `lock-field` | one token/collection field representation | other fields, URI pointer, program, params |
+| `lock-uri` | URI configuration/pointer at selected scope | program/dependencies/params/hooks |
+| `lock-script` | code-project script chunks | dependencies, metadata, params, external renderer code |
+| `lock-dependencies` | dependency list and registry pointer | bytes returned later by a live registry entry |
+| `lock-param-hooks` | configure/transfer/augment addresses | behavior behind an upgradeable address |
+| governed schema/value lock | writes governed by that schema/key | unrelated or ungoverned params; some inherited defaults |
+| ownership transfer | future owner-only authority at this contract | powers held by external minters/hooks/providers |
+
+For a code project, metadata locks alone do not freeze the program. A strong freeze normally requires
+script, dependency, relevant field/URI, hook, and governed-parameter decisions, plus immutable external
+renderer/hook/dependency deployments.
+
+Important qualifications:
+
+- An ungoverned parameter remains writable despite metadata locks.
+- A schema-welded token value is stronger than a collection default inherited by many tokens; the
+  recovery path may still allow a poisoned collection default to be cleared.
+- A registry dependency may return different bytes behind a frozen reference.
+- A locked pointer to an upgradeable proxy fixes the address, not its behavior.
+- A transfer-hook address represents a standing ability to veto mints/transfers. Freezing an empty
+  hook set is the proof that this power cannot later be added.
+- `lock-field` targets one scope (token, or `--collection`); a token-scope value wins over a
+  collection-scope one when both are set. Locking a scope that ISN'T actually serving the value
+  freezes an empty or overridden slot, not what a viewer sees — the CLI refuses this by default and
+  names the correct command; only `--force-field` proceeds (with a loud warning, never silently).
+  Check `abx tokenuri --token <id>`'s `abx_provenance` (or just try the lock without `--force-field`)
+  before assuming a scope holds the value.
+
+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/services.md

@@ -0,0 +1,173 @@
+# First-party services and feedback
+
+Use this reference for the public ABX service, API-key login, hosted resolver/rendering, or feedback.
+For provider-independent hosting and migration, also read [hosting.md](hosting.md).
+
+## Contents
+
+- [First-party service](#first-party-service)
+- [Creator wallet and sponsorship](#creator-wallet-and-sponsorship)
+- [Feedback targets](#feedback-targets)
+
+## First-party service
+
+The documented endpoints are:
+
+- documentation: `https://docs.abx.io`
+- service catalog, account, and control: `https://services.abx.io`
+- public token data: `https://resolver.abx.io` (discover it from the catalog; do not hardcode it)
+- OAuth discovery: `https://services.abx.io/.well-known/oauth-authorization-server`
+- manual signup fallback: `https://services.abx.io/signup`
+
+The first-party provider has the built-in remote name `abx`:
+
+```bash
+abx remote abx
+```
+
+It needs `ABX_SERVICES_API_KEY` in the project's ignored `.env`; it does not need
+`ABX_REMOTE_ABX_URL`. When the key is absent, use:
+
+```bash
+abx auth login
+```
+
+The CLI starts the OAuth device flow and shows a verified browser URL plus a matching short code.
+The human completes name, email, one-time-code verification, and approval in that browser. The CLI
+polls at the provider-declared interval, receives the API key, and writes it directly to ignored
+`.env` without printing it. The browser never receives the key. Do not ask the human to paste an OTP
+or key into chat. `--no-open` leaves the browser handoff as a link; `--force` is required to replace
+an existing local credential, but does not revoke the displaced provider key. For normal rotation,
+run `abx auth logout` and then `abx auth login`; reserve `--force` for recovery. The CLI refuses
+tracked or unignored `.env` files.
+
+The issued API key is long-lived and remains valid until it is revoked. Reuse the stored key across
+tasks and agent sessions; do not start a new login merely because a task or conversation ended. If
+`abx remote abx` authenticates successfully, no login is needed. `abx auth login` also detects an
+already loaded credential and reuses it instead of issuing another.
+
+In an agent runner, start `abx auth login --no-open` with a short initial yield or a resumable
+background session. Relay the printed URL and code immediately while that same process keeps polling,
+then resume it after human approval. Do not start another login or add an outer retry loop. If the
+runner cannot yield control while a command waits, ask the human to run the command in their terminal.
+
+Logout only for intentional teardown, suspected compromise, deliberate rotation, or to free an
+active-key slot. When revoking, do not only delete the local value:
+
+```bash
+abx auth logout          # first-party service
+abx auth logout <name>   # another OAuth-capable named remote
+```
+
+Logout discovers the provider's RFC 7009 endpoint, revokes the current key, and only then removes the
+matching `.env` assignment. If the key came from a shell or another environment source, the CLI
+revokes it and tells the human where it still needs to be unset. A repeated logout with no active
+local credential is safe.
+
+An account may have up to five active keys. The service stores hashes, so it can list key metadata
+but cannot recover a lost secret. Use `abx auth keys` to inspect active keys and
+`abx auth revoke-key <key-id>` to revoke an unused non-current key. Use `abx auth logout` for the
+current key. Only create another key when a separate environment actually needs its own credential.
+
+Use `/signup` only as the manual recovery path. It shows the raw key once, so the human—not the
+agent—must place it in `.env`. An already verified email reuses its account and may receive another
+key, subject to the same limit.
+
+Availability, pricing, and quotas are service policy rather than protocol guarantees. Confirm current
+terms before making a durable hosting choice and keep the exit route explicit: the same remote-service
+contract supports another provider or a creator-operated resolver/effects deployment.
+
+Before depending on hosted behavior, inspect the live descriptor with `abx remote abx`; do not infer
+capabilities from this file. A remote is a provider catalog and may advertise different HTTPS
+origins for token resolution, control, account operations, and creator wallets. Trust the advertised
+interface endpoint, not a guessed hostname. Use `--remote abx` on commands that accept a managed
+resolver and verify the resulting public surfaces as described in [hosting.md](hosting.md).
+
+## Creator wallet and sponsorship
+
+An account with a verified email can use one persistent ABX creator wallet. The
+`ABX_SERVICES_API_KEY` identifies the account but cannot sign. `--sponsor` discovers the provider's
+`abx-creator-wallet/v1` endpoint and provisions or reuses the wallet. The first sponsored command
+asks the human to match one code and approve a Privy agent grant. The CLI keeps the rotating grant in
+the operating system's credential store and reuses it for up to 30 days, unless the creator revokes
+it first. The request-signing key remains memory-only. A reused grant removes another browser step; it does
+not remove the dry run, transaction summary, or production confirmation.
+
+The approval is authority for the agent to use the creator wallet, not approval of one displayed
+transaction. Review each exact network and transaction plan in the terminal. The creator can inspect
+and revoke active grants at `https://services.abx.io/authorize`.
+
+Treat the live descriptor and account capabilities as the authority for sponsored networks. The
+public [network table](https://docs.abx.io/docs/reference/deployments) is the human-readable summary,
+but it does not guarantee sponsorship for an account or moment. When the creator has not selected
+another signer, prefer this lane for an eligible testnet operation. For production, prove the flow on
+the paired testnet and repeat the production warning before confirmation. Before using it:
+
+1. run `abx auth login` if the account has no API key;
+2. inspect `abx capabilities --json` and the command help;
+3. run the same command with `--dry-run --json`;
+4. summarize the network, creator-wallet address, transaction group, zero value, permanent choices,
+   and any experimental or beta status;
+5. repeat with `--sponsor`; if no usable grant exists, give the human the verified URL and code and
+   resume the same command after approval.
+
+The lane accepts zero-value calls and receipt-dependent staged content groups up to the live network
+and provider policy. ABX does not impose an additional per-transaction gas ceiling. Use
+`abx deploy-contract` for exact already-compiled creation bytecode; its sponsored path calls the
+keyless CREATE2 proxy because provider-backed raw creation is unsupported. The constructor therefore
+sees the proxy as `msg.sender`; use explicit constructor arguments for ownership. ABX does not
+compile or audit it. Never add retries around a sponsored write. An `unknown` outcome means the
+provider may have submitted it: preserve the operation ID and reconcile status before any new send.
+
+Sponsorship is optional service policy, not protocol support. `--send`, `--sign`, and `--unsigned`
+remain first-class bring-your-own alternatives. Honor an explicit choice of any of them. If the
+provider does not advertise the chain, the account is ineligible, or the transaction group exceeds
+policy, select one of those lanes rather than refusing the underlying operation. Do not use
+sponsorship on a production network unless the live descriptor, account capabilities, and command
+all explicitly support it. Never infer eligibility merely because the CLI recognizes the lane.
+
+## Feedback targets
+
+`abx feedback` has two deliberately separate targets:
+
+| Intent | Command | Recipient |
+|---|---|---|
+| ABX protocol, contracts, CLI, SDK, skill, or docs | `abx feedback` | core ABX team |
+| A remote provider's resolver, rendering, auth, or operations | `abx feedback --remote <name>` | that provider |
+
+For first-party hosted-service feedback use `--remote abx`. A third-party remote can advertise the
+optional `abx-service-feedback/v1` interface and operate its own feedback store. Never send
+provider-specific incidents through core feedback merely because both first-party targets currently
+share infrastructure.
+
+Discovery and report previews are public. Submission (`--yes`) and `--mine` require the same key
+created by `abx auth login`; login once rather than creating a separate feedback credential. Run the
+command without report flags to inspect its live schema and instructions. To report, provide the
+required structured flags; use `--detail-file` or `--context-file` rather than fragile shell quoting
+for longer content. The CLI shows the exact destination and payload first. Review and redact the
+preview with the human, then repeat with `--yes` only after explicit approval.
+
+```bash
+# Preview core feedback; nothing is sent.
+abx feedback --area cli --kind bug --summary "Concise summary" --detail-file report.md
+
+# After the human approves this exact preview.
+abx feedback --area cli --kind bug --summary "Concise summary" --detail-file report.md --yes
+
+# Provider-specific preview.
+abx feedback --remote abx --component rendering --kind bug --summary "Concise summary"
+
+# Review reports previously submitted with the current key.
+abx feedback --mine
+abx feedback --remote abx --mine
+```
+
+Do not attach `.env`, credentials, wallet/session URLs, full transcripts, or unrelated source files.
+Prefer the smallest reproduction and relevant version/chain/address context. The API key authenticates
+the reporter; hosted-service entitlement is evaluated separately. It never grants transaction-signing
+authority.
+
+Use the CLI instead of hand-written HTTP or retry loops. The device flow already handles pending,
+slow-down, and transient polling responses until its fixed expiry. Treat `401` as missing/invalid credentials,
+`403` as recognized credentials without the required entitlement, and schema/interface errors as a
+request or provider-contract mismatch. Read [diagnose.md](diagnose.md) and make one state transition.