docs: rewrite README with "Why spec-forge?" section and fix unclosed code fence

[Copilot]

The README read like an API reference with no explanation of why spec-forge exists — the real pain points (abandoned gRPC tooling, swaggo annotation burden, go-zero bugs) were invisible to new visitors.

Changes

New "Why spec-forge?" section

• gRPC/Protobuf: calls out google/gnostic (abandoned), grpc-gateway (Swagger 2.0 only), and buf (no official OpenAPI docs) — explains why protoc-gen-connect-openapi was chosen
• Gin: shows the swaggo/swag annotation problem (compiler-unvalidated, manual sync) vs. spec-forge's zero-annotation AST approach
• Hertz/Kitex: notes tooling exists but is officially undocumented
• go-zero: clarifies that goctl swagger bugs are patched internally
• vs AI-generated docs: distinguishes code-synchronized enrichment from LLM-written docs that drift
• AI Agent angle: positions accurate OpenAPI specs as machine-readable interface contracts

Updated one-liner

A CLI tool that solves the fragmented, painful world of OpenAPI spec generation — auto-detects your framework, generates accurate specs from source code, and enriches them with AI.

Structural improvements

• Added "Zero annotations for Gin" to the Features list
• Moved Supported Frameworks table before Framework-Specific Usage
• Added inline callout blockquotes to the Gin and gRPC sections reinforcing the key differentiators
• Expanded Quick Start to cover all four supported frameworks

Bug fix

• Closed the missing ``` fence in the ### Publishing to ReadMe.com section that left the code block unclosed before ## License

Original prompt

Background

The current README is functional but too neutral — it reads like an API reference rather than a compelling pitch. Many developers question the value of spec-forge, but the project actually solves very real, concrete pain points that are not communicated anywhere in the current README.

After a deep discussion about the project's positioning, the following key insights emerged that should be reflected in the README:

Core Pain Points spec-forge Solves (that are NOT in the current README)

1. gRPC/Protobuf ecosystem is fragmented and poorly documented:

• google/gnostic's protoc-gen-openapi is abandoned/unmaintained — yet still referenced by most tutorials
• grpc-gateway's protoc-gen-openapiv2 only outputs Swagger 2.0, not OpenAPI 3.x
• buf has no official documentation for OpenAPI generation — developers rely entirely on third-party blogs
• Developers waste hours figuring out which tool to use before writing a single line of code

2. Gin requires verbose godoc annotations (swaggo pain):

• The dominant solution (swaggo/swag) requires writing // @Summary, // @Param, // @Success etc. for every handler
• These annotations are not validated by the Go compiler — errors only surface at generation time
• Renaming a type means manually updating annotations everywhere
• spec-forge's AST-based approach requires zero annotations — this is a key differentiator that is completely missing from the README

3. Hertz and Kitex (CloudWeGo ecosystem) have hidden, undocumented tooling:

• OpenAPI generation tools exist but are buried in GitHub corners with no official documentation
• The official CloudWeGo docs don't mention how to generate OpenAPI specs
• spec-forge is the only tool that wraps this complexity with a single command

4. go-zero's goctl swagger has known bugs:

• spec-forge patches these bugs internally (this is real implementation work that's invisible to users)

5. AI-enriched specs are fundamentally different from "AI-generated" specs:

• A common objection is "just use ChatGPT to write your docs"
• The README must clearly explain: AI generation ≠ code-synchronized spec
• spec-forge reads the actual code structure, then uses AI to fill in human-readable descriptions — the output is both machine-accurate and human-readable

6. The AI Agent era makes high-quality OpenAPI specs increasingly critical:

• OpenAPI specs are becoming the "interface contract" for AI agents to call APIs
• This is a new, compelling reason to maintain accurate specs that the README doesn't mention at all

---

What Needs to Change in README.md

Please rewrite the README.md with the following structure. Preserve all existing technical content (configuration, commands, framework-specific usage, etc.) — only add and reorganize, don't remove working documentation.

New README Structure:

1. Title + Badges (keep as-is)

2. One-liner — upgrade from the current neutral description to something that leads with the problem:

   A CLI tool that solves the fragmented, painful world of OpenAPI spec generation — auto-detects your framework, generates accurate specs from source code, and enriches them with AI.

3. NEW: "Why spec-forge?" section — this is the most important addition. Must include:

   • A clear statement that generating OpenAPI from backend code is harder than it should be, with a concrete breakdown by ecosystem:

     • gRPC/Protobuf: google/gnostic is abandoned, grpc-gateway only outputs Swagger 2.0, buf has no official OpenAPI docs (only community blogs), leaving developers lost
     • Gin: swaggo requires hundreds of verbose // @swagger annotations that the compiler never validates — spec-forge uses AST analysis requiring zero annotations
     • Hertz / Kitex (CloudWeGo): tools exist but are buried with no official documentation
     • go-zero: goctl swagger has known bugs that spec-forge patches internally

   • A "vs AI-generated docs" explanation:

     spec-forge reads your actual code structure to guarantee accuracy, then uses AI to make it human-readable. This is fundamentally different from asking an LLM to write docs from scratch — those drift from reality the moment your code changes.

   • A mention of the AI Agent angle:

     In the AI Agent era, OpenAPI specs are becoming machine-readable interface contracts. spec-forge helps ensure yours are accurate and complete.

4. Features (keep existing 4 bullets, consider adding one about "zero annotation" for Gin)

5. How It Works (keep existing mermaid diagram + step descriptions)

6. Installation (keep as-is)

7. Quick Start (keep as-is, but make the examples span more frameworks — not just Spring Boot)

8. Supported Frameworks (keep existing table)

9. Framework-Specific Usage — keep all existing content, but add a clear callout for Gin explaining the "no annotations needed" benefit at the top of...

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This PR rewrites the README to add a "Why spec-forge?" section that explains the concrete pain points solved by the tool (fragmented gRPC tooling, swaggo annotation burden for Gin, undocumented CloudWeGo tools, go-zero goctl bugs), updates the one-liner, reorganizes existing content for better flow, and fixes an unclosed code fence bug.

Changes:

• Added a new "Why spec-forge?" section with per-framework pain-point explanations, an LLM comparison, and an AI Agent angle
• Reorganized sections (Supported Frameworks table moved before Framework-Specific Usage, Configuration/LLM Providers moved after framework details), expanded Quick Start with examples for all four frameworks, and added callout blockquotes in Gin and gRPC sections
• Fixed a missing closing ``` fence in the "Publishing to ReadMe.com" section

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[qodo-code-review]

