@finchtech/cli 0.3.6 → 0.3.7

package/README.md

@@ -18,7 +18,7 @@ ZIP import failures return `AGENT_MARKET_REQUEST_INVALID`, exit code `2`, and `f
 
 Intent HTTP failures include `remotePath: "/api/skills/intents"`, `remoteStatus`, and available safe correlation IDs. `responseIssue` distinguishes `transport_failed`, `body_read_failed`, `empty_body`, `invalid_content_length`, `response_too_large`, `invalid_json`, and `schema_mismatch`. Schema failures include at most eight `schemaIssues` with known field paths and validation keywords; an empty path means the response root or an unrecognized field, whose name is withheld. No response values, arbitrary property names, URLs, or raw causes are printed. Malformed success responses are rejected during `intent`, before signing or writing a pending-send marker. Use the returned recovery command for the same publication; the CLI never automatically retries intent requests or resubmits transactions. The fingerprint identifies the local recovery journal, not a server trace; use returned remote IDs to correlate server logs.
 
-The CLI measures the exact final multipart request, including metadata and framing. Requests above 4,000,000 bytes emit a structured SKILL_UPLOAD_NEAR_LIMIT warning on stderr and continue; requests above 4,500,000 bytes fail before upload. Exactly 4,000,000 bytes do not warn; exactly 4,500,000 bytes warn and continue. These MB thresholds are decimal. The manifest allowance is separately 3 MiB (3,145,728 bytes) on upload and reads. Repacking a compressed source ZIP may increase its size. Passing admission does not certify production upload success or authorize replaying a previously failed publication.
+The CLI measures the exact final multipart request, including metadata and framing. At or below 4,000,000 bytes it posts that request to the inline upload route. Above it the object goes through the staged transport instead: the CLI asks for a signed URL, writes the bytes straight to storage, and has the server read them back, verify them and pin them, so the platform's 4,500,000-byte request-body limit does not apply. These MB thresholds are decimal. The per-object ceilings are enforced against the final object either way: 30 MiB (31,457,280 bytes) for a package, 5 MiB for a cover, and 3 MiB (3,145,728 bytes) for a manifest. The package ceiling is one shared constant, applied by upload admission, by the retrieval route, by this client before it uploads, and by this client when it downloads, so a package that publishes is a package that reads back. Repacking a compressed source ZIP may increase its size. Passing admission does not certify production upload success or authorize replaying a previously failed publication.
 
 The command groups are `wallet`, `login/status/logout`, `site`, `mcp doctor`, `mcp authorize`, `mcp grant`, `creator`, `credentials`, `intent`, `operation show`, `purchase`, `task`, and `skill`. Run `finch --help` for the exact command list as one JSON value.
 
@@ -55,11 +55,11 @@ Version 0.3.1 fixes Skill search continuation: pass the returned `nextCursor` un
 Older clients receive an upgrade message from the Skill search API.
 
 Version 0.3.0 upgrades Skill publication and encrypted delivery together. Upgrade with
-`pnpm add -g @finchtech/cli@0.3.6` and verify `finch --version` before publishing new Skills
+`pnpm add -g @finchtech/cli@0.3.7` and verify `finch --version` before publishing new Skills
 or downloading encrypted Skills from the upgraded gateway. Older CLI versions cannot use
 the new encrypted delivery, including for historical Skills; 0.3.0 retains historical package support.
 
-A single `.zip` passed to `skill publish-submit --path` or `skill version-submit --path` is expanded locally before filtering and primary-document hashing; request a `file` source plan for this input. Directory inputs keep ZIP assets as ordinary files. Imports support stored/DEFLATE ZIPs up to 10 MiB compressed and expanded, with at most 1024 entries. Unsafe paths, symbolic links, encrypted ZIPs, ZIP64, conflicting entries, and corrupt content are refused. Include `SKILL.md`, `README.md`, or one unambiguous root Markdown document.
+A single `.zip` passed to `skill publish-submit --path` or `skill version-submit --path` is expanded locally before filtering and primary-document hashing; request a `file` source plan for this input. Directory inputs keep ZIP assets as ordinary files. Imports support stored/DEFLATE ZIPs up to the package ceiling compressed and expanded, with at most 1024 entries. Unsafe paths, symbolic links, encrypted ZIPs, ZIP64, conflicting entries, and corrupt content are refused. Include `SKILL.md`, `README.md`, or one unambiguous root Markdown document.
 
 New Skills publish a DAG-CBOR SkillRoot hash in one graph bundle. Existing Skill identities keep ZIP-hash updates. New Skills require this updated CLI; it verifies every object and decrypts protected files locally into an ordinary ZIP. Historical ZIP downloads and whole-package decryption remain supported. A pending publication reuses its uploaded bytes and saved root commitment on resume.
 
@@ -90,8 +90,8 @@ not a valid repair. ZIP imports also reject symbolic links.
 
 Source errors keep exit code 2 and `AGENT_MARKET_REQUEST_INVALID`. Parse the JSON string in `error.state`
 for `diagnosticCode`: `SKILL_SOURCE_SYMLINK_UNSUPPORTED`, `SKILL_SOURCE_UNREADABLE`, or
-`SKILL_UPLOAD_SIZE_INVALID`, `SKILL_SOURCE_ZIP_INVALID`, `SKILL_SOURCE_PRIMARY_DOCUMENT_INVALID`, `SKILL_UPLOAD_REQUEST_TOO_LARGE`, or `SKILL_MANIFEST_SIZE_INVALID`. Source diagnostics include a root-relative `path` (`.` for the selected
-root); size diagnostics include `actualBytes` and `maxBytes`. The 10 MiB internal packaging bound is independent of the stricter HTTP limit and applies to the final
+`SKILL_UPLOAD_SIZE_INVALID`, `SKILL_SOURCE_ZIP_INVALID`, `SKILL_SOURCE_PRIMARY_DOCUMENT_INVALID`, or `SKILL_MANIFEST_SIZE_INVALID`. Source diagnostics include a root-relative `path` (`.` for the selected
+root); size diagnostics include `actualBytes` and `maxBytes`. The internal packaging bound is the package ceiling and applies to the final
 upload object, including SkillRoot metadata and encryption overhead. STORE ZIP construction does not
 compress files. A size rejection occurs before that upload and before transaction submission.
 
@@ -103,17 +103,17 @@ and receipt handling. A validated remote error keeps its code, message, trace an
 precedence over a remote service's generic retry flag. Private causes, RPC URLs, credentials and
 journal contents are never printed.
 
-Publication failures set `retryable: false`: this is not permission to replay a paid operation.
+Publication failures report `retryable` and `nextAction` according to the failure. A projection failure after confirmed transactions can be retryable; inspect `unconfirmedActions` before claiming the complete publication succeeded. This is not permission to replay a paid operation.
 `not_attempted` means no send was attempted in this invocation and no hashes were found in the
 validated journal; it is not proof about other invocations. `hash_known` includes known transaction
-hashes. `uncertain` means sending or durable checkpointing failed; contact support before retrying or
+hashes. `uncertain` means sending or durable checkpointing failed. For creation/version/key stages, contact support before retrying or
 recovering, even when a hash is shown. A non-null `recoveryCommand` is provided only after a journal
 is validated or saved and no submission/checkpoint uncertainty was observed. Recheck CLI/MCP identity
 and use that command rather than repeating publish-submit. Cleanup failures do not claim a journal
 still exists. If source is unavailable or its excluded-path inventory changed across CLI versions,
 the fingerprint-only recovery command can use the already stored publication bytes.
 
-These fixes require CLI 0.3.3 or newer; npm 0.3.2 does not include them. Updating a Skill does not upgrade the installed CLI. Journal v6 saves a pending stage before signing/submitting. Missing hashes in a pending stage or a legacy v4/v5 journal block automatic resubmission; contact support. Known hashes are verified without rebroadcast. The pending marker also blocks destructive local authorization/wallet cleanup through the recovery inventory.
+These fixes require CLI 0.3.3 or newer; npm 0.3.2 does not include them. Updating a Skill does not upgrade the installed CLI. Journal v6 saves a pending stage before signing/submitting. Missing hashes in creating stages of a pending or legacy v4/v5 journal block automatic resubmission; follow the reported chain-state checks and contact support. CLI 0.3.7 permits the URI assignment stage to converge through its typed recovery path. Known hashes are verified without rebroadcast. The pending marker also blocks destructive local authorization/wallet cleanup through the recovery inventory.
 
 ## Bootstrap and health reports (CLI 0.3.4+)
 
@@ -126,3 +126,7 @@ CLI 0.3.5 fixes valid WebP covers and packaged detail images being rejected when
 ## Market category compatibility (CLI 0.3.6+)
 
 Use CLI 0.3.6 or newer for the expanded market categories. Skill response display categories now accept bounded text, so future taxonomy additions do not require another CLI upgrade. Updating the website or this Skill does not upgrade an installed CLI.
+
+## Staged uploads and external media (CLI 0.3.7+)
+
+CLI 0.3.7 supports authorized external-media manifests and 30 MiB final packages on both upload and download. Browser publishing still uses multipart and refuses external media. Failed staged uploads attempt ticket release and report its result in the sanitized diagnostic. Presentation submission reports progress and whether setting the same URI can safely converge; a stale plan, authorization failure or invalid input still requires correction before retrying. Read the maintained Finch Market Skill for the complete external-host and recovery boundaries.