Clarify generators.yml dual purpose: API declaration and code generation

fern/products/api-def/grpc-pages/reference/generators-reference.mdx

@@ -3,6 +3,8 @@ title: gRPC generators.yml reference
 description: Reference for configuring gRPC specifications in your generators.yml file
 ---
 
-Configure how your gRPC specification is processed and transformed into SDKs and documentation using the `generators.yml` configuration file.
+The `generators.yml` file serves two roles: it declares your gRPC specification location (in the `api.specs` section), and configures SDK generation (in the optional `groups` section). 
 
-<Markdown src="/snippets/grpc-specs.mdx" />
+APIs declared here can be rendered in your documentation via `docs.yml`. See [Generate your API Reference](/learn/docs/api-references/generate-api-ref).
+
+<Markdown src="/snippets/grpc-specs.mdx" />

fern/products/api-def/openapi-pages/reference/generators-reference.mdx

@@ -3,6 +3,8 @@ title: OpenAPI generators.yml reference
 description: Reference for configuring OpenAPI specifications in your generators.yml file
 ---
 
-Configure how your OpenAPI specification is processed and transformed into SDKs using the `generators.yml` configuration file.
+The `generators.yml` file serves two roles: it declares your OpenAPI specification location (in the `api.specs` section), and configures SDK generation (in the optional `groups` section). 
 
-<Markdown src="/snippets/openapi-specs.mdx" />
+APIs declared here can be rendered in your documentation via `docs.yml`. See [Generate your API Reference](/learn/docs/api-references/generate-api-ref).
+
+<Markdown src="/snippets/openapi-specs.mdx" />

fern/products/api-def/pages/project-structure.mdx

@@ -15,7 +15,7 @@ When you run `fern init` (for the Fern Definition) or `fern init --spec-type pat
 ```bash
 fern/
   ├─ fern.config.json # Root-level config for entire Fern project
-  ├─ generators.yml # Defines SDKs and docs to generate
+  ├─ generators.yml # Declares APIs and configures SDK generation
   └─ spec-folder/ # definition, openapi, asyncapi, etc.
     └─ spec-file.yml # API definition file
 ```
@@ -32,16 +32,24 @@ fern/
 
 ### `generators.yml`
 
-<Markdown src="/snippets/generators-yml-project-structure.mdx" />
+The `generators.yml` file is required for OpenAPI/AsyncAPI to declare your API specification location. This also enables [API Reference documentation](/learn/docs/api-references/generate-api-ref).
+
+```yaml title="generators.yml"
+api:
+  specs:
+    - openapi: ./openapi/openapi.yml
+```
+
+**For Fern Definition**, no `generators.yml` is needed to [generate API Reference docs](/learn/docs/api-references/generate-api-ref). Fern automatically detects your API by checking for a `definition/` directory.
+
+For SDK generation, `generators.yml` is required for all specification formats. Add a `groups` section to configure which SDKs to generate. See the [SDKs project structure](/sdks/overview/project-structure#generatorsyml) for details.
 
 ### API definition file
 
 For Fern Definition, your API configuration is split across two files: `api.yml` for API-wide configuration and separate `.yml` files for your actual endpoint and type definitions. See [What is a Fern Definition?](/api-definitions/ferndef/overview) for more information. 
 
 For the other specification formats ([OpenAPI](/api-definitions/openapi/overview), [AsyncAPI](/api-definitions/asyncapi/overview), [OpenRPC](/api-definitions/openrpc/overview), and [gRPC](/api-definitions/grpc/overview)), you'll have a single self-contained specification file. 
 
-<Note>To generate API reference documentation, [set the `api-name` property](/docs/api-references/generate-api-ref#include-more-than-one-api-reference) in your `docs.yml` file.</Note>
-
 ## Multiple APIs
 
 When working with multiple API definitions, you can organize them in multiple ways depending on your SDK generation needs.

fern/products/docs/pages/api-references/generate-api-ref.mdx

@@ -3,17 +3,24 @@ title: Generate your API Reference
 description: Use Fern Docs to generate your API Reference documentation from your API definition, using your choice of either OpenAPI or Fern Definition.
 ---
 
-A key benefit of using Fern Docs is that once you've defined your API, you get your API Reference documentation with just one line.
-Add `- api: API Reference` to your navigation in `docs.yml` and Fern takes care of the rest! You'll see your endpoints, types,
-and cURL snippets automatically populated from your [OpenAPI Specification](/learn/api-definition/openapi/overview) or [Fern Definition](/learn/api-definition/fern/overview).
+Fern automatically generates your API Reference documentation from your [OpenAPI Specification](/learn/api-definition/openapi/overview) or [Fern Definition](/learn/api-definition/fern/overview). Once you've set up your API definition, adding it to your docs takes just one line of configuration.
 
-Example:
+<Info title="Prerequisites">
+  - For **OpenAPI/AsyncAPI**: Add your spec file and create a `generators.yml` that references it in the `api.specs` section
+  - For **Fern Definition**: Add a `definition/` directory with your API definition files (Fern auto-detects this)
+
+  [Learn more about project structure](/learn/api-definitions/overview/project-structure).
+</Info>
+
+Add `- api: API Reference` to your navigation in `docs.yml`:
 
 ```yml docs.yml
 navigation:
   - api: API Reference
 ```
 
+Fern will automatically populate your endpoints, types, and code snippets from your API definition.
+
 ### API Reference configuration options
 
 | Property         | Value                                                                                                   |
@@ -36,18 +43,20 @@ More on customizing your API Reference [here](/learn/docs/api-references/customi
 
 ### Include more than one API Reference
 
-To include multiple, distinct API definitions in your documentation, you can indicate which to include using the `api-name` property. The `api-name` corresponds to the name of the folder where your API definition is housed. 
+To include multiple, distinct API definitions in your documentation, use the `api-name` property. The `api-name` corresponds to the folder name containing your API definition.
 
-For example, your file structure might look like this:
+This works with any combination of OpenAPI and Fern Definition formats. For example:
 
 ```bash
 fern/
