feat(release): prepare clerk 1.0.0 release

.changeset/clerk-1-0-0.md

@@ -0,0 +1,7 @@
+---
+"clerk": major
+---
+
+Release Clerk CLI 1.0 as the first stable `1.x` line.
+
+This milestone rolls up the recent improvements to bootstrap flows, authentication and keyless claiming, bundled agent skills, PATH-aware updates, interactive prompts, and docs into a stable baseline for the standalone `clerk` CLI.

.github/release-notes/v1.0.0.md

@@ -0,0 +1,27 @@
+# Clerk CLI 1.0
+
+Clerk CLI `1.0.0` is the first stable `1.x` release of the standalone `clerk` command line tool.
+
+This release marks the CLI as a stable, supported interface for working with Clerk from the terminal: bootstrapping new projects, authenticating, linking apps, pulling environment variables, inspecting and updating instance configuration, making direct API requests, running integration health checks, switching environments, opening dashboard resources, installing the bundled Clerk agent skill, and updating the CLI itself.
+
+Core workflows available in Clerk CLI `1.0.0` include:
+
+- `clerk init` to bootstrap Clerk into supported projects and starters
+- `clerk auth`, `clerk whoami`, `clerk link`, and `clerk unlink` for account and project association
+- `clerk env pull` for pulling Clerk environment variables into local env files
+- `clerk config pull`, `schema`, `patch`, and `put` for instance configuration management
+- `clerk api` and `clerk apps` for direct platform access from the terminal
+- `clerk doctor` for integration diagnostics and guided fixes
+- `clerk open`, `clerk switch-env`, `clerk completion`, `clerk skill install`, and `clerk update` for day-to-day developer workflows
+
+Install Clerk CLI:
+
+```sh
+# Homebrew (macOS / Linux)
+brew install clerk/stable/clerk
+
+# npm
+npm install -g clerk
+```
+
+See the autogenerated notes below for the full PR-by-PR changelog included in this `1.0.0` release.

README.md

@@ -224,7 +224,3 @@ clerk update
  $ clerk update --yes Update without confirmation prompt
  $ clerk update --all Update every clerk install on PATH
 ```
-
-## Open Questions
-
-- How do we keep types in sync with PLAPI?

docs/releasing.md

@@ -95,6 +95,8 @@ This launches an interactive prompt that asks which packages changed and whether
 
 On every push to `main`, the `changesets/action@v1` GitHub Action either creates a new "Version Packages" PR or updates an existing one. That PR aggregates all pending changesets, bumps versions, and updates changelogs. Merging it triggers a stable release (detected by `scripts/check-release.ts`).
 
+Changeset summaries drive the package changelog and the contents of the generated "Version Packages" PR. They do **not** control the GitHub Release body for stable releases; that comes from GitHub's autogenerated release notes, optionally prepended with a checked-in intro file at `.github/release-notes/vX.Y.Z.md`.
+
 Configuration:
 
 - `.changeset/config.json` -- Changesets configuration (access, snapshot template, ignored packages)
@@ -166,7 +168,7 @@ Runs the releaser script (`scripts/releaser/index.ts`) via `bun run release` (st
  - Copies the compiled binary from the build artifacts
 3. Publishes each platform package with `--access public` (authentication and provenance use npm OIDC trusted publishing -- no `NPM_TOKEN` secret needed, just `id-token: write` permission on a GitHub-hosted runner)
 4. Temporarily mutates the wrapper `package.json` to add `optionalDependencies` and remove `private: true`, publishes it, then restores the original file
-5. For stable releases, creates a Git tag and GitHub Release via the GitHub API
+5. For stable releases, creates a Git tag and GitHub Release via the GitHub API. If `.github/release-notes/vX.Y.Z.md` exists for that version, its contents are prepended ahead of GitHub's autogenerated notes.
 
 The releaser accepts these flags:
 
@@ -211,6 +213,7 @@ Install: `brew install clerk/stable/clerk`
 | `packages/cli-core/src/globals.d.ts` | TypeScript declaration for the `CLI_VERSION` compile-time define |
 | `install.sh` | Shell install script — downloads binary from GitHub Releases |
 | `scripts/releaser/index.ts` | Generates platform packages and publishes everything to npm |
+| `.github/release-notes/vX.Y.Z.md` | Optional version-specific intro prepended to stable GitHub Release notes |
 | `scripts/releaser/targets.ts` | Target definitions (used by both releaser and build.ts) |
 | `scripts/build.ts` | Cross-compiles CLI binaries for all 8 platform targets |
 | `scripts/sign-macos.ts` | Signs and notarizes macOS binaries (keychain, codesign, notarytool) |

scripts/lib/release-notes.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { getStableReleaseCreateArgs } from "./release-notes.ts";
+
+describe("getStableReleaseCreateArgs", () => {
+ let tempDir: string;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "release-notes-"));
+ });
+
+ afterEach(async () => {
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ test("uses plain generated notes when no intro file exists", async () => {
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+
+ test("prepends version-specific notes when the intro file exists", async () => {
+ const notesPath = join(tempDir, "v1.0.0.md");
+ await Bun.write(notesPath, "Intro line\n\n- Highlight");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: [
+ "gh",
+ "release",
+ "create",
+ "v1.0.0",
+ "--generate-notes",
+ "--notes",
+ "Intro line\n\n- Highlight",
+ ],
+ notesPath,
+ });
+ });
+
+ test("ignores empty intro files", async () => {
+ await Bun.write(join(tempDir, "v1.0.0.md"), "\n \n");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+});

scripts/lib/release-notes.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+
+const DEFAULT_STABLE_RELEASE_NOTES_DIR = join(import.meta.dir, "../../.github/release-notes");
+
+export type StableReleaseCreateArgs = {
+ args: string[];
+ notesPath?: string;
+};
+
+export async function getStableReleaseCreateArgs(
+ version: string,
+ notesDir = DEFAULT_STABLE_RELEASE_NOTES_DIR,
+): Promise<StableReleaseCreateArgs> {
+ const tagName = `v${version}`;
+ const args = ["gh", "release", "create", tagName, "--generate-notes"];
+ const notesPath = join(notesDir, `v${version}.md`);
+
+ if (!(await Bun.file(notesPath).exists())) {
+ return { args };
+ }
+
+ const notes = (await Bun.file(notesPath).text()).trim();
+ if (!notes) {
+ return { args };
+ }
+
+ return { args: [...args, "--notes", notes], notesPath };
+}

scripts/releaser.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { type Target, targets, SCOPE, PKG_PREFIX } from "./lib/targets.ts";
 import { run, isPublished, publish } from "./lib/npm.ts";
+import { getStableReleaseCreateArgs } from "./lib/release-notes.ts";
 
 const DIST_DIR = join(import.meta.dir, "../dist/platform-packages");
 const ARTIFACTS_DIR = process.env.ARTIFACTS_DIR ?? join(import.meta.dir, "../dist/artifacts");
@@ -136,7 +137,11 @@ if (!tag && !dryRun) {
  console.log(`GitHub Release for ${tagName} already exists, skipping.`);
  } else {
  console.log(`Creating GitHub Release for ${tagName}...`);
- await run(["gh", "release", "create", tagName, "--generate-notes"]);
+ const { args: releaseArgs, notesPath } = await getStableReleaseCreateArgs(version);
+ if (notesPath) {
+ console.log(`Prepending release intro from ${notesPath}...`);
+ }
+ await run(releaseArgs);
  }
 }
 

.changeset/clerk-1-0-0.md

@@ -0,0 +1,7 @@
+---
+"clerk": major
+---
+
+Release Clerk CLI 1.0 as the first stable `1.x` line.
+
+This milestone rolls up the recent improvements to bootstrap flows, authentication and keyless claiming, bundled agent skills, PATH-aware updates, interactive prompts, and docs into a stable baseline for the standalone `clerk` CLI.

.github/release-notes/v1.0.0.md

@@ -0,0 +1,27 @@
+# Clerk CLI 1.0
+
+Clerk CLI `1.0.0` is the first stable `1.x` release of the standalone `clerk` command line tool.
+
+This release marks the CLI as a stable, supported interface for working with Clerk from the terminal: bootstrapping new projects, authenticating, linking apps, pulling environment variables, inspecting and updating instance configuration, making direct API requests, running integration health checks, switching environments, opening dashboard resources, installing the bundled Clerk agent skill, and updating the CLI itself.
+
+Core workflows available in Clerk CLI `1.0.0` include:
+
+- `clerk init` to bootstrap Clerk into supported projects and starters
+- `clerk auth`, `clerk whoami`, `clerk link`, and `clerk unlink` for account and project association
+- `clerk env pull` for pulling Clerk environment variables into local env files
+- `clerk config pull`, `schema`, `patch`, and `put` for instance configuration management
+- `clerk api` and `clerk apps` for direct platform access from the terminal
+- `clerk doctor` for integration diagnostics and guided fixes
+- `clerk open`, `clerk switch-env`, `clerk completion`, `clerk skill install`, and `clerk update` for day-to-day developer workflows
+
+Install Clerk CLI:
+
+```sh
+# Homebrew (macOS / Linux)
+brew install clerk/stable/clerk
+
+# npm
+npm install -g clerk
+```
+
+See the autogenerated notes below for the full PR-by-PR changelog included in this `1.0.0` release.

README.md

@@ -224,7 +224,3 @@ clerk update
  $ clerk update --yes Update without confirmation prompt
  $ clerk update --all Update every clerk install on PATH
 ```
