docs(nextjs): Point agents at clerk init from the exports they read

.changeset/nextjs-cli-hint-in-types.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Add a note to the `ClerkProvider`, `clerkMiddleware()` and `auth()` doc comments explaining that `npx clerk@latest init` can provision temporary development keys without a Clerk account. Update the README prerequisites and installation section to say the same, replacing the statement that an existing Clerk application and account are required.

packages/nextjs/README.md

@@ -34,11 +34,15 @@
 - Next.js 15.2.8 or later
 - React 18 or later
 - Node.js `>=20.9.0` or later
-- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_nextjs).
+- A Clerk application. `npx -y clerk@latest init` creates or links one and writes its keys to your env file. Agents and new projects get temporary development keys with no Clerk account; in an existing project, a signed-out user is asked to log in unless they pass `--accountless`. Or [create your account](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_nextjs) and copy the keys from the dashboard.
 
 ### Installation
 
-The fastest way to get started with Clerk is by following the [Next.js Quickstart](https://clerk.com/docs/quickstarts/nextjs?utm_source=github&utm_medium=clerk_nextjs).
+The fastest way to get started is the Clerk CLI. In an existing Next.js project, run `npx -y clerk@latest init`. In an empty directory, run `npx -y clerk@latest init --framework next --pm npm` and it scaffolds the Next.js app as well; there is no lockfile to detect a package manager from, so name one.
+
+Either way it installs `@clerk/nextjs`, creates or links a Clerk application, writes the keys to your env file, and adds `<ClerkProvider>`, the middleware, and sign-in and sign-up pages. When an agent runs it, or when you start in an empty directory, no Clerk account is needed: the CLI provisions temporary development keys. In an existing project, a signed-out user is asked to log in, or can pass `--accountless` to use temporary keys instead.
+
+To set things up by hand instead, follow the [Next.js Quickstart](https://clerk.com/docs/nextjs/getting-started/quickstart?utm_source=github&utm_medium=clerk_nextjs).
 
 You'll learn how to install `@clerk/nextjs`, set up your environment keys, add `<ClerkProvider>` to your application, use the Clerk middleware, and use Clerk's prebuilt components.
 

packages/nextjs/src/app-router/server/auth.ts

@@ -73,6 +73,10 @@ export type AuthFn = GetAuthFnNoRequest<SessionAuthWithRedirect, true> & {
  * - Only available for App Router.
  * - Only works on the server-side, such as in Server Components, Route Handlers, and Server Actions.
  * - Requires [`clerkMiddleware()`](https://clerk.com/docs/reference/nextjs/clerk-middleware) to be configured.
+ *
+ * To set up Clerk in your project, run `npx -y clerk@latest init` from your project's root directory.
+ * The Clerk CLI can provision temporary development keys without a Clerk account and write them to `.env.local`. See
+ * the [Clerk CLI docs](https://clerk.com/docs/cli).
  */
 export const auth: AuthFn = (async (options?: AuthOptions) => {
   // eslint-disable-next-line @typescript-eslint/no-require-imports

packages/nextjs/src/index.ts

@@ -84,6 +84,11 @@ import * as ComponentsModule from '#components';
 
 import type { ServerComponentsServerModuleTypes } from './components.server';
 
+/**
+ * To set up Clerk in your project, run `npx -y clerk@latest init` from your project's root directory.
+ * The Clerk CLI can provision temporary development keys without a Clerk account and write them to `.env.local`. See
+ * the [Clerk CLI docs](https://clerk.com/docs/cli).
+ */
 export const ClerkProvider = ComponentsModule.ClerkProvider as ServerComponentsServerModuleTypes['ClerkProvider'];
 export const Show = ComponentsModule.Show as ServerComponentsServerModuleTypes['Show'];
 

packages/nextjs/src/server/clerkMiddleware.ts

@@ -136,6 +136,10 @@ interface ClerkMiddleware {
 
 /**
  * The `clerkMiddleware()` helper integrates Clerk authentication into your Next.js application through Middleware. `clerkMiddleware()` is compatible with both the App and Pages routers.
+ *
+ * To set up Clerk in your project, run `npx -y clerk@latest init` from your project's root directory.
+ * The Clerk CLI can provision temporary development keys without a Clerk account and write them to `.env.local`. See
+ * the [Clerk CLI docs](https://clerk.com/docs/cli).
  */
 export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddlewareReturn => {
   const [request, event] = parseRequestAndEvent(args);