-  ├─ fern.config.json 
+  ├─ fern.config.json
   ├─ docs.yml
-  ├─ plant-api/         
-  │   └─ api.yml     # API definition
-  └─ garden-api/          
-      └─ api.yml    # API definition
+  ├─ plant-api/
+  │   ├─ openapi.yml       # OpenAPI spec
+  │   └─ generators.yml    # References the OpenAPI spec
+  └─ garden-api/
+      └─ definition/       # Fern Definition (auto-detected)
+          └─ api.yml
 ```
 
 For a simple setup without tabs, you can include multiple API References directly in your navigation:

fern/products/docs/pages/getting-started/project-structure.mdx

@@ -1,5 +1,5 @@
 ---
-title: Project Structure
+title: Project structure
 description: An overview of the file and folder structure of a Fern Docs project
 ---
 
@@ -13,7 +13,8 @@ This page provides an overview of the file and folder structure of a Fern Docs p
   ├─ pages
   ├─ assets
   ├─ docs.yml
-  ├─ openapi
+  ├─ openapi # or definition/ for the Fern Definition
+  ├─ generators.yml
   └─ fern.config.json
 ```
 </CodeBlock>
@@ -22,8 +23,9 @@ A Fern Docs project has the following top-level folders:
 
 - `pages`: Contains the Markdown (MDX) files that make up your documentation.
 - `assets`: Contains any images or videos used in your documentation.
-- `docs.yml`: The configuration file that defines the navigation, theme, and hosting details of your documentation.
-- `openapi`: Contains the OpenAPI Specification file (if you have an API Reference section in your documentation).
+- `docs.yml`: Defines the navigation, theme, and hosting details of your documentation.
+- `openapi` or `definition/`: Contains your API specification files (if you have an API Reference section).
+- `generators.yml`: Required for OpenAPI to reference your spec location. Also used to configure SDK generation. Not required for Fern Definition docs-only projects.
 - `fern.config.json`: The configuration file specifying your organization name and CLI version.
 
 ## Pages folder
@@ -106,11 +108,26 @@ title: Fern's Documentation
 ```
 </CodeBlock>
 
-## API Definitions 
+## API definitions and `generators.yml`
+
+To generate [API Reference](/docs/api-references/generate-api-ref) documentation, you need to provide your API definition. How you do this depends on your format:
+
+- **OpenAPI/AsyncAPI**: Always requires a `generators.yml` file with an `api.specs` section. You can optionally add a `groups` section for SDK generation.
+- **Fern Definition**: Auto-detected when you have a `definition/` directory. Only add `generators.yml` if you're generating SDKs.
+
+<Info>Using Fern for both API Reference docs and SDKs? You'll use `docs.yml` for your documentation settings and `generators.yml` to configure [SDK code snippets](/docs/api-references/sdk-snippets) in your API Reference.</Info>
 
 <AccordionGroup>
   <Accordion title="OpenAPI">
-    The `openapi` folder contains the OpenAPI Specification file for your API Reference section. Fern will read either a YAML or JSON file from this folder to generate the API Reference documentation. If you don't have an API Reference section, you can skip this folder.
+    The `openapi` folder contains your OpenAPI Specification file. Fern supports either YAML or JSON format.
+
+    You must also create a `generators.yml` file that references your spec:
+
+    ```yaml title="generators.yml"
+    api:
+      specs:
+        - openapi: ../openapi/openapi.json
+    ```
 
     In addition to your specification file, you can optionally [add an overrides file](/api-definitions/overview/overrides) for additional customizations. 
 
@@ -126,9 +143,9 @@ title: Fern's Documentation
 
   </Accordion>
   <Accordion title="Fern Definition">
-    The `definition` folder contains the Fern Definition YAML files used to generate the API Reference section. If you don't have an API Reference section, you can skip this folder.
+    The `definition` folder contains the Fern Definition YAML files used to generate the API Reference section. Fern automatically detects this directory, so no `generators.yml` is needed for API Reference documentation.
 
-    In addition to your specification file, you can optionally [add an overrides file](/api-definitions/overview/overrides) for additional customizations. 
+    You can optionally [add an overrides file](/api-definitions/overview/overrides) for additional customizations. 
 
     <CodeBlock title="fern/definition">
     ```bash
