docs: document reserved folder names (fern, apis, changelog) (#3597)

Co-authored-by: fern-api[bot] <115122769+fern-api[bot]@users.noreply.github.com>

Author: devin-ai-integration[bot]

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

@@ -65,7 +65,8 @@ For the other specification formats ([OpenAPI](/api-definitions/openapi/overview
 
 ## Multiple APIs
 
-Fern supports two approaches for working with multiple API definitions:
+Fern supports two approaches for working with multiple API definitions. Both require an `apis` folder — this folder must use that exact name.
+
 
 1. **Separate SDKs for each API** - Each API generates its own independent set of SDK packages (e.g., `@company/user-api`, `@company/payments-api` or versioned like `@company/sdk-v1`, `@company/sdk-v2`)
 2. **Combined SDKs from multiple APIs** - Multiple APIs merge into a single SDK package with optional namespacing (e.g., `client.users`, `client.payments` or versioned like `client.v1`, `client.v2`)

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

@@ -20,13 +20,27 @@ This page provides an overview of the file and folder structure of a Fern Docs p
 
 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.
+- `pages`: Contains the Markdown (MDX) files that make up your documentation. This folder can use any name.
+- `assets`: Contains any images or videos used in your documentation. This folder can use any name.
 - `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.
 
+## Reserved folder names
+
+Some folders in a Fern project have reserved names and must be named exactly as shown:
+
+| Folder | Required name | When it's used |
+| --- | --- | --- |
+| `fern` | `fern` | Always. The root folder for every Fern project. |
+| `apis` | `apis` | Multi-API workspaces that contain more than one API definition. |
+| `changelog` | `changelog` | Projects that include a [changelog](/learn/docs/configuration/changelogs). |
+
+<Warning>
+Renaming these folders causes Fern to not recognize them. Always use the exact names listed above.
+</Warning>
+
 ## Pages folder
 
 The `pages` folder contains the Markdown (MDX) files that make up your documentation. Each MDX file represents a page in your documentation.
@@ -177,7 +191,7 @@ To generate [API Reference](/docs/api-references/generate-api-ref) documentation
       </Folder>
     </Files>
 
-    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).
+    The `apis` folder must use this exact name. Reference each API in `docs.yml` using `api-name` that matches the subfolder name. To see this in practice, check out [Vapi's Fern configuration](https://github.com/VapiAI/docs/tree/main/fern/apis).
 
   </Accordion>
 </AccordionGroup>
@@ -196,6 +210,6 @@ The `fern.config.json` file stores your organization name and the Fern CLI versi
 
 <Info> 
   When working with a locally installed CLI, set `version` to `"*"`. See [Install Fern CLI locally](/cli-api-reference/cli-reference/overview#install-fern-cli-locally) for details.
-</Info>                                                                                                                                                                                                                                                                                                
+</Info>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                
 
 

fern/products/docs/pages/navigation/changelogs.mdx

@@ -3,7 +3,7 @@ title: Keep a Changelog
 subtitle: Record the notable changes to your project
 ---
 
-Keep a record of how your project has changed by writing changelog entries that users can sort by tag. The changelog will automatically populate with the files contained within the `changelog` folder.
+Keep a record of how your project has changed by writing changelog entries that users can sort by tag. The changelog will automatically populate with the files contained within the `changelog` folder. This folder must be named `changelog` exactly — Fern won't recognize it under any other name.
 
 <Frame
     caption="Keep your users updated as your project evolves"