feat: Update documentation and improve content clarity across multiple files

Author: TBXark

content/_index.md

@@ -11,13 +11,13 @@ layout: hextra-home
 
 <div class="hx:mt-6 hx:mb-6">
 {{< hextra/hero-headline >}}
-  Build pragmatic Go backends&nbsp;<br class="hx:sm:block hx:hidden" />with Sphere
+  A pragmatic Go toolkit that starts&nbsp;<br class="hx:sm:block hx:hidden" />monolithic and scales to microservices
 {{< /hextra/hero-headline >}}
 </div>
 
 <div class="hx:mb-12">
 {{< hextra/hero-subtitle >}}
-  Monolithic-first toolkit with codegen for contracts, errors, stubs, and clients
+  Define once in Protobuf, generate everything: handlers, routes, errors, and clients
 {{< /hextra/hero-subtitle >}}
 </div>
 
@@ -27,27 +27,27 @@ layout: hextra-home
 
 {{< hextra/feature-grid >}}
   {{< hextra/feature-card
-    title="Contracts First"
-    subtitle="Define APIs in Protobuf and entities in Ent; generate Go handlers, routers, bindings, and clients."
+    title="Protocol-First Design"
+    subtitle="Define once in Protobuf, generate everywhere. Get Go handlers, HTTP routing, client SDKs, and OpenAPI docs from a single source of truth."
   >}}
   {{< hextra/feature-card
-    title="Monolith-First Template"
-    subtitle="Start with a single binary using Gin + Wire; evolve to multi-service when needed."
+    title="Pragmatic Monolith Template"
+    subtitle="Start simple with Gin + Wire + Ent in a single binary. Clean architecture that scales from MVP to microservices when needed."
   >}}
   {{< hextra/feature-card
-    title="Code Generation"
-    subtitle="protoc-gen-sphere, protoc-gen-route, protoc-gen-sphere-binding, and protoc-gen-sphere-errors automate server, routing, tags, and typed errors."
+    title="Complete Code Generation"
+    subtitle="Automated toolchain with protoc-gen-sphere ecosystem: server stubs, HTTP routing, field binding, typed errors, and validation."
   >}}
   {{< hextra/feature-card
-    title="Typed Errors"
-    subtitle="Define error enums in .proto; get consistent HTTP JSON with status, code, reason, and message."
+    title="Structured Error Handling"
+    subtitle="Define error enums in protobuf with automatic HTTP status mapping. Get consistent JSON responses with code, reason, and message."
   >}}
   {{< hextra/feature-card
-    title="Swagger & Clients"
-    subtitle="Generate OpenAPI from contracts and optional TypeScript SDKs for frontends."
+    title="Full-Stack Development"
+    subtitle="Generate Swagger documentation, TypeScript SDKs, and validation schemas. Bridge backend and frontend with type safety."
   >}}
   {{< hextra/feature-card
-    title="CLI & Layout"
-    subtitle="sphere-cli and sphere-layout bootstrap projects with Makefile workflows and a sane project structure."
+    title="Developer Experience"
+    subtitle="sphere-cli for project scaffolding, Makefile workflows, and clean project structure. Focus on business logic, not boilerplate."
   >}}
 {{< /hextra/feature-grid >}}

content/docs/components/protoc-gen-route.md

@@ -1,6 +1,6 @@
 ---
 title: protoc-gen-route
-weight: 35
+weight: 33
 ---
 
 `protoc-gen-route` is a protoc plugin that generates routing code from `.proto` files. It is designed to inspect service definitions within your protobuf files and automatically generate corresponding route handlers based on a specified template. This plugin creates Go code that provides structured routing with operation constants, extra data handling, server interfaces, and codec interfaces for seamless integration with various transport protocols.