@@ -145,38 +162,27 @@ title: Fern's Documentation
 
   </Accordion>
   <Accordion title="Multiple APIs">
-    If you have multiple APIs, you can organize them into separate folders within the `apis` folder. Each API should have its own API definition and [(optional) overrides file](/api-definitions/overview/overrides). 
-
-    For example:
+    Organize multiple APIs into separate folders. You can mix OpenAPI and Fern Definition formats:
+
     <CodeBlock title="fern/apis">
     ```bash
     apis
-    ├─ admin
-    │  ├─ openapi.json 
-    │  └─ overrides.yaml
-    ├─ user
-    │  ├─ openapi.yaml 
-    │  └─ overrides.yaml
+    ├─ admin-api
+    │  ├─ openapi.json
+    │  ├─ generators.yml       # Required for OpenAPI
+    │  └─ overrides.yaml       # Optional
+    └─ user-api
+       └─ definition/          # Auto-detected for Fern Definition
+          ├─ api.yml
+          └─ overrides.yaml    # Optional
     ```
     </CodeBlock>
 
-    To see this in practice, check out [Vapi's Fern configuration](https://github.com/VapiAI/docs/tree/main/fern/apis).
+    Reference each API in `docs.yml` using `api-name` that matches the folder name. To see this in practice, check out [Vapi's Fern configuration](https://github.com/VapiAI/docs/tree/main/fern/apis).
 
   </Accordion>
 </AccordionGroup>
 
-<Note>
-  If you're using Fern for both API Reference documentation and SDKs, you'll use both `docs.yml` (the Docs configuration file) and `generators.yml` ([the SDK configuration file](/sdks/overview/project-structure#generatorsyml)) to configure [how SDK code snippets appear](/docs/api-references/sdk-snippets) in your API reference documentation.  
-
-  If you're only using Fern for API Reference docs, not SDKs, your `generators.yml` should simply link to your spec:
-
-  ```yaml title="generators.yml"
-  api:
-    specs:
-      - openapi: ../openapi/openapi.json
-  ```
-</Note>
-
 
 ## `fern.config.json`
 

fern/products/sdks/project-structure.mdx

@@ -47,9 +47,58 @@ The source repository contains a `fern/` folder  that is initialized with your A
 
 ### `generators.yml`
 
-<Markdown src="/snippets/generators-yml-project-structure.mdx" />
+The `generators.yml` file configures SDK generation in the `groups` section. For OpenAPI/AsyncAPI, you must also declare your API spec location in the `api.specs` section.
+
+<Tabs>
+<Tab title="OpenAPI/AsyncAPI">
+
+```yaml title="generators.yml"
+# API declaration (required for OpenAPI/AsyncAPI)
+api:
+  specs:
+    - openapi: ./openapi/openapi.yml
+
+# SDK generation
+groups:
+  ts-sdk:
+    generators:
+      - name: fernapi/fern-typescript-sdk
+        version: <Markdown src="/snippets/version-number-ts.mdx"/>
+        github:
+          repository: your-organization/typescript-sdk-repo
+
+  python-sdk:
+    generators:
+      - name: fernapi/fern-python-sdk
+        version: <Markdown src="/snippets/version-number-python.mdx"/>
+        github:
+          repository: your-organization/python-sdk-repo
+```
+</Tab>
+<Tab title="Fern Definition">
+
+For Fern Definition, the `api` section isn't needed. Fern auto-detects your API from the `definition/` directory.
+
+```yaml title="generators.yml"
+groups:
+  ts-sdk:
+    generators:
+      - name: fernapi/fern-typescript-sdk
+        version: <Markdown src="/snippets/version-number-ts.mdx"/>
+        github:
+          repository: your-organization/typescript-sdk-repo
+
+  python-sdk:
+    generators:
+      - name: fernapi/fern-python-sdk
+        version: <Markdown src="/snippets/version-number-python.mdx"/>
+        github:
+          repository: your-organization/python-sdk-repo
+```
+</Tab>
+</Tabs>
 
-<Info title="Examples"> 
+<Info title="Examples">
   See Cohere's [`generators.yml` file](https://github.com/cohere-ai/cohere-developer-experience/blob/23d6c541a01eb6b54dd9bb3588c805bb0e307713/fern/apis/sdks/generators.yml) and Vapi's [`generators.yml` file](https://github.com/VapiAI/docs/blob/9c674c2b16ba03e864e26673c5290c88048c9a7a/fern/apis/api/generators.yml).
 </Info>
 

fern/products/sdks/reference/generators-yml-reference.mdx

@@ -4,9 +4,7 @@ description: Reference for the generators.yml configuration
 max-toc-depth: 3
 ---
 
-The `generators.yml` file configures how Fern generates SDKs from your API
-specification, including which languages to generate, where to publish them, and
-how to customize each SDK.
+The `generators.yml` file serves two purposes: it declares your API definition (required for OpenAPI/AsyncAPI), and configures SDK generation, including which languages to generate, where to publish them, and how to customize each SDK.
 
 ```yaml title="generators.yml" maxLines=10
 api: