Improve fern.config.json documentation

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

@@ -26,20 +26,9 @@ fern/
   Beyond the core files, you can optionally use an overrides file to customize your API definition without modifying the original spec. See [Overrides](/api-definitions/overview/overrides) for instructions.
 </Note>
 
-### `fern.config.json file`
+### `fern.config.json`
 
-Every fern folder has a single `fern.config.json` file. This file stores the organization and
-the version of the Fern CLI that you are using. 
-
-```json title="fern.config.json"
-{
-    "organization": "your-organization",
-    "version": "0.31.2"
-}
-```
-
-Every time you run a fern CLI command, the CLI downloads itself at the correct version to ensure 
-determinism. 
+<Markdown src="/snippets/fern-config-json-reference.mdx" />
 
 ### `generators.yml`
 
@@ -196,4 +185,4 @@ groups:
 ```
 
 </Accordion>
-</AccordionGroup>
+</AccordionGroup>

fern/products/cli-api-reference/pages/cli-get-started.mdx

@@ -39,6 +39,8 @@ In your `fern.config.json`, set the version to `*` to use your locally installed
 }
 ```
 
+See the [fern.config.json reference](/learn/sdks/overview/project-structure#fernconfigjson) for more details.
+
 </Step>
 
 <Step title="Run via package manager">

fern/products/cli-api-reference/pages/commands.mdx

@@ -221,7 +221,7 @@ hideOnThisPage: true
 
   <Accordion title="fern check">
 
-    Use `fern check` to validate your API definition and Fern configuration: `fern.config.json`, `generators.yml`, and `docs.yml`.
+    Use `fern check` to validate your API definition and Fern configuration: [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson), `generators.yml`, and `docs.yml`.
 
     When successfully executed, this command will not produce any output.
 
@@ -336,7 +336,7 @@ hideOnThisPage: true
 
   <Accordion title="fern upgrade">
 
-    Use `fern upgrade` to upgrade your compiler version in `fern.config.json` to the
+    Use `fern upgrade` to upgrade your compiler version in [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) to the
     latest version. It will also upgrade generators in `generators.yml` to their minimum-compatible versions.
 
     <CodeBlock title="terminal">
@@ -389,8 +389,8 @@ hideOnThisPage: true
 
   <Accordion title="fern token">
 
-    Use `fern token `to generate a `FERN_TOKEN` specific to your organization defined 
-    in `fern.config.json`. Use the token to authenticate with the API in CI. Tokens do not expire.
+    Use `fern token` to generate a `FERN_TOKEN` specific to your organization defined 
+    in [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson). Use the token to authenticate with the API in CI. Tokens do not expire.
 
     <CodeBlock title="terminal">
     ```bash 

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

@@ -180,15 +180,6 @@ title: Fern's Documentation
 
 ## `fern.config.json`
 
-The `fern.config.json` file specifies your organization name and the version of the Fern CLI used to generate the documentation. You can customize this file to reflect your organization's details.
-
-<CodeBlock title="fern/fern.config.json">
-```json
-{
-  "organization": "my-organization",
-  "version": "<Markdown src="/snippets/version-number-cli.mdx"/>"
-}
-```
-</CodeBlock> 
+<Markdown src="/snippets/fern-config-json-reference.mdx" />   
 
 

fern/products/docs/pages/getting-started/quickstart.mdx

@@ -29,15 +29,15 @@ In this guide, we'll show you how to get started with Fern in under 5 minutes.
       Next, please update the template settings to use your organization.
 
       <Warning title="Edit template settings">
-        Please edit the details `fern.config.json` and `docs.yml` with your organization
+        Please edit the details in `fern.config.json` and `docs.yml` with your organization
         name.
 
         <CodeBlocks>
           <CodeBlock title="fern.config.json">
           ```json  {2}
           {
             "organization": "{{YOUR_ORGANIZATION}}",
-            "version": "0.x.x"
+            "version": "<Markdown src="/snippets/version-number-cli.mdx"/>"
           }
           ```
           </CodeBlock>
@@ -48,6 +48,8 @@ In this guide, we'll show you how to get started with Fern in under 5 minutes.
           ```
           </CodeBlock>
         </CodeBlocks>
+
+        See the [fern.config.json reference](/learn/sdks/overview/project-structure#fernconfigjson) for more details.
       </Warning>
       Finally, navigate to the docs directory (where the `fern` folder is located) and execute the following command to generate your documentation:
 

fern/products/sdks/project-structure.mdx

@@ -43,16 +43,7 @@ The source repository contains a `fern/` folder  that is initialized with your A
 
 ### `fern.config.json`
 
-Every fern folder has a single `fern.config.json` file. This file stores the organization name and the version of the Fern CLI that you are using:
-
-```json
-{
-    "organization": "your-organization",
-    "version": "<Markdown src="/snippets/version-number-cli.mdx"/>"
-}
-```
-
-Every time you run a fern CLI command, the CLI downloads itself at the correct version to ensure determinism.
+<Markdown src="/snippets/fern-config-json-reference.mdx" />
 
 ### `generators.yml`
 
@@ -72,4 +63,4 @@ See [Project structure (API Definitions)](/api-definitions/overview/project-stru
 
 1. **Create repositories**: Set up your source repository, plus one repository for each SDK
 2. **Install Fern GitHub App**: Install the [Fern GitHub App](https://github.com/apps/fern-api) on all repositories
-3. **Configure `generators.yml`**: In your `generators.yml`, add a reference to each SDK repository.
+3. **Configure `generators.yml`**: In your `generators.yml`, add a reference to each SDK repository.

fern/snippets/fern-config-json-reference.mdx

@@ -0,0 +1,57 @@
+## What is fern.config.json?
+
+Every `fern/` folder contains a single `fern.config.json` file at its root. This configuration file stores your organization name and the Fern CLI version used for your project.
+
+### Schema
+
+The `fern.config.json` file has two required fields:
+
+- **`organization`** (string): Your organization identifier. This is used by `fern token` to generate organization-specific authentication tokens and to scope CLI actions to your organization. You can view and manage your organization in the [Fern Dashboard](https://dashboard.buildwithfern.com/).
+
+- **`version`** (string): The Fern CLI version to use. Accepts a pinned semantic version (e.g., `"0.94.1"`) or `"*"` to use your locally installed CLI version.
+
+### Examples
+
+<Tabs>
+<Tab title="Pinned version (recommended for CI)">
+
+```json title="fern.config.json"
+{
+  "organization": "plant-catalog",
+  "version": "<Markdown src="/snippets/version-number-cli.mdx"/>"
+}
+```
+
+Pinning to a specific version ensures deterministic builds. Every time you run a Fern CLI command, the CLI downloads itself at the specified version.
+
+</Tab>
+<Tab title="Local development">
+
+```json title="fern.config.json"
+{
+  "organization": "plant-catalog",
+  "version": "*"
+}
+```
+
+Using `"*"` tells Fern to use your locally installed CLI version. This is useful for local development when you've installed Fern as a project dependency. See [Install Fern CLI locally](/learn/cli-api/cli-reference/overview#install-fern-cli-locally) for details.
+
+</Tab>
+</Tabs>
+
+### When to change these values
+
+- **`organization`**: Rarely needs to be changed. Only update this if your organization identifier changes in the Fern Dashboard.
+
+- **`version`**: Use the `fern upgrade` command to update to the latest CLI version. The command automatically updates this field in `fern.config.json` and upgrades generators in `generators.yml` to their minimum-compatible versions.
+
+### How the CLI uses this file
+
+The following CLI commands read from `fern.config.json`:
+
+- **`fern check`**: Validates the configuration file
+- **`fern upgrade`**: Updates the `version` field to the latest CLI version
+- **`fern token`**: Uses the `organization` field to generate organization-specific tokens
+- **`fern init`**: Creates this file when initializing a new project
+
+The version pinning ensures determinism across different environments. When you run any Fern CLI command, it automatically downloads and uses the specified CLI version, ensuring consistent behavior in local development, CI/CD pipelines, and across team members.