docs: restructure README into concise overview with docs/ reference pages

[ryanio]

docs: restructure README into concise overview with docs/ reference pages

Summary

Slims down the README from ~340 lines to ~180 lines by moving detailed content into a new docs/ folder. The README now serves as a quick-start guide with a command summary table, linking out to dedicated reference pages for deeper information.

README changes:

• Replaced the full inline CLI command reference with a compact command summary table
• Replaced the full inline examples section with a Quick Start showing the most common commands
• Trimmed the SDK section to a focused quickstart (was showing all 9 domains inline, now shows the most useful ones)
• Added OpenSeaAPIError error handling example
• Added a Development section with build/test/lint commands
• Added a Docs section linking to all reference pages

New docs/ pages:

• docs/cli-reference.md — full command reference with all options and flags (moved from README)
• docs/examples.md — real-world usage examples for every command (moved from README)
• docs/sdk.md — full SDK API reference with all methods, config options, error handling, and exports
• docs/pagination.md — pagination patterns for CLI and SDK, including a table of all paginated commands and an iteration example
• docs/events.md — event type reference table with CLI and SDK usage

No code changes — docs only.

Updates since last revision

The initial commit added detailed content directly into the README, making it quite long. Per reviewer feedback, a second commit restructured the approach:

• Moved the full CLI reference to docs/cli-reference.md
• Moved all examples to docs/examples.md
• Slimmed the README to a scannable overview with links into docs/

Review & Testing Checklist for Human

• Verify all internal links resolve correctly on GitHub (README links to docs/cli-reference.md, docs/examples.md, docs/sdk.md, docs/pagination.md, docs/events.md; and cross-links within docs/ like docs/cli-reference.md linking to events.md and pagination.md)
• Spot-check that CLI options in docs/cli-reference.md match actual behavior — especially --creator, --include-hidden, --after, --before flags which were sourced from command source files but not previously documented
• Skim docs/sdk.md examples against src/sdk.ts class signatures for accuracy (note: the SDK examples use repeated destructuring like const { nfts, next } in multiple places which is fine as documentation but would need unique names in real code)

Notes

• All documented options were verified against source files in src/commands/*.ts and src/sdk.ts
• docs/pagination.md notes that tokens commands use --cursor while all others use --next — this is an existing inconsistency in the codebase, not introduced by this PR
• Confidence: high — docs-only changes with no functional risk, content sourced directly from source code
• Link to Devin run: https://app.devin.ai/sessions/8bb30b3c11be40f792be6a9f8ac058a8
• Requested by: @ryanio

[devin-ai-integration]

Original prompt from Ryan

how can we improve opensea-cli readme

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 5 additional findings.