Review Summary by Qodo

Rewrite README with framework pain points and extract framework docs

📝 Documentation ✨ Enhancement

Walkthroughs

Description

• Rewrote README with "Why spec-forge?" section explaining pain points in OpenAPI generation across
  frameworks
• Added comprehensive framework-specific documentation files (Gin, gRPC, go-zero, Spring Boot,
  Hertz, Kitex)
• Moved framework details to separate docs to reduce README size and improve maintainability
• Enhanced Quick Start section with examples for all four supported frameworks
• Added "Zero annotations for Gin" feature highlight and improved positioning against competing
  tools
• Fixed unclosed code fence in Publishing to ReadMe.com section

Diagram

flowchart LR
  A["README.md<br/>Original"] -->|"Add Why section<br/>& framework callouts"| B["README.md<br/>Refactored"]
  A -->|"Extract framework<br/>details"| C["docs/gin.md"]
  A -->|"Extract framework<br/>details"| D["docs/grpc-protoc.md"]
  A -->|"Extract framework<br/>details"| E["docs/go-zero.md"]
  A -->|"Extract framework<br/>details"| F["docs/spring-boot.md"]
  A -->|"Extract framework<br/>details"| G["docs/hertz.md"]
  A -->|"Extract framework<br/>details"| H["docs/kitex.md"]
  B -->|"Link to"| C
  B -->|"Link to"| D
  B -->|"Link to"| E
  B -->|"Link to"| F

Loading

File Changes

1. README.md 📝 Documentation +86/-67

Rewrite README with value proposition and framework pain points

• Replaced generic one-liner with compelling value proposition addressing fragmented OpenAPI tooling
• Added "Why spec-forge?" section with detailed pain points for gRPC, Gin, Hertz/Kitex, and go-zero
 ecosystems
• Added comparison section explaining AI-enriched specs vs AI-generated docs and AI Agent angle
• Expanded Quick Start with examples for Gin, gRPC, go-zero, and AI enrichment
• Moved Supported Frameworks table before Framework-Specific Usage section
• Added "Zero annotations for Gin" to Features list
• Removed verbose framework-specific usage sections (moved to separate docs)
• Fixed unclosed code fence in Publishing to ReadMe.com section

README.md

---

2. docs/gin.md 📝 Documentation +55/-0

New Gin framework documentation with zero-annotation approach

• New file explaining Gin framework support with AST-based static analysis
• Detailed comparison with swaggo/swag annotation burden
• Documents supported patterns (route registration, groups, middleware, parameter binding)
• Provides usage examples with and without AI enrichment

docs/gin.md

---

3. docs/go-zero.md 📝 Documentation +32/-0

New go-zero framework documentation and usage guide

• New file documenting go-zero project support
• Explains detection, patching, and generation workflow
• Lists prerequisites (goctl tool installation)
• Provides basic and enriched generation examples

docs/go-zero.md

---

View more (4)

4. docs/grpc-protoc.md 📝 Documentation +51/-0

New gRPC/Protobuf documentation with tooling comparison

• New file explaining gRPC/Protobuf support using native protoc
• Includes comparison table of gRPC tooling landscape (gnostic, grpc-gateway, buf)
• Documents protoc-gen-connect-openapi as the chosen solution
• Lists prerequisites and installation steps
• Provides usage examples with import paths and AI enrichment
• Notes buf-managed projects limitation

docs/grpc-protoc.md

---

5. docs/spring-boot.md 📝 Documentation +34/-0

New Spring Boot framework documentation and setup guide

• New file documenting Spring Boot project support
• Explains springdoc-openapi integration and detection workflow
• Documents supported build tools (Maven and Gradle)
• Covers multi-module Maven project handling
• Provides usage examples with and without AI enrichment

