Docs: Improve Onboarding and Quickstart Experience (Comprehensive Update)

[Samir-atra]

Description

This PR comprehensively improves the onboarding experience for new Hive users. It addresses critical friction points identified in recent issues by restructuring the README.md for better mental model flow, adding explicit troubleshooting steps, providing a clear "manual" path for creating agents without AI assistance, and refining contributor guidelines.

Related Issues

• Closes Add Minimal Python-Only Quick Start for New Contributors #2135: Adds a minimal Python-only manual quickstart option.
• Resolves Clarify onboarding and mental model in README for first-time users #2401: Moves "How It Works" before "Quick Start" to clarify the mental model earlier.
• Resolves Docs: Quickstart “first successful run” steps could be clearer (expected output + common failure modes) #3220: Adds a "Troubleshooting" table with common failure modes (uv, PYTHONPATH, keys).
• Resolves Surface DEVELOPER.md onboarding in README and clarify a first “10-minute success” path #3664: Surfaces DEVELOPER.md prominently for advanced setup details.
• Resolves Clarify "Build Your First Agent" with a concrete end-to-end example #3810: Expands "Build Your First Agent" with concrete steps for defining goals and verifying success.
• Resolves [Bug]: Docs: unclear what successful agent execution looks like and how to inspect results #2050: Adds a "Verifying Success" subsection to explain expected output (JSON, status codes).
• Resolves Docs: Confusing project structure and unclear getting-started instructions #4179: Clarifies the tools directory structure and setup.
• Resolves Testing CLI documentation does not match actual arguments #717: Fixes incorrect CLI arguments in core/framework/cli.py docstrings.
• Resolves [Docs] Clarify how to run tests locally (PYTHONPATH=core) #2519: Documents how to run local tests with PYTHONPATH=core.
• Resolves Contributing: Add “Good first contributions” section (docs, triage, examples) for newcomers #3221: Adds a "Where to Start?" section to CONTRIBUTING.md linking to Good First Issues.
• Resolves [Docs] Update README to reflect folder rename (aden_tools -> tools) #2370: Reflects the folder rename from aden_tools to tools in documentation.

Summary of Changes

1. README.md

• Mental Model: Moved the "How It Works" section before "Quick Start" and added an "Agent Execution Flow" subsection to explain the Goal -> Planning -> Execution -> Evaluation loop.
• Manual Onboarding: Added Option B: Standard CLI (Manual Creation) for users who prefer not to use Claude Code immediately.
• Troubleshooting: Added a table with fixes for common setup errors (command not found: uv, ImportError, missing keys).
• Success Verification: Added a "Verifying Success" subsection under "Run Agents" detailing what output and logs to expect.
• Developer Link: Added a prominent callout linking to DEVELOPER.md for deep-dive setup.
• Structure Clarity: Clarified the dual nature of the tools directory (source vs. package).

2. quickstart.sh

• Refined the success message to present both the recommended Claude Code path and the manual CLI alternative clearly.
• Corrected the manual template copy command to use tech_news_reporter (an existing template) instead of the missing basic_agent.

3. CONTRIBUTING.md

• Added a "Where to Start?" section guiding new contributors to "Good First Issues" and documentation improvements.

4. core/framework/cli.py

• Corrected docstring examples for testing commands to match actual CLI arguments.

[Lumi-artLife]

This is an impressive consolidation of onboarding feedback! Addressing 11 related issues in one comprehensive PR shows great prioritization.

The "mental model before quickstart" reordering is particularly smart — I've seen too many projects jump straight to commands without explaining the "why" first. The troubleshooting table for common setup errors will definitely reduce friction for new contributors.

One suggestion: Consider adding a "Common Mistakes" subsection based on actual issues you've seen. Things like forgetting to export env vars, or trying to run agents before credentials are configured. Real error messages from failed runs can be surprisingly helpful.

The manual CLI option (Option B) is a nice touch for users who want to understand the mechanics before automating. Overall, this significantly lowers the barrier to entry. 👍