@hugomrdias/fil 0.0.0 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hugomrdias/fil",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Command-line interface for Filecoin storage",
   "license": "MIT",
   "author": "Hugo Dias <hugomrdias@gmail.com>",
@@ -27,7 +27,7 @@
     "@filoz/synapse-core": "^0.10.0",
     "@ipld/car": "^5.4.7",
     "@types/node": "26.5.1",
-    "clipact": "0.0.0",
+    "clipact": "0.1.0",
     "env-paths": "^4.0.0",
     "esbuild": "0.28.2",
     "ipfs-unixfs-exporter": "^16.2.3",

package/skills/fil/SKILL.md

@@ -1,28 +1,41 @@
 ---
 name: fil
-description: Store files and folders on Filecoin with the fil CLI and return retrieval links; download, list, delete, and resume interrupted uploads. Use when the user asks to publish, store, share, or retrieve content on Filecoin or FOC.
+description: Store files and folders on Filecoin with the fil CLI, return links to share them, and retrieve and verify them later. Use when the user asks to publish, store, share, back up, retrieve, or verify content on Filecoin.
 ---
 
 # fil
 
-`fil` stores a file (exact bytes) or a folder (a UnixFS CAR served over IPFS) on Filecoin and returns a link. Every command writes one JSON object to stdout when run by an agent; it has `data` on success or `error` on failure. Branch on `error.code`, never on stderr text.
+`fil` stores a file (its exact bytes) or a folder (a UnixFS CAR served over IPFS) on Filecoin and returns links to share it. A person owns the wallet and approves what you may do. You never hold the wallet key.
 
-## Discover before you call
+## Run it
 
-- `fil schema --list` lists every command with its side effects.
-- `fil schema <command>` gives the input JSON Schema, the JSON Schema of `data`, and what each error code means, for the installed version. Prefer it over guessing flags.
+Run `fil` when it is on the PATH. Otherwise run `npx -y @hugomrdias/fil` in its place, which needs Node.js 24 or newer.
+
+Every command writes one JSON object to stdout: `data` on success or `error` on failure, then optional `next` steps. Branch on `error.code`, never on stderr text.
+
+Don't guess flags or fields. The installed CLI describes itself:
+
+- `fil --help` lists the commands, and `fil <command> --help` shows examples and flags.
+- `fil schema <command>` gives the input and output JSON Schemas, and what each error code means.
 
 ## Workflow
 
-1. `fil status` shows whether a session key is active and the account is funded.
-2. `fil put <path> --dry-run` shows the size, provider, cost, and any missing authorization without storing anything.
-3. `fil put <path>` (or `fil publish <path>`) stores it. Return `data.urls.browser` to the user exactly as given, with `data.resource.ref`. `data.urls.piece` serves the exact stored bytes. A new link can return 404 until the indexer behind it has the piece; `fil inspect <ref> --check` reports when it answers.
-4. `fil get <ref>` downloads and verifies content; `fil ls` and `fil inspect <ref>` find what was stored.
+1. `fil status` shows whether a session key is approved and the account is funded.
+2. `fil put <path> --dry-run` reports the size, provider, cost, and missing authorization without storing anything.
+3. `fil put <path>` stores it. Give the user `data.urls.browser` exactly as returned, with `data.resource.ref`.
+4. `fil get <ref>` downloads the content and verifies it. `fil ls` and `fil inspect <ref>` find what was stored.
 
 ## Rules
 
 - Never ask for or pass a private key. Logging in needs the user: `auth_required` or `login_pending` means relay the `by: "user"` step (the fil-app approval link) and stop. After the user approves, run `fil login` once to confirm.
-- `insufficient_funds` and `session_expired` also need the user; relay their `next` steps.
+- `insufficient_funds` and `session_expired` also need the user. Relay their `next` steps.
 - `fil delete <ref>` needs `--yes`. On `confirmation_required`, relay the reason and rerun with `--yes` only after the user agrees.
-- Never repeat a failed or interrupted `put` or `delete`: that starts a new paid operation. Run the `fil operations resume <id>` command from `next` instead; errors with a fil code also carry the ID in `error.details.operationId`. Find lost operation IDs with `fil operations ls --incomplete`.
+- Never repeat a failed or interrupted `put` or `delete`: that starts a new paid operation. Run the `fil operations resume <id>` command from `next` instead. Errors with a fil code also carry the ID in `error.details.operationId`. Find lost operation IDs with `fil operations ls --incomplete`.
 - Retry only when `error.retryable` is `true`, after `retryAfterSeconds` when present.
+
+## Read more only when you need it
+
+Fetch these pages; each is Markdown:
+
+- No browser to open, or a disk that is gone when the session ends, such as a cloud sandbox: read [Cloud agents](https://fil-app.hugomrdias.dev/agents.md#cloud-agents) before `fil login`.
+- A link returns 404, the user wants proof the content is intact, or `fil ls` is missing content stored elsewhere: read [Retrieve and verify](https://fil-app.hugomrdias.dev/docs/retrieve.md).