docs/spring-boot.md

---

6. docs/hertz.md 📝 Documentation +22/-0

New Hertz framework documentation with coming soon status

• New file for Hertz (CloudWeGo) framework documentation
• Marks feature as coming soon with 🚧 status
• References hertz-contrib/swagger-generate and protoc-gen-http-swagger as recommended tools
• Provides links to official repositories

docs/hertz.md

---

7. docs/kitex.md 📝 Documentation +22/-0

New Kitex framework documentation with coming soon status

• New file for Kitex (CloudWeGo) framework documentation
• Marks feature as coming soon with 🚧 status
• References hertz-contrib/swagger-generate and protoc-gen-rpc-swagger as recommended tools
• Provides links to official repositories

docs/kitex.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (1) 📎 Requirement gaps (0)

1. Wrong OpenAI env var ☑ 🐞 Bug ✓ Correctness

Description

README examples use LLM_API_KEY with --provider openai, but the CLI requires OPENAI_API_KEY;
users following Quick Start will hit immediate auth failures.

Code

README.md[R109-115]

+# Generate with AI enrichment (any framework)
+LLM_API_KEY="your-api-key" spec-forge generate ./path/to/project \
  --enrich --provider openai --model gpt-4o --language en
# Enrich an existing OpenAPI spec
LLM_API_KEY="your-api-key" spec-forge enrich ./openapi.json \
  --provider openai --model gpt-4o --language zh

Evidence

README’s Quick Start shows LLM_API_KEY while selecting the OpenAI provider, but the implementation
explicitly reads OPENAI_API_KEY for provider=openai and errors if it is not set; README’s own
provider table also states OpenAI uses OPENAI_API_KEY.

README.md[109-116]
README.md[161-168]
cmd/enrich.go[188-205]
cmd/generate.go[357-371]
internal/enricher/config.go[80-96]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
README shows `LLM_API_KEY` while explicitly selecting `--provider openai`, but the CLI requires `OPENAI_API_KEY` for OpenAI. This will cause immediate authentication failures for users following Quick Start.
### Issue Context
The CLI hard-codes provider-specific env vars for OpenAI/Anthropic in both `generate` enrichment and `enrich` command paths.
### Fix Focus Areas
- README.md[109-116]
- README.md[161-168]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Spring docs omit wrappers 📘 Rule violation ⛯ Reliability

Description

The new Spring Boot documentation states the tool runs mvn verify / gradle generateOpenApiDocs
without mentioning wrapper-first execution (./mvnw / ./gradlew). This conflicts with the
required wrapper-preference behavior and may encourage less reproducible builds.

Code

docs/spring-boot.md[R13-16]

+| Build Tool | Command Used |
+|------------|--------------|
+| Maven | `mvn verify` |
+| Gradle | `gradle generateOpenApiDocs` |

Evidence

Compliance requires Maven/Gradle execution to prefer project wrappers before falling back to system
binaries. The added Spring Boot docs explicitly list system mvn/gradle commands as the commands
used, with no wrapper-first guidance.

CLAUDE.md
docs/spring-boot.md[13-16]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Spring Boot documentation lists `mvn verify` and `gradle generateOpenApiDocs` as the commands used, without indicating wrapper-first execution. This conflicts with the compliance requirement to prefer `./mvnw` / `./gradlew` before system binaries.
## Issue Context
Compliance requires Maven/Gradle execution to prefer project wrappers (including multi-module parent wrappers) before falling back to system `mvn`/`gradle`. The new docs should reflect this behavior (or at least not contradict it).
## Fix Focus Areas
- docs/spring-boot.md[13-16]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. go-zero command mismatch ☑ 🐞 Bug ✓ Correctness

Description

New go-zero docs (and README narrative) describe the wrong goctl prerequisite/command
(goctl-swagger / goctl swagger), but the implementation checks for goctl and runs `goctl api
swagger`; docs will mislead users during setup/troubleshooting.

Code

docs/go-zero.md[R7-9]

+1. **Detection**: Parses `go.mod` to detect go-zero dependency and locate API definition files (`.api` files)
+2. **Patching**: Checks for `goctl-swagger` installation
+3. **Generation**: Uses `goctl swagger` command to generate the OpenAPI spec

Evidence

The newly added go-zero docs instruct users about goctl-swagger and goctl swagger, but the
go-zero extractor code verifies goctl --version and executes goctl with args api swagger.
README’s new 'Why spec-forge?' section repeats the incorrect goctl swagger phrasing.

docs/go-zero.md[7-10]
README.md[45-47]
internal/extractor/gozero/patcher.go[40-62]
internal/extractor/gozero/generator.go[189-218]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Documentation for go-zero currently describes incorrect tooling/command names (`goctl-swagger` and `goctl swagger`). The implementation uses `goctl` and runs `goctl api swagger`.
### Issue Context
Users relying on docs may install the wrong tool or run the wrong command while debugging failures.
### Fix Focus Areas
- docs/go-zero.md[7-9]
- README.md[45-47]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[spencercjh]

LGTM