[C0ldSmi1e]

Summary

This PR significantly improves the README documentation to make the project more accessible and easier to understand for new users. The changes reorganize content for better flow, add clarifying details about how the tool works, and provide more explicit guidance on setup and safety features.

Key changes

• Reorganized structure: Added a "How it works" section early in the README to explain the core value propositions before diving into installation
• Clearer setup instructions: Separated API key configuration from shell wrapper setup with better explanations of what each step does
• Enhanced safety documentation: Expanded the Safety section with specific details about the blocklist (rm -rf, dd, fork bombs, curl | sh) and clarified that high-danger commands require deliberate action
• Improved usage examples: Added context that "no quotes, no subcommands" applies to the tool, and clarified the -j flag output format
• Better scripts/agents section: Clarified that howto never blocks on input and documented the exit code API more explicitly
• Added building section: Included cargo build and test commands for developers
• Config documentation: Clarified precedence order (flags > env vars > config > defaults) and noted that config is created with commented defaults on first run
• Added website and links: Included links to the website, design spec, and releases in the header
• Minor wording improvements: Various clarifications like "Enter runs it" instead of "Enter to run it", and more explicit explanations of how the tool behaves

Notable details

• The changes are documentation-only (README.md)
• No functional changes to the codebase
• Maintains all existing information while reorganizing for better clarity and discoverability

https://claude.ai/code/session_01Su1NcypUJbJve6J7wANB8Q