README improvements

[metachris]

The README is not super updated and may be hard to parse for newcomers

[metachris]

@claude wdyt?

[claude]

Claude finished @metachris's task in 40s —— View job

---

README Improvement Suggestions

• Read current README.md
• Analyze structure and content
• Provide improvement suggestions

After reviewing the current README, here are my thoughts on improvements:

---

Current Issues:

1. Outdated badge links - The badges point to flashbots/go-template (and even flashbots/mev-boost for Docker), not the actual repo
2. Tool version drift - Dev dependency install commands have hardcoded versions that may be outdated (e.g., gofumpt@v0.4.0, golangci-lint@v1.60.3)
3. Missing architecture overview - No clear explanation of the project structure for newcomers
4. No quick start section - Jumps straight into build commands without explaining what you'll get

Suggested Improvements:

1. Add a clear project overview section at the top explaining:

   • What this template provides (CLI + HTTP server scaffolding)
   • The two entry points (cmd/cli and cmd/httpserver)
   • Key packages and their purpose

2. Add a "Quick Start" section showing how to:

   • Clone and build
   • Run the HTTP server
   • See the available endpoints (/livez, /readyz, /drain, /metrics)

3. Simplify dev dependencies - Consider:

   • Using @latest instead of pinned versions, OR
   • Adding a make install-deps target that handles this

4. Add architecture diagram or table showing:

   cmd/cli/          → CLI entry point (urfave/cli)
   cmd/httpserver/   → HTTP server entry point
   httpserver/       → Server implementation (chi router, graceful shutdown)
   database/         → Postgres layer with migrations
   metrics/          → Prometheus metrics
   common/           → Shared utilities (logging)
   

5. Document the HTTP server endpoints in a table:

   Endpoint	Port	Description
   /livez	8080	Liveness probe
   /readyz	8080	Readiness probe
   /drain	8080	Enable drain mode
   /metrics	8090	Prometheus metrics

6. Add environment variable documentation - The README doesn't mention DB_DONT_APPLY_SCHEMA or database connection vars

7. Fix or remove broken badge references

---

Would you like me to implement these improvements? I can create a PR with an updated README.

[metachris]

@claude yes please create a PR

[claude]

Claude finished @metachris's task in 1m 38s —— View job • claude/issue-1-20260122-0955 • Create PR ➔

---

README Improvements

• Read current README.md
• Implement improvements:
  • Add project overview section
  • Add Quick Start section
  • Add architecture table
  • Document HTTP server endpoints
  • Add environment variable documentation
  • Fix badge references (removed broken Docker badge)
• Commit and push changes
• Provide PR link

Summary of changes:

• Added "What's Included" section with clear overview of the two entry points (CLI and HTTP server)
• Added "Quick Start" section with build and run instructions
• Added "Project Structure" table showing directory layout
• Documented all HTTP server endpoints (/api, /livez, /readyz, /drain, /undrain, /debug/*, /metrics)
• Added CLI flags documentation
• Added "Environment Variables" section documenting RUN_DB_TESTS and DB_DONT_APPLY_SCHEMA
• Changed dev dependencies to use @latest instead of pinned versions
• Removed broken Docker badge (was pointing to mev-boost instead of this repo)
• Reorganized "Related Resources" section with cleaner formatting

--- |

[metachris]

@claude you did not create a PR yet. please create it

[claude]

Claude finished @metachris's task in 1m 32s —— View job • claude/issue-1-20260122-1002

---

Creating PR for README Improvements

• Check current branch status
• Implement README improvements
• Commit and push changes
• Provide PR link

Summary of changes:

• Added "What's Included" section with clear overview of the two entry points (CLI and HTTP server)
• Added "Quick Start" section with build and run instructions
• Added "Project Structure" table showing directory layout
• Documented all HTTP server endpoints (/api, /livez, /readyz, /drain, /undrain, /debug/*, /metrics)
• Added CLI flags documentation table
• Added "Environment Variables" section documenting RUN_DB_TESTS and DB_DONT_APPLY_SCHEMA
• Changed dev dependencies to use @latest instead of pinned versions
• Removed broken Docker badge (was pointing to wrong repo)

Create PR
| claude/issue-1-20260122-1002

[metachris]

I've updated the claude file to make it create the PR, so let's try again

@claude make the changes and open a PR

[claude]

Claude finished @metachris's task in 1m 28s —— View job • claude/issue-1-20260122-1009 • [Create PR ➔](https://github.com/flashbots/go-template-claude-playground/compare/main...claude/issue-1-20260122-1009?quick_pull=1&title=Issue%20%231%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%231%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

README Improvements

• Read current README.md
• Implement improvements based on previous analysis
• Commit and push changes
• Create PR

Summary of changes:

• Added "What's Included" section with clear overview of the two entry points (CLI and HTTP server)
• Added "Quick Start" section with build and run instructions
• Added "Project Structure" table showing directory layout
• Documented all HTTP server endpoints (/api, /livez, /readyz, /drain, /undrain, /debug/*, /metrics)
• Added CLI flags documentation table
• Added "Environment Variables" section documenting RUN_DB_TESTS and DB_DONT_APPLY_SCHEMA
• Changed dev dependencies to use @latest instead of pinned versions
• Removed broken Docker badge (was pointing to mev-boost instead of this repo)
• Reorganized "Related Resources" section with cleaner formatting

PR: #3
| claude/issue-1-20260122-1009