@@ -395,3 +395,7 @@ service UserService {
 - Combine with `protoc-gen-sphere-errors` for consistent error handling
 - Works with any transport layer that can use the generated interfaces
 
+## See Also
+
+- Concepts: ../../concepts/protocol-and-codegen
+- Component: ./protoc-gen-sphere

content/docs/components/protoc-gen-sphere-binding.md

@@ -1,6 +1,6 @@
 ---
 title: protoc-gen-sphere-binding
-weight: 36
+weight: 34
 ---
 
 `protoc-gen-sphere-binding` is a protoc plugin that generates Go struct tags for Sphere binding from `.proto` files. It is designed to inspect service definitions within your protobuf files and automatically generate corresponding Go struct tags based on sphere binding annotations.
@@ -278,3 +278,8 @@ func inspectTags() {
 }
 ```
 
+## See Also
+
+- Guides: ../../guides/api-definitions
+- Component: ./protoc-gen-sphere
+- Concepts: ../../concepts/protocol-and-codegen

content/docs/components/protoc-gen-sphere-errors.md

@@ -1,6 +1,6 @@
 ---
 title: protoc-gen-sphere-errors
-weight: 37
+weight: 35
 ---
 
 `protoc-gen-sphere-errors` is a protoc plugin that generates error handling code from `.proto` files. It is designed to inspect enum definitions within your protobuf files and automatically generate corresponding error handling code based on the sphere errors framework. This plugin creates Go code that provides structured error handling with HTTP status codes, error codes, and customizable messages.
@@ -199,3 +199,8 @@ When used with Sphere's HTTP server utilities, these errors are automatically co
 - Sphere's Gin layer maps these to structured JSON with correct HTTP status
 - Pair with a global error parser if you need to merge validation/notfound/custom errors
 - The generated errors integrate seamlessly with Sphere's server utilities for consistent API responses
+
+## See Also
+
+- Guides: ../../guides/error-handling
+- Concepts: ../../concepts/protocol-and-codegen

content/docs/components/protoc-gen-sphere.md

@@ -1,6 +1,6 @@
 ---
 title: protoc-gen-sphere
-weight: 38
+weight: 32
 ---
 
 Generates HTTP server code from `.proto` service definitions, using `google.api.http` annotations and Sphere server utilities (Gin-based).
@@ -46,3 +46,9 @@ Notes
 - Works hand-in-hand with Sphere’s Gin helpers: `WithJson`, `ShouldBindJSON`, `ShouldBindUri`, `ShouldBindQuery`
 - Pair with `protoc-gen-sphere-binding` to inject binding tags into generated structs
 
+## See Also
+
+- Guides: ../../guides/api-definitions
+- Component: ./protoc-gen-sphere-binding
+- Component: ./protoc-gen-sphere-errors
+- Concepts: ../../concepts/protocol-and-codegen

content/docs/components/sphere-cli.md

@@ -1,6 +1,6 @@
 ---
 title: sphere-cli
-weight: 32
+weight: 31
 ---
 
 Sphere CLI (`sphere-cli`) is a command-line tool designed to streamline the development of [Sphere](https://github.com/go-sphere/sphere) projects. It helps you create new projects, generate service code, manage Protobuf definitions, and perform other common development tasks.
@@ -139,70 +139,10 @@ Renames the Go module path across the entire repository. This is useful when you
 sphere-cli rename --old <old-module-path> --new <new-module-path>
 ```
 
-## Workflow Examples
+## Common Workflows
 
-### Creating a New Project
-
-```shell
-# 1. Create the project
-sphere-cli create --name myapp --module github.com/myorg/myapp
-
-# 2. Navigate to the project
-cd myapp
-
-# 3. Initialize dependencies
-make init
-
-# 4. Generate initial code
-make gen/all
-```
-
-### Adding a New Service
-
-```shell
-# 1. Generate the proto file
-sphere-cli service proto --name UserService --package api.v1
-
-# 2. Edit the generated proto file to add methods
-# vim proto/api/v1/user_service.proto
-
-# 3. Generate the Go implementation
-sphere-cli service golang --name UserService --package api.v1 --mod github.com/myorg/myapp
-
-# 4. Generate all code
-make gen/all
-```
-
-### Working with Ent Schemas
-
-```shell
-# 1. Define your Ent schemas in internal/pkg/database/ent/schema/
-
-# 2. Convert Ent schemas to proto
-sphere-cli entproto --path ./internal/pkg/database/ent/schema --proto ./proto/entpb
-
-# 3. Generate database code
-make gen/db
-
-# 4. Generate API code
-make gen/proto
-```
-
-## Integration with Make
-
-Sphere projects use Makefiles to orchestrate common tasks. The CLI integrates well with these targets:
-
-```makefile
-# Generate database code from Ent schemas
-gen/db:
-	sphere-cli entproto
-	go generate ./internal/pkg/database/ent
-
-# Create a new service
-service/%:
-	sphere-cli service proto --name $* --package api.v1
-	sphere-cli service golang --name $* --package api.v1
-```
+- Quick project setup and generation: ../../getting-started/quickstart
+- Day-to-day development loop: ../../getting-started/workflow
 
 ## Best Practices
 
@@ -245,4 +185,3 @@ make gen/all  # Regenerate everything
 - [Quick Start](../../getting-started/quickstart) - Complete project setup guide
 - [Project Structure](../../concepts/project-structure) - Understanding the generated project layout
 - [Components Overview](../) - Details about protoc plugins used by sphere-cli
-