[backport] docs: late September improvements and fixes

docs/01-app/01-getting-started/01-installation.mdx

@@ -5,14 +5,52 @@ description: Learn how to create a new Next.js application with the `create-next
 
 {/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
 
+<AppOnly>
+
+Create a new Next.js app and run it locally.
+
+## Quick start
+
+1. Create a new Next.js app named `my-app`
+2. `cd my-app` and start the dev server.
+3. Visit `http://localhost:3000`.
+
+```bash package="pnpm"
+pnpm create next-app@latest my-app --yes
+cd my-app
+pnpm dev
+```
+
+```bash package="npm"
+npx create-next-app@latest my-app --yes
+cd my-app
+npm run dev
+```
+
+```bash package="yarn"
+yarn create next-app@latest my-app --yes
+cd my-app
+yarn dev
+```
+
+```bash package="bun"
+bun create next-app@latest my-app --yes
+cd my-app
+bun dev
+```
+
+- `--yes` skips prompts using saved preferences or defaults. The default setup enables TypeScript, Tailwind, App Router, and Turbopack, with import alias `@/*`.
+
+</AppOnly>
+
 ## System requirements
 
 Before you begin, make sure your system meets the following requirements:
 
 - [Node.js 18.18](https://nodejs.org/) or later.
 - macOS, Windows (including WSL), or Linux.
 
-## Automatic installation
+## Create with the CLI
 
 The quickest way to create a new Next.js app is using [`create-next-app`](/docs/app/api-reference/cli/create-next-app), which sets up everything automatically for you. To create a project, run:
 

docs/01-app/01-getting-started/02-project-structure.mdx

@@ -52,6 +52,8 @@ Top-level files are used to configure your application, manage dependencies, run
 
 ### Routing Files
 
+Add `page` to expose a route, `layout` for shared UI such as header, nav, or footer, `loading` for skeletons, `error` for error boundaries and `route` for APIs.
+
 |                                                                               |                     |                              |
 | ----------------------------------------------------------------------------- | ------------------- | ---------------------------- |
 | [`layout`](/docs/app/api-reference/file-conventions/layout)                   | `.js` `.jsx` `.tsx` | Layout                       |
@@ -66,35 +68,50 @@ Top-level files are used to configure your application, manage dependencies, run
 
 ### Nested routes
 
-|                 |                      |
-| --------------- | -------------------- |
-| `folder`        | Route segment        |
-| `folder/folder` | Nested route segment |
+Folders define URL segments. Nesting folders nests segments. Layouts at any level wrap their child segments. A route becomes public when a `page` or `route` file exists.
+
+| Path                        | URL pattern     | Notes                         |
+| --------------------------- | --------------- | ----------------------------- |
+| `app/layout.tsx`            | —               | Root layout wraps all routes  |
+| `app/blog/layout.tsx`       | —               | Wraps `/blog` and descendants |
+| `app/page.tsx`              | `/`             | Public route                  |
+| `app/blog/page.tsx`         | `/blog`         | Public route                  |
+| `app/blog/authors/page.tsx` | `/blog/authors` | Public route                  |
 
 ### Dynamic routes
 
-|                                                                                                        |                                  |
-| ------------------------------------------------------------------------------------------------------ | -------------------------------- |
-| [`[folder]`](/docs/app/api-reference/file-conventions/dynamic-routes#convention)                       | Dynamic route segment            |
-| [`[...folder]`](/docs/app/api-reference/file-conventions/dynamic-routes#catch-all-segments)            | Catch-all route segment          |
-| [`[[...folder]]`](/docs/app/api-reference/file-conventions/dynamic-routes#optional-catch-all-segments) | Optional catch-all route segment |
+Parameterize segments with square brackets. Use `[segment]` for a single param, `[...segment]` for catch‑all, and `[[...segment]]` for optional catch‑all. Access values via the [`params`](/docs/app/api-reference/file-conventions/page#params-optional) prop.
+
+| Path                            | URL pattern                                                          |
+| ------------------------------- | -------------------------------------------------------------------- |
+| `app/blog/[slug]/page.tsx`      | `/blog/my-first-post`                                                |
+| `app/shop/[...slug]/page.tsx`   | `/shop/clothing`, `/shop/clothing/shirts`                            |
+| `app/docs/[[...slug]]/page.tsx` | `/docs`, `/docs/layouts-and-pages`, `/docs/api-reference/use-router` |
 
 ### Route Groups and private folders
 
-|                                                                                |                                                  |
-| ------------------------------------------------------------------------------ | ------------------------------------------------ |
-| [`(folder)`](/docs/app/api-reference/file-conventions/route-groups#convention) | Group routes without affecting routing           |
-| [`_folder`](#private-folders)                                                  | Opt folder and all child segments out of routing |
+Organize code without changing URLs with route groups [`(group)`](/docs/app/api-reference/file-conventions/route-groups#convention), and colocate non-routable files with private folders [`_folder`](#private-folders).
+
+| Path                            | URL pattern | Notes                                     |
+| ------------------------------- | ----------- | ----------------------------------------- |
+| `app/(marketing)/page.tsx`      | `/`         | Group omitted from URL                    |
+| `app/(shop)/cart/page.tsx`      | `/cart`     | Share layouts within `(shop)`             |
+| `app/blog/_components/Post.tsx` | —           | Not routable; safe place for UI utilities |
+| `app/blog/_lib/data.ts`         | —           | Not routable; safe place for utils        |
 
 ### Parallel and Intercepted Routes
 
-|                                                                                             |                            |
-| ------------------------------------------------------------------------------------------- | -------------------------- |
-| [`@folder`](/docs/app/api-reference/file-conventions/parallel-routes#slots)                 | Named slot                 |
-| [`(.)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention)      | Intercept same level       |
-| [`(..)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention)     | Intercept one level above  |
-| [`(..)(..)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept two levels above |
-| [`(...)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention)    | Intercept from root        |
+These features fit specific UI patterns, such as slot-based layouts or modal routing.
+
+Use `@slot` for named slots rendered by a parent layout. Use intercept patterns to render another route inside the current layout without changing the URL, for example, to show a details view as a modal over a list.
+
+| Pattern (docs)                                                                              | Meaning              | Typical use case                     |
+| ------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------ |
+| [`@folder`](/docs/app/api-reference/file-conventions/parallel-routes#slots)                 | Named slot           | Sidebar + main content               |
+| [`(.)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention)      | Intercept same level | Preview sibling route in a modal     |
+| [`(..)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention)     | Intercept parent     | Open parent child as overlay         |
+| [`(..)(..)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention) | Intercept two levels | Deeply nested overlay                |
+| [`(...)folder`](/docs/app/api-reference/file-conventions/intercepting-routes#convention)    | Intercept from root  | Show arbitrary route in current view |
 
 ### Metadata file conventions
 

docs/01-app/02-guides/backend-for-frontend.mdx

@@ -28,7 +28,7 @@ To implement this pattern, use:
 
 - [Route Handlers](/docs/app/api-reference/file-conventions/route)
 - [`middleware`](/docs/app/api-reference/file-conventions/middleware)
-- In Pages Router, [API Routes](/pages/building-your-application/routing/api-routes)
+- In Pages Router, [API Routes](/docs/pages/building-your-application/routing/api-routes)
 
 ## Public Endpoints
 

docs/01-app/03-api-reference/03-file-conventions/error.mdx

@@ -219,7 +219,7 @@ export class GracefullyDegradingErrorBoundary extends Component<
   ErrorBoundaryProps,
   ErrorBoundaryState
 > {
-  private contentRef: React.RefObject<HTMLDivElement>
+  private contentRef: React.RefObject<HTMLDivElement | null>
 
   constructor(props: ErrorBoundaryProps) {
     super(props)

docs/01-app/03-api-reference/03-file-conventions/instrumentation.mdx

@@ -88,7 +88,7 @@ export function onRequestError(
   request: {
     path: string // resource path, e.g. /blog?name=foo
     method: string // request method. e.g. GET, POST, etc
-    headers: { [key: string]: string }
+    headers: { [key: string]: string | string[] }
   },
   context: {
     routerKind: 'Pages Router' | 'App Router' // the router type

docs/01-app/03-api-reference/03-file-conventions/middleware.mdx

@@ -20,6 +20,8 @@ Middleware executes before routes are rendered. It's particularly useful for imp
 
 Create a `middleware.ts` (or `.js`) file in the project root, or inside `src` if applicable, so that it is located at the same level as `pages` or `app`.
 
+If you’ve customized [`pageExtensions`](/docs/app/api-reference/config/next-config-js/pageExtensions), for example to `.page.ts` or `.page.js`, name your file `middleware.page.ts` or `middleware.page.js` accordingly.
+
 ```tsx filename="middleware.ts" switcher
 import { NextResponse, NextRequest } from 'next/server'
 

docs/01-app/03-api-reference/03-file-conventions/route.mdx

@@ -546,7 +546,6 @@ export async function GET(request) {
 > **Good to know**:
 >
 > - To add CORS headers to multiple Route Handlers, you can use [Middleware](/docs/app/api-reference/file-conventions/middleware#cors) or the [`next.config.js` file](/docs/app/api-reference/config/next-config-js/headers#cors).
-> - Alternatively, see our [CORS example](https://github.com/vercel/examples/blob/main/edge-functions/cors/lib/cors.ts) package.
 
 ### Webhooks