fix(#286): correct eternal storage CLI examples and catch unknown-tie…

[sshekhar563]

Resolves #286

Description

The eternal storage CLI examples in README.md and RFC-005 contained three bugs that caused errors when copy-pasted by new users.

Bugs Fixed

1. --source → --tier: soul recover uses --tier, not --source. It also takes a positional reference hash (not a .soul path) and requires --output.
2. --tiers local,ipfs → -t ipfs -t arweave: Click's multiple=True requires repeated flags, not comma-separated values. Additionally, no local provider is registered — only ipfs, arweave, and blockchain exist.
3. Unhandled ValueError traceback: When archive is called with an unknown tier, EternalStorageManager.archive() raises ValueError. The CLI now catches this and prints a clean error message instead of a raw traceback.

Changes

File	Change
README.md	Fixed eternal storage CLI examples
rfc/RFC-005-ETERNAL-STORAGE-PROVIDER.md	Same fix
src/soul_protocol/cli/main.py	Added try/except ValueError in archive command
tests/test_eternal/test_cli_eternal.py	Added test_archive_unknown_tier (clean error, no traceback)

Verification

• All 5 eternal storage CLI tests pass (test_cli_eternal.py)
• Ruff format and lint clean on all changed files

[prakashUXtech]

Good, focused fix. The README and RFC-005 examples now match the real flags (archive -t ipfs -t arweave, recover <ref> --tier --output), and the unknown-tier case is caught with a clean message that lists the available tiers instead of a traceback. Removing local from the docs rather than half-wiring it was the right minimal call, and it is consistent everywhere.

One thing to finish it: the same broken example still lives in docs/cli-reference.md:1304:

soul archive .soul/ --tiers ipfs arweave

That is the exact bug from the issue (with multiple=True, Click takes only ipfs and errors on arweave), and cli-reference is the doc people copy from most. One line: soul archive .soul/ -t ipfs -t arweave.

Optional, non-blocking: the archive-failed path prints the error but returns exit 0, so a script would not detect the failure. It matches the existing recover behavior, so it is not a regression, but a raise SystemExit(1) on both would make failures scriptable. And an (#286) Updated header line on main.py and the new test file, per convention.

Tight PR otherwise.

[prakashUXtech]

The blocker is fixed: the broken soul archive .soul/ --tiers ipfs arweave example in cli-reference is corrected to the repeated-flag form, and I swept the whole tree (docs, README, rfc, scripts) to confirm no broken --tiers a b or --source example survives anywhere. The optional asks are done too: the archive-failed path now does raise SystemExit(1) so failures are scriptable, and the (#286) header lines are on both files.

One thing to fix before merge, introduced by this push rather than the original work: adding the (#286) header line to cli/main.py also deleted eight earlier # Updated: entries (#231, #192, #142, #191, #203, #201, #189, #160), about 50 lines of changelog history. I diffed against dev to be sure. It's non-functional and CI can't see it, but it erases other people's entries, so please restore those eight and just prepend your #286 line above them. Everything from #42 down is still intact.

Non-blocking: a one-line test asserting the documented -t ipfs -t arweave two-flag form works would round it out, since the new test only covers the single-flag and failure cases. Otherwise this is clean.

[prakashUXtech]

Verified all three, and first: your count was right and mine was wrong. I said 8 deleted entries; you restored 10. The two I missed (#284 and #247) had landed on dev from the #299/#249 merges shortly before your push, so your merge resolution dropped those as well. You did the more careful accounting.

The restore checks out exactly: main.py at your head, minus your two new lines, diffs byte-identical against dev. Nothing lost, nothing reworded, nothing duplicated, and the commit is 62 additions with zero deletions. 27 entries where dev has 26, so the #286 line is genuinely prepended rather than replacing anything.

test_archive_two_tier_flags is a real test, not a shape check. The two mock providers return distinct tier names and distinct reference formats with no overlap, so a last-flag-wins regression would fail your assertion. And the original fix survives intact: I swept docs, README, rfc and scripts for any remaining --tiers <a> <b> or soul recover --source form and there are none.

Approving. Three small things you can fold in whenever, none worth holding this for:

1. README.md:390 still lists local as an archive destination ("local, IPFS, Arweave, blockchain"), two lines below the block you just fixed. local is never registered as a provider, and your own test uses -t local as the unknown tier. So someone reading the corrected example and then trying local hits the exact copy-paste failure #286 exists to eliminate. One word.
2. The test file header still says only "Added test_archive_unknown_tier" but the push added a second test.
3. To fully harden both tier tests, add assert "blockchain" not in result.output.lower(). Without it, a regression that ignored the flags entirely would fall through to "archive to all providers" and still pass. Applies to test_archive_specific_tier too, which had the same pre-existing gap.

One for a separate issue, not this PR: manager.py validates tiers inside the archive loop, so -t ipfs -t local archives to IPFS first and then raises, leaving the manifest unwritten and the archive orphaned. Harmless with in-memory mocks, but a real paid Arweave provider makes that a cost leak. Worth validating all tiers up front.

Nice, careful work on the restore.