-
-## Open Questions
-
-- How do we keep types in sync with PLAPI?

docs/releasing.md

@@ -95,6 +95,8 @@ This launches an interactive prompt that asks which packages changed and whether
 
 On every push to `main`, the `changesets/action@v1` GitHub Action either creates a new "Version Packages" PR or updates an existing one. That PR aggregates all pending changesets, bumps versions, and updates changelogs. Merging it triggers a stable release (detected by `scripts/check-release.ts`).
 
+Changeset summaries drive the package changelog and the contents of the generated "Version Packages" PR. They do **not** control the GitHub Release body for stable releases; that comes from GitHub's autogenerated release notes, optionally prepended with a checked-in intro file at `.github/release-notes/vX.Y.Z.md`.
+
 Configuration:
 
 - `.changeset/config.json` -- Changesets configuration (access, snapshot template, ignored packages)
@@ -166,7 +168,7 @@ Runs the releaser script (`scripts/releaser/index.ts`) via `bun run release` (st
  - Copies the compiled binary from the build artifacts
 3. Publishes each platform package with `--access public` (authentication and provenance use npm OIDC trusted publishing -- no `NPM_TOKEN` secret needed, just `id-token: write` permission on a GitHub-hosted runner)
 4. Temporarily mutates the wrapper `package.json` to add `optionalDependencies` and remove `private: true`, publishes it, then restores the original file
-5. For stable releases, creates a Git tag and GitHub Release via the GitHub API
+5. For stable releases, creates a Git tag and GitHub Release via the GitHub API. If `.github/release-notes/vX.Y.Z.md` exists for that version, its contents are prepended ahead of GitHub's autogenerated notes.
 
 The releaser accepts these flags:
 
@@ -211,6 +213,7 @@ Install: `brew install clerk/stable/clerk`
 | `packages/cli-core/src/globals.d.ts` | TypeScript declaration for the `CLI_VERSION` compile-time define |
 | `install.sh` | Shell install script — downloads binary from GitHub Releases |
 | `scripts/releaser/index.ts` | Generates platform packages and publishes everything to npm |
+| `.github/release-notes/vX.Y.Z.md` | Optional version-specific intro prepended to stable GitHub Release notes |
 | `scripts/releaser/targets.ts` | Target definitions (used by both releaser and build.ts) |
 | `scripts/build.ts` | Cross-compiles CLI binaries for all 8 platform targets |
 | `scripts/sign-macos.ts` | Signs and notarizes macOS binaries (keychain, codesign, notarytool) |

scripts/lib/release-notes.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { getStableReleaseCreateArgs } from "./release-notes.ts";
+
+describe("getStableReleaseCreateArgs", () => {
+ let tempDir: string;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "release-notes-"));
+ });
+
+ afterEach(async () => {
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ test("uses plain generated notes when no intro file exists", async () => {
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+
+ test("prepends version-specific notes when the intro file exists", async () => {
+ const notesPath = join(tempDir, "v1.0.0.md");
+ await Bun.write(notesPath, "Intro line\n\n- Highlight");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: [
+ "gh",
+ "release",
+ "create",
+ "v1.0.0",
+ "--generate-notes",
+ "--notes",
+ "Intro line\n\n- Highlight",
+ ],
+ notesPath,
+ });
+ });
+
+ test("ignores empty intro files", async () => {
+ await Bun.write(join(tempDir, "v1.0.0.md"), "\n \n");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+});

scripts/lib/release-notes.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+
+const DEFAULT_STABLE_RELEASE_NOTES_DIR = join(import.meta.dir, "../../.github/release-notes");
+
+export type StableReleaseCreateArgs = {
+ args: string[];
+ notesPath?: string;
+};
+
+export async function getStableReleaseCreateArgs(
+ version: string,
+ notesDir = DEFAULT_STABLE_RELEASE_NOTES_DIR,
+): Promise<StableReleaseCreateArgs> {
+ const tagName = `v${version}`;
+ const args = ["gh", "release", "create", tagName, "--generate-notes"];
+ const notesPath = join(notesDir, `v${version}.md`);
+
+ if (!(await Bun.file(notesPath).exists())) {
+ return { args };
+ }
+
+ const notes = (await Bun.file(notesPath).text()).trim();
+ if (!notes) {
+ return { args };
+ }
+
+ return { args: [...args, "--notes", notes], notesPath };
+}

scripts/releaser.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { type Target, targets, SCOPE, PKG_PREFIX } from "./lib/targets.ts";
 import { run, isPublished, publish } from "./lib/npm.ts";
+import { getStableReleaseCreateArgs } from "./lib/release-notes.ts";
 
 const DIST_DIR = join(import.meta.dir, "../dist/platform-packages");
 const ARTIFACTS_DIR = process.env.ARTIFACTS_DIR ?? join(import.meta.dir, "../dist/artifacts");
@@ -136,7 +137,11 @@ if (!tag && !dryRun) {
  console.log(`GitHub Release for ${tagName} already exists, skipping.`);
  } else {
  console.log(`Creating GitHub Release for ${tagName}...`);
- await run(["gh", "release", "create", tagName, "--generate-notes"]);
+ const { args: releaseArgs, notesPath } = await getStableReleaseCreateArgs(version);
+ if (notesPath) {
+ console.log(`Prepending release intro from ${notesPath}...`);
+ }
+ await run(releaseArgs);
  }
 }
 

.changeset/clerk-1-0-0.md

@@ -0,0 +1,7 @@
+---
+"clerk": major
+---
+
+Release Clerk CLI 1.0 as the first stable `1.x` line.
+
+This milestone rolls up the recent improvements to bootstrap flows, authentication and keyless claiming, bundled agent skills, PATH-aware updates, interactive prompts, and docs into a stable baseline for the standalone `clerk` CLI.

.github/release-notes/v1.0.0.md

@@ -0,0 +1,27 @@
+# Clerk CLI 1.0
+
+Clerk CLI `1.0.0` is the first stable `1.x` release of the standalone `clerk` command line tool.
+
+This release marks the CLI as a stable, supported interface for working with Clerk from the terminal: bootstrapping new projects, authenticating, linking apps, pulling environment variables, inspecting and updating instance configuration, making direct API requests, running integration health checks, switching environments, opening dashboard resources, installing the bundled Clerk agent skill, and updating the CLI itself.
+
+Core workflows available in Clerk CLI `1.0.0` include:
+
+- `clerk init` to bootstrap Clerk into supported projects and starters
+- `clerk auth`, `clerk whoami`, `clerk link`, and `clerk unlink` for account and project association
+- `clerk env pull` for pulling Clerk environment variables into local env files
+- `clerk config pull`, `schema`, `patch`, and `put` for instance configuration management
+- `clerk api` and `clerk apps` for direct platform access from the terminal
+- `clerk doctor` for integration diagnostics and guided fixes
+- `clerk open`, `clerk switch-env`, `clerk completion`, `clerk skill install`, and `clerk update` for day-to-day developer workflows
+
+Install Clerk CLI:
+
+```sh
+# Homebrew (macOS / Linux)
+brew install clerk/stable/clerk
+
+# npm
+npm install -g clerk
+```
+
+See the autogenerated notes below for the full PR-by-PR changelog included in this `1.0.0` release.

README.md

@@ -224,7 +224,3 @@ clerk update
  $ clerk update --yes Update without confirmation prompt
  $ clerk update --all Update every clerk install on PATH
 ```
-
-## Open Questions
-
-- How do we keep types in sync with PLAPI?

docs/releasing.md

@@ -95,6 +95,8 @@ This launches an interactive prompt that asks which packages changed and whether
 
 On every push to `main`, the `changesets/action@v1` GitHub Action either creates a new "Version Packages" PR or updates an existing one. That PR aggregates all pending changesets, bumps versions, and updates changelogs. Merging it triggers a stable release (detected by `scripts/check-release.ts`).
 
+Changeset summaries drive the package changelog and the contents of the generated "Version Packages" PR. They do **not** control the GitHub Release body for stable releases; that comes from GitHub's autogenerated release notes, optionally prepended with a checked-in intro file at `.github/release-notes/vX.Y.Z.md`.
+
 Configuration:
 
 - `.changeset/config.json` -- Changesets configuration (access, snapshot template, ignored packages)
@@ -166,7 +168,7 @@ Runs the releaser script (`scripts/releaser/index.ts`) via `bun run release` (st
  - Copies the compiled binary from the build artifacts
 3. Publishes each platform package with `--access public` (authentication and provenance use npm OIDC trusted publishing -- no `NPM_TOKEN` secret needed, just `id-token: write` permission on a GitHub-hosted runner)
 4. Temporarily mutates the wrapper `package.json` to add `optionalDependencies` and remove `private: true`, publishes it, then restores the original file
-5. For stable releases, creates a Git tag and GitHub Release via the GitHub API
+5. For stable releases, creates a Git tag and GitHub Release via the GitHub API. If `.github/release-notes/vX.Y.Z.md` exists for that version, its contents are prepended ahead of GitHub's autogenerated notes.
 
 The releaser accepts these flags:
 
@@ -211,6 +213,7 @@ Install: `brew install clerk/stable/clerk`
 | `packages/cli-core/src/globals.d.ts` | TypeScript declaration for the `CLI_VERSION` compile-time define |
 | `install.sh` | Shell install script — downloads binary from GitHub Releases |
 | `scripts/releaser/index.ts` | Generates platform packages and publishes everything to npm |
+| `.github/release-notes/vX.Y.Z.md` | Optional version-specific intro prepended to stable GitHub Release notes |
 | `scripts/releaser/targets.ts` | Target definitions (used by both releaser and build.ts) |
 | `scripts/build.ts` | Cross-compiles CLI binaries for all 8 platform targets |
 | `scripts/sign-macos.ts` | Signs and notarizes macOS binaries (keychain, codesign, notarytool) |

scripts/lib/release-notes.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { getStableReleaseCreateArgs } from "./release-notes.ts";
+
+describe("getStableReleaseCreateArgs", () => {
+ let tempDir: string;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "release-notes-"));
+ });
+
+ afterEach(async () => {
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ test("uses plain generated notes when no intro file exists", async () => {
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+
+ test("prepends version-specific notes when the intro file exists", async () => {
+ const notesPath = join(tempDir, "v1.0.0.md");
+ await Bun.write(notesPath, "Intro line\n\n- Highlight");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: [
+ "gh",
+ "release",
+ "create",
+ "v1.0.0",
+ "--generate-notes",
+ "--notes",
+ "Intro line\n\n- Highlight",
+ ],
+ notesPath,
+ });
+ });
+
+ test("ignores empty intro files", async () => {
+ await Bun.write(join(tempDir, "v1.0.0.md"), "\n \n");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+});

scripts/lib/release-notes.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+
+const DEFAULT_STABLE_RELEASE_NOTES_DIR = join(import.meta.dir, "../../.github/release-notes");
+
+export type StableReleaseCreateArgs = {
+ args: string[];
+ notesPath?: string;
+};
+
+export async function getStableReleaseCreateArgs(
+ version: string,
+ notesDir = DEFAULT_STABLE_RELEASE_NOTES_DIR,
+): Promise<StableReleaseCreateArgs> {
+ const tagName = `v${version}`;
+ const args = ["gh", "release", "create", tagName, "--generate-notes"];
+ const notesPath = join(notesDir, `v${version}.md`);
+
+ if (!(await Bun.file(notesPath).exists())) {
+ return { args };
+ }
+
+ const notes = (await Bun.file(notesPath).text()).trim();
+ if (!notes) {
+ return { args };
+ }
+
+ return { args: [...args, "--notes", notes], notesPath };
+}

scripts/releaser.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { type Target, targets, SCOPE, PKG_PREFIX } from "./lib/targets.ts";
 import { run, isPublished, publish } from "./lib/npm.ts";
+import { getStableReleaseCreateArgs } from "./lib/release-notes.ts";
 
 const DIST_DIR = join(import.meta.dir, "../dist/platform-packages");
 const ARTIFACTS_DIR = process.env.ARTIFACTS_DIR ?? join(import.meta.dir, "../dist/artifacts");
@@ -136,7 +137,11 @@ if (!tag && !dryRun) {
  console.log(`GitHub Release for ${tagName} already exists, skipping.`);
  } else {
  console.log(`Creating GitHub Release for ${tagName}...`);
- await run(["gh", "release", "create", tagName, "--generate-notes"]);
+ const { args: releaseArgs, notesPath } = await getStableReleaseCreateArgs(version);
+ if (notesPath) {
+ console.log(`Prepending release intro from ${notesPath}...`);
+ }
+ await run(releaseArgs);
  }
 }
 

.changeset/clerk-1-0-0.md

@@ -0,0 +1,7 @@
+---
+"clerk": major
+---
+
+Release Clerk CLI 1.0 as the first stable `1.x` line.
+
+This milestone rolls up the recent improvements to bootstrap flows, authentication and keyless claiming, bundled agent skills, PATH-aware updates, interactive prompts, and docs into a stable baseline for the standalone `clerk` CLI.

.github/release-notes/v1.0.0.md

@@ -0,0 +1,27 @@
+# Clerk CLI 1.0
+
+Clerk CLI `1.0.0` is the first stable `1.x` release of the standalone `clerk` command line tool.
+
+This release marks the CLI as a stable, supported interface for working with Clerk from the terminal: bootstrapping new projects, authenticating, linking apps, pulling environment variables, inspecting and updating instance configuration, making direct API requests, running integration health checks, switching environments, opening dashboard resources, installing the bundled Clerk agent skill, and updating the CLI itself.
+
+Core workflows available in Clerk CLI `1.0.0` include:
+
+- `clerk init` to bootstrap Clerk into supported projects and starters
+- `clerk auth`, `clerk whoami`, `clerk link`, and `clerk unlink` for account and project association
+- `clerk env pull` for pulling Clerk environment variables into local env files
+- `clerk config pull`, `schema`, `patch`, and `put` for instance configuration management
+- `clerk api` and `clerk apps` for direct platform access from the terminal
+- `clerk doctor` for integration diagnostics and guided fixes
+- `clerk open`, `clerk switch-env`, `clerk completion`, `clerk skill install`, and `clerk update` for day-to-day developer workflows
+
+Install Clerk CLI:
+
+```sh
+# Homebrew (macOS / Linux)
+brew install clerk/stable/clerk
+
+# npm
+npm install -g clerk
+```
+
+See the autogenerated notes below for the full PR-by-PR changelog included in this `1.0.0` release.

README.md

@@ -224,7 +224,3 @@ clerk update
  $ clerk update --yes Update without confirmation prompt
  $ clerk update --all Update every clerk install on PATH
 ```
-
-## Open Questions
-
-- How do we keep types in sync with PLAPI?

docs/releasing.md

@@ -95,6 +95,8 @@ This launches an interactive prompt that asks which packages changed and whether
 
 On every push to `main`, the `changesets/action@v1` GitHub Action either creates a new "Version Packages" PR or updates an existing one. That PR aggregates all pending changesets, bumps versions, and updates changelogs. Merging it triggers a stable release (detected by `scripts/check-release.ts`).
 
+Changeset summaries drive the package changelog and the contents of the generated "Version Packages" PR. They do **not** control the GitHub Release body for stable releases; that comes from GitHub's autogenerated release notes, optionally prepended with a checked-in intro file at `.github/release-notes/vX.Y.Z.md`.
+
 Configuration:
 
 - `.changeset/config.json` -- Changesets configuration (access, snapshot template, ignored packages)
@@ -166,7 +168,7 @@ Runs the releaser script (`scripts/releaser/index.ts`) via `bun run release` (st
  - Copies the compiled binary from the build artifacts
 3. Publishes each platform package with `--access public` (authentication and provenance use npm OIDC trusted publishing -- no `NPM_TOKEN` secret needed, just `id-token: write` permission on a GitHub-hosted runner)
 4. Temporarily mutates the wrapper `package.json` to add `optionalDependencies` and remove `private: true`, publishes it, then restores the original file
-5. For stable releases, creates a Git tag and GitHub Release via the GitHub API
+5. For stable releases, creates a Git tag and GitHub Release via the GitHub API. If `.github/release-notes/vX.Y.Z.md` exists for that version, its contents are prepended ahead of GitHub's autogenerated notes.
 
 The releaser accepts these flags:
 
@@ -211,6 +213,7 @@ Install: `brew install clerk/stable/clerk`
 | `packages/cli-core/src/globals.d.ts` | TypeScript declaration for the `CLI_VERSION` compile-time define |
 | `install.sh` | Shell install script — downloads binary from GitHub Releases |
 | `scripts/releaser/index.ts` | Generates platform packages and publishes everything to npm |
+| `.github/release-notes/vX.Y.Z.md` | Optional version-specific intro prepended to stable GitHub Release notes |
 | `scripts/releaser/targets.ts` | Target definitions (used by both releaser and build.ts) |
 | `scripts/build.ts` | Cross-compiles CLI binaries for all 8 platform targets |
 | `scripts/sign-macos.ts` | Signs and notarizes macOS binaries (keychain, codesign, notarytool) |

scripts/lib/release-notes.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { getStableReleaseCreateArgs } from "./release-notes.ts";
+
+describe("getStableReleaseCreateArgs", () => {
+ let tempDir: string;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "release-notes-"));
+ });
+
+ afterEach(async () => {
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ test("uses plain generated notes when no intro file exists", async () => {
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+
+ test("prepends version-specific notes when the intro file exists", async () => {
+ const notesPath = join(tempDir, "v1.0.0.md");
+ await Bun.write(notesPath, "Intro line\n\n- Highlight");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: [
+ "gh",
+ "release",
+ "create",
+ "v1.0.0",
+ "--generate-notes",
+ "--notes",
+ "Intro line\n\n- Highlight",
+ ],
+ notesPath,
+ });
+ });
+
+ test("ignores empty intro files", async () => {
+ await Bun.write(join(tempDir, "v1.0.0.md"), "\n \n");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+});

scripts/lib/release-notes.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+
+const DEFAULT_STABLE_RELEASE_NOTES_DIR = join(import.meta.dir, "../../.github/release-notes");
+
+export type StableReleaseCreateArgs = {
+ args: string[];
+ notesPath?: string;
+};
+
+export async function getStableReleaseCreateArgs(
+ version: string,
+ notesDir = DEFAULT_STABLE_RELEASE_NOTES_DIR,
+): Promise<StableReleaseCreateArgs> {
+ const tagName = `v${version}`;
+ const args = ["gh", "release", "create", tagName, "--generate-notes"];
+ const notesPath = join(notesDir, `v${version}.md`);
+
+ if (!(await Bun.file(notesPath).exists())) {
+ return { args };
+ }
+
+ const notes = (await Bun.file(notesPath).text()).trim();
+ if (!notes) {
+ return { args };
+ }
+
+ return { args: [...args, "--notes", notes], notesPath };
+}

scripts/releaser.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { type Target, targets, SCOPE, PKG_PREFIX } from "./lib/targets.ts";
 import { run, isPublished, publish } from "./lib/npm.ts";
+import { getStableReleaseCreateArgs } from "./lib/release-notes.ts";
 
 const DIST_DIR = join(import.meta.dir, "../dist/platform-packages");
 const ARTIFACTS_DIR = process.env.ARTIFACTS_DIR ?? join(import.meta.dir, "../dist/artifacts");
@@ -136,7 +137,11 @@ if (!tag && !dryRun) {
  console.log(`GitHub Release for ${tagName} already exists, skipping.`);
  } else {
  console.log(`Creating GitHub Release for ${tagName}...`);
- await run(["gh", "release", "create", tagName, "--generate-notes"]);
+ const { args: releaseArgs, notesPath } = await getStableReleaseCreateArgs(version);
+ if (notesPath) {
+ console.log(`Prepending release intro from ${notesPath}...`);
+ }
+ await run(releaseArgs);
  }
 }
 

.changeset/clerk-1-0-0.md

@@ -0,0 +1,7 @@
+---
+"clerk": major
+---
+
+Release Clerk CLI 1.0 as the first stable `1.x` line.
+
+This milestone rolls up the recent improvements to bootstrap flows, authentication and keyless claiming, bundled agent skills, PATH-aware updates, interactive prompts, and docs into a stable baseline for the standalone `clerk` CLI.

.github/release-notes/v1.0.0.md

@@ -0,0 +1,27 @@
+# Clerk CLI 1.0
+
+Clerk CLI `1.0.0` is the first stable `1.x` release of the standalone `clerk` command line tool.
+
+This release marks the CLI as a stable, supported interface for working with Clerk from the terminal: bootstrapping new projects, authenticating, linking apps, pulling environment variables, inspecting and updating instance configuration, making direct API requests, running integration health checks, switching environments, opening dashboard resources, installing the bundled Clerk agent skill, and updating the CLI itself.
+
+Core workflows available in Clerk CLI `1.0.0` include:
+
+- `clerk init` to bootstrap Clerk into supported projects and starters
+- `clerk auth`, `clerk whoami`, `clerk link`, and `clerk unlink` for account and project association
+- `clerk env pull` for pulling Clerk environment variables into local env files
+- `clerk config pull`, `schema`, `patch`, and `put` for instance configuration management
+- `clerk api` and `clerk apps` for direct platform access from the terminal
+- `clerk doctor` for integration diagnostics and guided fixes
+- `clerk open`, `clerk switch-env`, `clerk completion`, `clerk skill install`, and `clerk update` for day-to-day developer workflows
+
+Install Clerk CLI:
+
+```sh
+# Homebrew (macOS / Linux)
+brew install clerk/stable/clerk
+
+# npm
+npm install -g clerk
+```
+
+See the autogenerated notes below for the full PR-by-PR changelog included in this `1.0.0` release.

README.md

@@ -224,7 +224,3 @@ clerk update
  $ clerk update --yes Update without confirmation prompt
  $ clerk update --all Update every clerk install on PATH
 ```
-
-## Open Questions
-
-- How do we keep types in sync with PLAPI?

docs/releasing.md

@@ -95,6 +95,8 @@ This launches an interactive prompt that asks which packages changed and whether
 
 On every push to `main`, the `changesets/action@v1` GitHub Action either creates a new "Version Packages" PR or updates an existing one. That PR aggregates all pending changesets, bumps versions, and updates changelogs. Merging it triggers a stable release (detected by `scripts/check-release.ts`).
 
+Changeset summaries drive the package changelog and the contents of the generated "Version Packages" PR. They do **not** control the GitHub Release body for stable releases; that comes from GitHub's autogenerated release notes, optionally prepended with a checked-in intro file at `.github/release-notes/vX.Y.Z.md`.
+
 Configuration:
 
 - `.changeset/config.json` -- Changesets configuration (access, snapshot template, ignored packages)
@@ -166,7 +168,7 @@ Runs the releaser script (`scripts/releaser/index.ts`) via `bun run release` (st
  - Copies the compiled binary from the build artifacts
 3. Publishes each platform package with `--access public` (authentication and provenance use npm OIDC trusted publishing -- no `NPM_TOKEN` secret needed, just `id-token: write` permission on a GitHub-hosted runner)
 4. Temporarily mutates the wrapper `package.json` to add `optionalDependencies` and remove `private: true`, publishes it, then restores the original file
-5. For stable releases, creates a Git tag and GitHub Release via the GitHub API
+5. For stable releases, creates a Git tag and GitHub Release via the GitHub API. If `.github/release-notes/vX.Y.Z.md` exists for that version, its contents are prepended ahead of GitHub's autogenerated notes.
 
 The releaser accepts these flags:
 
@@ -211,6 +213,7 @@ Install: `brew install clerk/stable/clerk`
 | `packages/cli-core/src/globals.d.ts` | TypeScript declaration for the `CLI_VERSION` compile-time define |
 | `install.sh` | Shell install script — downloads binary from GitHub Releases |
 | `scripts/releaser/index.ts` | Generates platform packages and publishes everything to npm |
+| `.github/release-notes/vX.Y.Z.md` | Optional version-specific intro prepended to stable GitHub Release notes |
 | `scripts/releaser/targets.ts` | Target definitions (used by both releaser and build.ts) |
 | `scripts/build.ts` | Cross-compiles CLI binaries for all 8 platform targets |
 | `scripts/sign-macos.ts` | Signs and notarizes macOS binaries (keychain, codesign, notarytool) |

scripts/lib/release-notes.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { getStableReleaseCreateArgs } from "./release-notes.ts";
+
+describe("getStableReleaseCreateArgs", () => {
+ let tempDir: string;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "release-notes-"));
+ });
+
+ afterEach(async () => {
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ test("uses plain generated notes when no intro file exists", async () => {
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+
+ test("prepends version-specific notes when the intro file exists", async () => {
+ const notesPath = join(tempDir, "v1.0.0.md");
+ await Bun.write(notesPath, "Intro line\n\n- Highlight");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: [
+ "gh",
+ "release",
+ "create",
+ "v1.0.0",
+ "--generate-notes",
+ "--notes",
+ "Intro line\n\n- Highlight",
+ ],
+ notesPath,
+ });
+ });
+
+ test("ignores empty intro files", async () => {
+ await Bun.write(join(tempDir, "v1.0.0.md"), "\n \n");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+});

scripts/lib/release-notes.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+
+const DEFAULT_STABLE_RELEASE_NOTES_DIR = join(import.meta.dir, "../../.github/release-notes");
+
+export type StableReleaseCreateArgs = {
+ args: string[];
+ notesPath?: string;
+};
+
+export async function getStableReleaseCreateArgs(
+ version: string,
+ notesDir = DEFAULT_STABLE_RELEASE_NOTES_DIR,
+): Promise<StableReleaseCreateArgs> {
+ const tagName = `v${version}`;
+ const args = ["gh", "release", "create", tagName, "--generate-notes"];
+ const notesPath = join(notesDir, `v${version}.md`);
+
+ if (!(await Bun.file(notesPath).exists())) {
+ return { args };
+ }
+
+ const notes = (await Bun.file(notesPath).text()).trim();
+ if (!notes) {
+ return { args };
+ }
+
+ return { args: [...args, "--notes", notes], notesPath };
+}

scripts/releaser.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { type Target, targets, SCOPE, PKG_PREFIX } from "./lib/targets.ts";
 import { run, isPublished, publish } from "./lib/npm.ts";
+import { getStableReleaseCreateArgs } from "./lib/release-notes.ts";
 
 const DIST_DIR = join(import.meta.dir, "../dist/platform-packages");
 const ARTIFACTS_DIR = process.env.ARTIFACTS_DIR ?? join(import.meta.dir, "../dist/artifacts");
@@ -136,7 +137,11 @@ if (!tag && !dryRun) {
  console.log(`GitHub Release for ${tagName} already exists, skipping.`);
  } else {
  console.log(`Creating GitHub Release for ${tagName}...`);
- await run(["gh", "release", "create", tagName, "--generate-notes"]);
+ const { args: releaseArgs, notesPath } = await getStableReleaseCreateArgs(version);
+ if (notesPath) {
+ console.log(`Prepending release intro from ${notesPath}...`);
+ }
+ await run(releaseArgs);
  }
 }
 

.changeset/clerk-1-0-0.md

@@ -0,0 +1,7 @@
+---
+"clerk": major
+---
+
+Release Clerk CLI 1.0 as the first stable `1.x` line.
+
+This milestone rolls up the recent improvements to bootstrap flows, authentication and keyless claiming, bundled agent skills, PATH-aware updates, interactive prompts, and docs into a stable baseline for the standalone `clerk` CLI.

.github/release-notes/v1.0.0.md

@@ -0,0 +1,27 @@
+# Clerk CLI 1.0
+
+Clerk CLI `1.0.0` is the first stable `1.x` release of the standalone `clerk` command line tool.
+
+This release marks the CLI as a stable, supported interface for working with Clerk from the terminal: bootstrapping new projects, authenticating, linking apps, pulling environment variables, inspecting and updating instance configuration, making direct API requests, running integration health checks, switching environments, opening dashboard resources, installing the bundled Clerk agent skill, and updating the CLI itself.
+
+Core workflows available in Clerk CLI `1.0.0` include:
+
+- `clerk init` to bootstrap Clerk into supported projects and starters
+- `clerk auth`, `clerk whoami`, `clerk link`, and `clerk unlink` for account and project association
+- `clerk env pull` for pulling Clerk environment variables into local env files
+- `clerk config pull`, `schema`, `patch`, and `put` for instance configuration management
+- `clerk api` and `clerk apps` for direct platform access from the terminal
+- `clerk doctor` for integration diagnostics and guided fixes
+- `clerk open`, `clerk switch-env`, `clerk completion`, `clerk skill install`, and `clerk update` for day-to-day developer workflows
+
+Install Clerk CLI:
+
+```sh
+# Homebrew (macOS / Linux)
+brew install clerk/stable/clerk
+
+# npm
+npm install -g clerk
+```
+
+See the autogenerated notes below for the full PR-by-PR changelog included in this `1.0.0` release.

README.md

@@ -224,7 +224,3 @@ clerk update
  $ clerk update --yes Update without confirmation prompt
  $ clerk update --all Update every clerk install on PATH
 ```
-
-## Open Questions
-
-- How do we keep types in sync with PLAPI?

docs/releasing.md

@@ -95,6 +95,8 @@ This launches an interactive prompt that asks which packages changed and whether
 
 On every push to `main`, the `changesets/action@v1` GitHub Action either creates a new "Version Packages" PR or updates an existing one. That PR aggregates all pending changesets, bumps versions, and updates changelogs. Merging it triggers a stable release (detected by `scripts/check-release.ts`).
 
+Changeset summaries drive the package changelog and the contents of the generated "Version Packages" PR. They do **not** control the GitHub Release body for stable releases; that comes from GitHub's autogenerated release notes, optionally prepended with a checked-in intro file at `.github/release-notes/vX.Y.Z.md`.
+
 Configuration:
 
 - `.changeset/config.json` -- Changesets configuration (access, snapshot template, ignored packages)
@@ -166,7 +168,7 @@ Runs the releaser script (`scripts/releaser/index.ts`) via `bun run release` (st
  - Copies the compiled binary from the build artifacts
 3. Publishes each platform package with `--access public` (authentication and provenance use npm OIDC trusted publishing -- no `NPM_TOKEN` secret needed, just `id-token: write` permission on a GitHub-hosted runner)
 4. Temporarily mutates the wrapper `package.json` to add `optionalDependencies` and remove `private: true`, publishes it, then restores the original file
-5. For stable releases, creates a Git tag and GitHub Release via the GitHub API
+5. For stable releases, creates a Git tag and GitHub Release via the GitHub API. If `.github/release-notes/vX.Y.Z.md` exists for that version, its contents are prepended ahead of GitHub's autogenerated notes.
 
 The releaser accepts these flags:
 
@@ -211,6 +213,7 @@ Install: `brew install clerk/stable/clerk`
 | `packages/cli-core/src/globals.d.ts` | TypeScript declaration for the `CLI_VERSION` compile-time define |
 | `install.sh` | Shell install script — downloads binary from GitHub Releases |
 | `scripts/releaser/index.ts` | Generates platform packages and publishes everything to npm |
+| `.github/release-notes/vX.Y.Z.md` | Optional version-specific intro prepended to stable GitHub Release notes |
 | `scripts/releaser/targets.ts` | Target definitions (used by both releaser and build.ts) |
 | `scripts/build.ts` | Cross-compiles CLI binaries for all 8 platform targets |
 | `scripts/sign-macos.ts` | Signs and notarizes macOS binaries (keychain, codesign, notarytool) |

scripts/lib/release-notes.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { getStableReleaseCreateArgs } from "./release-notes.ts";
+
+describe("getStableReleaseCreateArgs", () => {
+ let tempDir: string;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "release-notes-"));
+ });
+
+ afterEach(async () => {
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ test("uses plain generated notes when no intro file exists", async () => {
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+
+ test("prepends version-specific notes when the intro file exists", async () => {
+ const notesPath = join(tempDir, "v1.0.0.md");
+ await Bun.write(notesPath, "Intro line\n\n- Highlight");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: [
+ "gh",
+ "release",
+ "create",
+ "v1.0.0",
+ "--generate-notes",
+ "--notes",
+ "Intro line\n\n- Highlight",
+ ],
+ notesPath,
+ });
+ });
+
+ test("ignores empty intro files", async () => {
+ await Bun.write(join(tempDir, "v1.0.0.md"), "\n \n");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+});

scripts/lib/release-notes.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+
+const DEFAULT_STABLE_RELEASE_NOTES_DIR = join(import.meta.dir, "../../.github/release-notes");
+
+export type StableReleaseCreateArgs = {
+ args: string[];
+ notesPath?: string;
+};
+
+export async function getStableReleaseCreateArgs(
+ version: string,
+ notesDir = DEFAULT_STABLE_RELEASE_NOTES_DIR,
+): Promise<StableReleaseCreateArgs> {
+ const tagName = `v${version}`;
+ const args = ["gh", "release", "create", tagName, "--generate-notes"];
+ const notesPath = join(notesDir, `v${version}.md`);
+
+ if (!(await Bun.file(notesPath).exists())) {
+ return { args };
+ }
+
+ const notes = (await Bun.file(notesPath).text()).trim();
+ if (!notes) {
+ return { args };
+ }
+
+ return { args: [...args, "--notes", notes], notesPath };
+}

scripts/releaser.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { type Target, targets, SCOPE, PKG_PREFIX } from "./lib/targets.ts";
 import { run, isPublished, publish } from "./lib/npm.ts";
+import { getStableReleaseCreateArgs } from "./lib/release-notes.ts";
 
 const DIST_DIR = join(import.meta.dir, "../dist/platform-packages");
 const ARTIFACTS_DIR = process.env.ARTIFACTS_DIR ?? join(import.meta.dir, "../dist/artifacts");
@@ -136,7 +137,11 @@ if (!tag && !dryRun) {
  console.log(`GitHub Release for ${tagName} already exists, skipping.`);
  } else {
  console.log(`Creating GitHub Release for ${tagName}...`);
- await run(["gh", "release", "create", tagName, "--generate-notes"]);
+ const { args: releaseArgs, notesPath } = await getStableReleaseCreateArgs(version);
+ if (notesPath) {
+ console.log(`Prepending release intro from ${notesPath}...`);
+ }
+ await run(releaseArgs);
  }
 }
 

.changeset/clerk-1-0-0.md

@@ -0,0 +1,7 @@
+---
+"clerk": major
+---
+
+Release Clerk CLI 1.0 as the first stable `1.x` line.
+
+This milestone rolls up the recent improvements to bootstrap flows, authentication and keyless claiming, bundled agent skills, PATH-aware updates, interactive prompts, and docs into a stable baseline for the standalone `clerk` CLI.

.github/release-notes/v1.0.0.md

@@ -0,0 +1,27 @@
+# Clerk CLI 1.0
+
+Clerk CLI `1.0.0` is the first stable `1.x` release of the standalone `clerk` command line tool.
+
+This release marks the CLI as a stable, supported interface for working with Clerk from the terminal: bootstrapping new projects, authenticating, linking apps, pulling environment variables, inspecting and updating instance configuration, making direct API requests, running integration health checks, switching environments, opening dashboard resources, installing the bundled Clerk agent skill, and updating the CLI itself.
+
+Core workflows available in Clerk CLI `1.0.0` include:
+
+- `clerk init` to bootstrap Clerk into supported projects and starters
+- `clerk auth`, `clerk whoami`, `clerk link`, and `clerk unlink` for account and project association
+- `clerk env pull` for pulling Clerk environment variables into local env files
+- `clerk config pull`, `schema`, `patch`, and `put` for instance configuration management
+- `clerk api` and `clerk apps` for direct platform access from the terminal
+- `clerk doctor` for integration diagnostics and guided fixes
+- `clerk open`, `clerk switch-env`, `clerk completion`, `clerk skill install`, and `clerk update` for day-to-day developer workflows
+
+Install Clerk CLI:
+
+```sh
+# Homebrew (macOS / Linux)
+brew install clerk/stable/clerk
+
+# npm
+npm install -g clerk
+```
+
+See the autogenerated notes below for the full PR-by-PR changelog included in this `1.0.0` release.

README.md

@@ -224,7 +224,3 @@ clerk update
  $ clerk update --yes Update without confirmation prompt
  $ clerk update --all Update every clerk install on PATH
 ```
-
-## Open Questions
-
-- How do we keep types in sync with PLAPI?

docs/releasing.md

@@ -95,6 +95,8 @@ This launches an interactive prompt that asks which packages changed and whether
 
 On every push to `main`, the `changesets/action@v1` GitHub Action either creates a new "Version Packages" PR or updates an existing one. That PR aggregates all pending changesets, bumps versions, and updates changelogs. Merging it triggers a stable release (detected by `scripts/check-release.ts`).
 
+Changeset summaries drive the package changelog and the contents of the generated "Version Packages" PR. They do **not** control the GitHub Release body for stable releases; that comes from GitHub's autogenerated release notes, optionally prepended with a checked-in intro file at `.github/release-notes/vX.Y.Z.md`.
+
 Configuration:
 
 - `.changeset/config.json` -- Changesets configuration (access, snapshot template, ignored packages)
@@ -166,7 +168,7 @@ Runs the releaser script (`scripts/releaser/index.ts`) via `bun run release` (st
  - Copies the compiled binary from the build artifacts
 3. Publishes each platform package with `--access public` (authentication and provenance use npm OIDC trusted publishing -- no `NPM_TOKEN` secret needed, just `id-token: write` permission on a GitHub-hosted runner)
 4. Temporarily mutates the wrapper `package.json` to add `optionalDependencies` and remove `private: true`, publishes it, then restores the original file
-5. For stable releases, creates a Git tag and GitHub Release via the GitHub API
+5. For stable releases, creates a Git tag and GitHub Release via the GitHub API. If `.github/release-notes/vX.Y.Z.md` exists for that version, its contents are prepended ahead of GitHub's autogenerated notes.
 
 The releaser accepts these flags:
 
@@ -211,6 +213,7 @@ Install: `brew install clerk/stable/clerk`
 | `packages/cli-core/src/globals.d.ts` | TypeScript declaration for the `CLI_VERSION` compile-time define |
 | `install.sh` | Shell install script — downloads binary from GitHub Releases |
 | `scripts/releaser/index.ts` | Generates platform packages and publishes everything to npm |
+| `.github/release-notes/vX.Y.Z.md` | Optional version-specific intro prepended to stable GitHub Release notes |
 | `scripts/releaser/targets.ts` | Target definitions (used by both releaser and build.ts) |
 | `scripts/build.ts` | Cross-compiles CLI binaries for all 8 platform targets |
 | `scripts/sign-macos.ts` | Signs and notarizes macOS binaries (keychain, codesign, notarytool) |

scripts/lib/release-notes.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { getStableReleaseCreateArgs } from "./release-notes.ts";
+
+describe("getStableReleaseCreateArgs", () => {
+ let tempDir: string;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "release-notes-"));
+ });
+
+ afterEach(async () => {
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ test("uses plain generated notes when no intro file exists", async () => {
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+
+ test("prepends version-specific notes when the intro file exists", async () => {
+ const notesPath = join(tempDir, "v1.0.0.md");
+ await Bun.write(notesPath, "Intro line\n\n- Highlight");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: [
+ "gh",
+ "release",
+ "create",
+ "v1.0.0",
+ "--generate-notes",
+ "--notes",
+ "Intro line\n\n- Highlight",
+ ],
+ notesPath,
+ });
+ });
+
+ test("ignores empty intro files", async () => {
+ await Bun.write(join(tempDir, "v1.0.0.md"), "\n \n");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+});

scripts/lib/release-notes.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+
+const DEFAULT_STABLE_RELEASE_NOTES_DIR = join(import.meta.dir, "../../.github/release-notes");
+
+export type StableReleaseCreateArgs = {
+ args: string[];
+ notesPath?: string;
+};
+
+export async function getStableReleaseCreateArgs(
+ version: string,
+ notesDir = DEFAULT_STABLE_RELEASE_NOTES_DIR,
+): Promise<StableReleaseCreateArgs> {
+ const tagName = `v${version}`;
+ const args = ["gh", "release", "create", tagName, "--generate-notes"];
+ const notesPath = join(notesDir, `v${version}.md`);
+
+ if (!(await Bun.file(notesPath).exists())) {
+ return { args };
+ }
+
+ const notes = (await Bun.file(notesPath).text()).trim();
+ if (!notes) {
+ return { args };
+ }
+
+ return { args: [...args, "--notes", notes], notesPath };
+}

scripts/releaser.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { type Target, targets, SCOPE, PKG_PREFIX } from "./lib/targets.ts";
 import { run, isPublished, publish } from "./lib/npm.ts";
+import { getStableReleaseCreateArgs } from "./lib/release-notes.ts";
 
 const DIST_DIR = join(import.meta.dir, "../dist/platform-packages");
 const ARTIFACTS_DIR = process.env.ARTIFACTS_DIR ?? join(import.meta.dir, "../dist/artifacts");
@@ -136,7 +137,11 @@ if (!tag && !dryRun) {
  console.log(`GitHub Release for ${tagName} already exists, skipping.`);
  } else {
  console.log(`Creating GitHub Release for ${tagName}...`);
- await run(["gh", "release", "create", tagName, "--generate-notes"]);
+ const { args: releaseArgs, notesPath } = await getStableReleaseCreateArgs(version);
+ if (notesPath) {
+ console.log(`Prepending release intro from ${notesPath}...`);
+ }
+ await run(releaseArgs);
  }
 }
 

.changeset/clerk-1-0-0.md

@@ -0,0 +1,7 @@
+---
+"clerk": major
+---
+
+Release Clerk CLI 1.0 as the first stable `1.x` line.
+
+This milestone rolls up the recent improvements to bootstrap flows, authentication and keyless claiming, bundled agent skills, PATH-aware updates, interactive prompts, and docs into a stable baseline for the standalone `clerk` CLI.

.github/release-notes/v1.0.0.md

@@ -0,0 +1,27 @@
+# Clerk CLI 1.0
+
+Clerk CLI `1.0.0` is the first stable `1.x` release of the standalone `clerk` command line tool.
+
+This release marks the CLI as a stable, supported interface for working with Clerk from the terminal: bootstrapping new projects, authenticating, linking apps, pulling environment variables, inspecting and updating instance configuration, making direct API requests, running integration health checks, switching environments, opening dashboard resources, installing the bundled Clerk agent skill, and updating the CLI itself.
+
+Core workflows available in Clerk CLI `1.0.0` include:
+
+- `clerk init` to bootstrap Clerk into supported projects and starters
+- `clerk auth`, `clerk whoami`, `clerk link`, and `clerk unlink` for account and project association
+- `clerk env pull` for pulling Clerk environment variables into local env files
+- `clerk config pull`, `schema`, `patch`, and `put` for instance configuration management
+- `clerk api` and `clerk apps` for direct platform access from the terminal
+- `clerk doctor` for integration diagnostics and guided fixes
+- `clerk open`, `clerk switch-env`, `clerk completion`, `clerk skill install`, and `clerk update` for day-to-day developer workflows
+
+Install Clerk CLI:
+
+```sh
+# Homebrew (macOS / Linux)
+brew install clerk/stable/clerk
+
+# npm
+npm install -g clerk
+```
+
+See the autogenerated notes below for the full PR-by-PR changelog included in this `1.0.0` release.

README.md

@@ -224,7 +224,3 @@ clerk update
  $ clerk update --yes Update without confirmation prompt
  $ clerk update --all Update every clerk install on PATH
 ```
-
-## Open Questions
-
-- How do we keep types in sync with PLAPI?

docs/releasing.md

@@ -95,6 +95,8 @@ This launches an interactive prompt that asks which packages changed and whether
 
 On every push to `main`, the `changesets/action@v1` GitHub Action either creates a new "Version Packages" PR or updates an existing one. That PR aggregates all pending changesets, bumps versions, and updates changelogs. Merging it triggers a stable release (detected by `scripts/check-release.ts`).
 
+Changeset summaries drive the package changelog and the contents of the generated "Version Packages" PR. They do **not** control the GitHub Release body for stable releases; that comes from GitHub's autogenerated release notes, optionally prepended with a checked-in intro file at `.github/release-notes/vX.Y.Z.md`.
+
 Configuration:
 
 - `.changeset/config.json` -- Changesets configuration (access, snapshot template, ignored packages)
@@ -166,7 +168,7 @@ Runs the releaser script (`scripts/releaser/index.ts`) via `bun run release` (st
  - Copies the compiled binary from the build artifacts
 3. Publishes each platform package with `--access public` (authentication and provenance use npm OIDC trusted publishing -- no `NPM_TOKEN` secret needed, just `id-token: write` permission on a GitHub-hosted runner)
 4. Temporarily mutates the wrapper `package.json` to add `optionalDependencies` and remove `private: true`, publishes it, then restores the original file
-5. For stable releases, creates a Git tag and GitHub Release via the GitHub API
+5. For stable releases, creates a Git tag and GitHub Release via the GitHub API. If `.github/release-notes/vX.Y.Z.md` exists for that version, its contents are prepended ahead of GitHub's autogenerated notes.
 
 The releaser accepts these flags:
 
@@ -211,6 +213,7 @@ Install: `brew install clerk/stable/clerk`
 | `packages/cli-core/src/globals.d.ts` | TypeScript declaration for the `CLI_VERSION` compile-time define |
 | `install.sh` | Shell install script — downloads binary from GitHub Releases |
 | `scripts/releaser/index.ts` | Generates platform packages and publishes everything to npm |
+| `.github/release-notes/vX.Y.Z.md` | Optional version-specific intro prepended to stable GitHub Release notes |
 | `scripts/releaser/targets.ts` | Target definitions (used by both releaser and build.ts) |
 | `scripts/build.ts` | Cross-compiles CLI binaries for all 8 platform targets |
 | `scripts/sign-macos.ts` | Signs and notarizes macOS binaries (keychain, codesign, notarytool) |

scripts/lib/release-notes.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { getStableReleaseCreateArgs } from "./release-notes.ts";
+
+describe("getStableReleaseCreateArgs", () => {
+ let tempDir: string;
+
+ beforeEach(async () => {
+ tempDir = await mkdtemp(join(tmpdir(), "release-notes-"));
+ });
+
+ afterEach(async () => {
+ await rm(tempDir, { recursive: true, force: true });
+ });
+
+ test("uses plain generated notes when no intro file exists", async () => {
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+
+ test("prepends version-specific notes when the intro file exists", async () => {
+ const notesPath = join(tempDir, "v1.0.0.md");
+ await Bun.write(notesPath, "Intro line\n\n- Highlight");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: [
+ "gh",
+ "release",
+ "create",
+ "v1.0.0",
+ "--generate-notes",
+ "--notes",
+ "Intro line\n\n- Highlight",
+ ],
+ notesPath,
+ });
+ });
+
+ test("ignores empty intro files", async () => {
+ await Bun.write(join(tempDir, "v1.0.0.md"), "\n \n");
+
+ expect(await getStableReleaseCreateArgs("1.0.0", tempDir)).toEqual({
+ args: ["gh", "release", "create", "v1.0.0", "--generate-notes"],
+ });
+ });
+});

scripts/lib/release-notes.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+
+const DEFAULT_STABLE_RELEASE_NOTES_DIR = join(import.meta.dir, "../../.github/release-notes");
+
+export type StableReleaseCreateArgs = {
+ args: string[];
+ notesPath?: string;
+};
+
+export async function getStableReleaseCreateArgs(
+ version: string,
+ notesDir = DEFAULT_STABLE_RELEASE_NOTES_DIR,
+): Promise<StableReleaseCreateArgs> {
+ const tagName = `v${version}`;
+ const args = ["gh", "release", "create", tagName, "--generate-notes"];
+ const notesPath = join(notesDir, `v${version}.md`);
+
+ if (!(await Bun.file(notesPath).exists())) {
+ return { args };
+ }
+
+ const notes = (await Bun.file(notesPath).text()).trim();
+ if (!notes) {
+ return { args };
+ }
+
+ return { args: [...args, "--notes", notes], notesPath };
+}

scripts/releaser.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { type Target, targets, SCOPE, PKG_PREFIX } from "./lib/targets.ts";
 import { run, isPublished, publish } from "./lib/npm.ts";
+import { getStableReleaseCreateArgs } from "./lib/release-notes.ts";
 
 const DIST_DIR = join(import.meta.dir, "../dist/platform-packages");
 const ARTIFACTS_DIR = process.env.ARTIFACTS_DIR ?? join(import.meta.dir, "../dist/artifacts");
@@ -136,7 +137,11 @@ if (!tag && !dryRun) {
  console.log(`GitHub Release for ${tagName} already exists, skipping.`);
  } else {
  console.log(`Creating GitHub Release for ${tagName}...`);
- await run(["gh", "release", "create", tagName, "--generate-notes"]);
+ const { args: releaseArgs, notesPath } = await getStableReleaseCreateArgs(version);
+ if (notesPath) {
+ console.log(`Prepending release intro from ${notesPath}...`);
+ }
+ await run(releaseArgs);
  }
 }