Improve root page, examples, and config docs

- Rework homepage hero with install command and CTAs
- Expand feature grid to 6 cards matching ogen capabilities
- Add spec-to-Go showcase section
- Add Examples page (real-world specs, optional/nullable, oneOf, SSE, security)
- Expand config docs with feature/parser/filter recipes

Author: ernado

docs/06-examples.mdx

@@ -0,0 +1,213 @@
+---
+id: examples
+title: Examples
+sidebar_label: Examples
+sidebar_position: 6
+---
+
+# Examples
+
+This page collects small, focused examples. For a complete runnable project,
+see the [Getting started](intro) guide and the
+[ogen-go/example](https://github.com/ogen-go/example) repository.
+
+## Real-world specifications
+
+ogen is tested against a large set of real-world OpenAPI documents. Each of
+these is generated in CI from the
+[`examples`](https://github.com/ogen-go/ogen/tree/main/examples) directory:
+
+| API | Spec |
+| --- | --- |
+| GitHub | `api.github.com.json` |
+| Kubernetes | `k8s.json` |
+| OpenAI | `openai.openapi.yaml` |
+| Telegram Bot API | `telegram_bot_api.json` |
+| Firecracker | `firecracker.json` |
+| Petstore (expanded) | `petstore-expanded.yml` |
+
+Generation is driven by `go:generate` directives. A typical one looks like:
+
+```go title="generate.go"
+package api
+
+//go:generate go tool ogen --clean --config .ogen.yml --target api github.json
+```
+
+Larger specs like GitHub and Kubernetes rely on type inference and skipping
+not-yet-supported operations:
+
+```yaml title=".ogen.yml"
+parser:
+  infer_types: true
+generator:
+  ignore_not_implemented: ["all"]
+```
+
+See [Config](config) for the full list of options.
+
+## Optional and nullable fields
+
+ogen avoids pointers for optional and nullable values. Given this schema:
+
+```yaml
+components:
+  schemas:
+    Pet:
+      type: object
+      required: [id, name]
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        nickname:
+          type: string
+          nullable: true
+        tag:
+          type: string
+          format: uuid
+```
+
+ogen generates wrappers instead of pointers:
+
+```go
+type Pet struct {
+    ID       int64        `json:"id"`
+    Name     string       `json:"name"`
+    Nickname OptNilString `json:"nickname"` // optional + nullable
+    Tag      OptUUID      `json:"tag"`      // optional uuid.UUID
+}
+```
+
+Each wrapper comes with helpers:
+
+```go
+pet := Pet{ID: 1, Name: "Cat"}
+pet.Tag = NewOptUUID(uuid.New())
+
+if v, ok := pet.Tag.Get(); ok {
+    fmt.Println("tag:", v)
+}
+
+pet.Nickname = NewOptNilString("Kitty")
+pet.Nickname.SetToNull() // encodes as JSON null
+```
+
+## Sum types from `oneOf`
+
+A `oneOf` with a discriminator becomes a Go sum type:
+
+```yaml
+components:
+  schemas:
+    Animal:
+      oneOf:
+        - $ref: "#/components/schemas/Cat"
+        - $ref: "#/components/schemas/Dog"
+      discriminator:
+        propertyName: kind
+        mapping:
+          cat: "#/components/schemas/Cat"
+          dog: "#/components/schemas/Dog"
+```
+
+The generated type carries the active variant and helper constructors:
+
+```go
+type Animal struct {
+    Type AnimalType // "Cat" or "Dog"
+    Cat  Cat
+    Dog  Dog
+}
+
+func NewCatAnimal(v Cat) Animal
+func NewDogAnimal(v Dog) Animal
+```
+
+Switch on the variant when handling a response:
+
+```go
+switch a.Type {
+case CatAnimal:
+    fmt.Println("meow:", a.Cat.Name)
+case DogAnimal:
+    fmt.Println("woof:", a.Dog.Name)
+}
+```
+
+ogen can also infer the discriminator automatically when none is defined — by
+type, by unique field names, or by enum values. See the
+[sum types reference](types/sumtype.md) for details.
+
+## Server-Sent Events
+
+For `text/event-stream` responses, ogen generates an SSE client:
+
+```yaml
+paths:
+  /events:
+    get:
+      operationId: streamEvents
+      responses:
+        '200':
+          description: Event stream
+          content:
+            text/event-stream:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                  createdAt:
+                    type: string
+                    format: date-time
+```
+
+The generated client exposes an iterator over events and handles reconnection
+automatically:
+
+```go
+stream, err := client.StreamEvents(ctx)
+if err != nil {
+    return err
+}
+defer stream.Close()
+
+for ev, err := range stream.All(ctx) {
+    if err != nil {
+        return err
+    }
+    fmt.Println(ev.Data.Message)
+}
+```
+
+## Securing requests
+
+Security schemes become a `SecuritySource` interface you implement once. For an
+API secured with a bearer token:
+
+```yaml
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+security:
+  - bearerAuth: []
+```
+
+```go
+type securitySource struct {
+    token string
+}
+
+func (s securitySource) BearerAuth(ctx context.Context, operationName api.OperationName) (api.BearerAuth, error) {
+    return api.BearerAuth{Token: s.token}, nil
+}
+
+client, err := api.NewClient(server, securitySource{token: os.Getenv("TOKEN")})
+```
+
+The token is then attached to every request that requires it.

docs/07-config.mdx

@@ -5,31 +5,163 @@ sidebar_label: Config
 sidebar_position: 7
 ---
 
-ogen could be configurated via `.ogen.yml` file:
+# Configuration
 
-```yaml [title=".ogen.yml"]
-# sets generator options.
+ogen can be configured via a YAML file passed with the `--config` flag:
+
+```bash
+go tool ogen --config .ogen.yml --target petstore --clean petstore.yml
+```
+
+Adding the schema annotation at the top of the file enables autocompletion and
+validation in editors that support the YAML language server:
+
+```yaml title=".ogen.yml"
+# yaml-language-server: $schema=https://raw.githubusercontent.com/ogen-go/ogen/main/schemas/ogen.jsonschema.json
+```
+
+The configuration has two main sections: `parser` controls how the OpenAPI
+document is read, and `generator` controls what code is produced.
+
+## Features
+
+ogen provides an opt-in/opt-out mechanism for features such as OpenTelemetry
+integration, client and server generation, and request validation.
+
+```yaml title=".ogen.yml"
 generator:
-  # sets generator features.
   features:
     enable:
-      # Enables paths client generation
+      # Generate client code for API paths.
       - "paths/client"
-      # Enables paths server generation
+      # Generate server code for API paths.
       - "paths/server"
-      # Enables validation of client requests
-      - "client/request/validation"
-      # Enables validation of server responses
-      - "server/response/validation"
-      # Enables OpenTelemetry integration
+      # Enable OpenTelemetry integration.
       - "ogen/otel"
+    disable:
+      # Disable server response validation.
+      - "server/response/validation"
+```
+
+Features are resolved in three steps: start from the default set (unless
+`disable_all` is `true`), apply `disable`, then apply `enable`. Entries in
+`enable` always take priority.
+
+The default feature set is:
+
+```yaml
+- paths/client
+- paths/server
+- webhooks/client
+- webhooks/server
+- ogen/otel
+- ogen/unimplemented
+```
+
+You can find the [complete feature list](https://github.com/ogen-go/ogen/blob/main/gen/features.go)
+in the ogen repository.
+
+### Generate only a client
+
+To generate a client without any server code, disable everything and enable
+just the client features:
+
+```yaml title=".ogen.yml"
+generator:
+  features:
+    enable:
+      - client/editors
+      - client/request/options
+      - ogen/otel
+      - ogen/unimplemented
+      - paths/client
+      - webhooks/client
     disable_all: true
 ```
 
-See full config example [here](https://github.com/ogen-go/ogen/blob/main/examples/config/example_all.yml).
+### Disable OpenTelemetry
+
+OpenTelemetry is enabled by default. Disable it to drop the dependency and the
+instrumentation code:
+
+```yaml title=".ogen.yml"
+generator:
+  features:
+    disable:
+      - "ogen/otel"
+```
+
+## Skipping unsupported operations
+
+Some real-world specifications contain constructs that ogen cannot yet
+generate. By default, generation fails on the first such error. Use
+`ignore_not_implemented` to skip those operations instead:
+
+```yaml title=".ogen.yml"
+generator:
+  # Skip all not-implemented generation errors.
+  ignore_not_implemented: ["all"]
+```
+
+You can also skip only specific cases, which keeps the rest of the
+specification strict:
+
+```yaml title=".ogen.yml"
+generator:
+  ignore_not_implemented:
+    - "nested objects in form parameters"
+```
+
+## Filters
+
+Generate code for a subset of the specification by path or HTTP method:
+
+```yaml title=".ogen.yml"
+generator:
+  filters:
+    # Only paths matching this regular expression are generated.
+    path_regex: "^/api/v1/.*"
+    # Only these methods are generated.
+    methods:
+      - GET
+      - POST
+```
+
+## Type inference
 
-### Features
+When a schema omits an explicit `type`, ogen can infer it from the schema's
+properties. This is required for many large real-world specs such as the
+GitHub or Kubernetes APIs:
 
-ogen provides a opt-in/opt-out mechanism for some features like OpenTelemetry integration.
+```yaml title=".ogen.yml"
+parser:
+  infer_types: true
+```
+
+## Full example
+
+A configuration combining the most common options, similar to what is used to
+generate the GitHub API client:
+
+```yaml title=".ogen.yml"
+# yaml-language-server: $schema=https://raw.githubusercontent.com/ogen-go/ogen/main/schemas/ogen.jsonschema.json
+
+parser:
+  # Detect schema type from its properties.
+  infer_types: true
+
+generator:
+  features:
+    enable:
+      - "paths/client"
+      - "paths/server"
+      - "ogen/otel"
+    disable_all: true
+  # Skip operations that are not yet supported.
+  ignore_not_implemented: ["all"]
+```
 
-You can find a [complete feature list](https://github.com/ogen-go/ogen/blob/main/gen/features.go) in ogen repository.
+See the [full reference config](https://github.com/ogen-go/ogen/blob/main/examples/config/example_all.yml),
+which documents every available option with example values, and the
+[default config](https://github.com/ogen-go/ogen/blob/main/examples/config/default_all.yml),
+which shows all defaults.