feat: declare API errors and authentication with developer tooling

cmd/go-omni/apigen/templates.go

@@ -71,12 +71,17 @@ their business logic is implemented. Authentication hooks also fail closed with
 2. Run the same go-omni CLI version as the framework dependency:
 
 `+"```sh"+`
-go-omni api validate --api %s
-go-omni api generate --api %s --dir .
-go-omni api generate --api %s --dir . --check
+go-omni api validate
+go-omni api inspect
+go-omni api generate --dry-run
+go-omni api generate
+go-omni api generate --check
+go-omni api export > openapi.json
 go test ./...
 `+"```"+`
 
+Commands inside a generated project discover the recorded API entry automatically.
+--dry-run previews create/update/remove actions without writing files.
 The --check command is read-only and suitable for CI. It fails on stale or missing
 generated files and missing business scaffolds. go.mod, configuration, main,
 Service, Repository, servicecontext, middleware hook bodies and API files are
@@ -99,6 +104,7 @@ etc/config.yaml              # lowerCamelCase configuration
 internal/settings/           # defaults -> file -> environment
 internal/servicecontext/     # dependency initialization and cleanup
 internal/types/typesGen.go    # generated request/response types
+internal/apierrors/errorsGen.go # generated fresh error constructors, when declared
 internal/handler/<group>/     # generated binding and service adapters
 internal/service/<group>/     # developer-owned business operations
 internal/repository/<group>/  # developer-owned persistence contracts
@@ -123,6 +129,13 @@ and binding compiler. Responses are expected to honor their declared constraints
 they are not validated on every response. Do not return nil slices/maps for a
 non-nullable collection (initialize empty collections instead).
 
+Declare public business errors in error (...) and reference them with @errors.
+Use internal/apierrors constructors to share status, code and message with OpenAPI.
+Auth declarations connect a bearer/header/cookie scheme to a real named middleware.
+The selected auth runs first; @auth none removes inherited declarative auth.
+Validation policy remains in the middleware implementation. Public messages must
+not contain secrets; error causes may be included in server logs.
+
 Named middleware is composed in declaration order (first is outermost). Implement
 the generated hooks or replace entries in servicecontext; never bypass an auth
 hook merely to make the server start. Middleware names do not imply a JWT policy.
@@ -131,7 +144,7 @@ This CLI supports a documented go-zero-style subset, not all goctl features.
 Database tables and repositories cannot be inferred from an HTTP contract. Add
 business repositories through servicecontext. Database and storage options are
 composed at creation; the original profile is retained on regeneration.
-`, module, entry, entry, entry, entry)
+`, module, entry)
 }
 
 func infrastructureREADME(o Options) string {