Improve README.md for clearer installation and usage instructions

[dolmen]

📝 Recommendation for Improving the goeval README

This document outlines suggested improvements for the github.com/dolmen-go/goeval README.md file, focusing on enhanced clarity, usability, and visibility for potential users and contributors. The key goal is to clearly articulate the tool's dual nature: local execution (default) versus online Playground interaction (flag-based).

1. 🚀 Clarity and Positioning

The introduction should immediately define the tool's dual-mode functionality and value.

Current State	Suggested Improvement	Rationale
Single description.	Elevator Pitch: Clearly state the dual functionality.	Addresses the critical distinction between local and online modes.
No dedicated feature list.	Feature List (Highlights): Separate benefits for each mode.	Makes capabilities scannable at a glance and highlights the key Playground features.
No visual demo.	Visual Demonstration: Add an animated GIF or screenshot.	Crucial for command-line tools; quickly shows value and usage.

Recommended Pitch:

goeval is a command-line tool for running Go snippets. By default, it uses the local Go toolchain for instant execution. When combined with the -play or -share flags, it becomes a terminal interface for running and sharing code using the official Go Playground service online.

2. 🛠️ Installation and Setup

Ensure instructions are modern and robust.

Suggested Improvement	Rationale
Prioritize Standard Go Install: Use the modern, reliable syntax.	Aligns with modern Go tooling practices and user preference (using `@latest`).
Prerequisites: Briefly state the required Go version (e.g., Go 1.18+).	Ensures compatibility and sets user expectation.
System Path Note: Add a note about the binary location ($GOPATH/bin or $HOME/go/bin).	Helps newcomers ensure the executable is in their system's $PATH.

Recommended Installation Block:

### Installation

To install \`goeval\`, ensure you have a working Go environment (Go 1.18+ recommended) and run:

\`\`\`bash
go install github.com/dolmen-go/goeval@latest
\`\`\`

*(Note: This command installs the binary to your \`$GOPATH/bin\` or \`$HOME/go/bin\` directory. Ensure this directory is included in your system's \`$PATH\`.)*

3. 📖 Usage and Examples

The usage section must clearly delineate the two modes of operation with simple, valid snippets.

Suggested Improvement	Rationale
Split Usage Section: Separate instructions for "Local Execution" and "Playground Interaction."	Improves clarity and prevents user confusion over the default behavior.
Simplify Code Snippets: Use simplified `goeval` syntax (omitting boilerplate) for the examples.	Provides examples that are practical and easy to use on the command line.
Flag Clarity: Explicitly mention which flags trigger the online Playground interaction.	Guides users to the correct command for their desired task (local vs. online).

Recommended Usage Block:

### Usage and Examples

\`goeval\` supports two distinct modes of operation. By default, it uses your local Go toolchain.

#### Mode 1: Local Execution (Default)

For quick, everyday evaluations using your local Go toolchain. The boilerplate (package, imports, function definition) is generally \*\*omitted\*\*.

| Task | Command |
| :--- | :--- |
| **Basic Expression:** Evaluate an expression. | \`goeval 'fmt.Println("Local Result:", 1+2)'\` |
| **Piping from File:** Run a snippet piped from a file. | \`cat my-snippet.go \| goeval\` |

#### Mode 2: Playground Interaction (\`-play\` and \`-share\`)

Use these flags to interact with the \*\*official Go Playground API\*\* for environment verification or sharing.

| Task | Command |
| :--- | :--- |
| **Online Execution:** Run code on the Playground server. | \`goeval -play 'println("Online test via Playground API")'\` |
| **Sharing Code:** Generate a shareable Playground URL. | \`goeval -share 'println("Share this code")'\` |

4. 🤝 Community and Maintenance

These elements build trust and encourage participation.

Suggested Improvement	Rationale
Status Badges: Add badges for Go Reference, License, and CI Status.	Standard practice for open-source projects; shows project health quickly.
Contributing Guide: Include a link or brief section on contributions.	Encourages community involvement (bug reports, feature suggestions, PRs).
License: Clearly state the license.	Legal clarity.

---

🤖 AI Usage Disclosure

As a commitment to transparency, the content of this issue was generated and iteratively refined using an Artificial Intelligence assistant (Gemini 2.5 Flash).

List of Prompts Used

• Check the README of github.com/dolmen-go/goeval and suggest some axes of improvement.

• goeval doesn't "simulates the Go Playground environment". Instead it use the global online instance as a backend for the -play and -share commands. Update your review using that information.

• The official Go Playground service is a backend for running code, but when -play or -share are given. So that isn't the default behaviour. Update your review using that information.

• Fix code given to goeval in the examples : they aren't valid goeval syntax.

• Rewrite the full recommandation for posting as a GitHub issue on the project. Add an IA usage disclosure block following the standard for AI disclosure defined by the Ghostty project in its CONTRIBUTING.md file. A of list the prompts used must be included in a details/summary block (ignoring the prompts and the answer that I told you). Your answer must be show me the Markdown source that I can copy and paste.

• The final Markdown had to be man-ually edited because of escaping issues: Gemini is not yet good at producing Markdown source to the end user. :(