@kitschpatrol/chagent 0.3.0 → 0.4.0

package/dist/bin/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { C as version, S as maxTimeoutMinutes, b as defaultModels, i as generateChangelog, l as agentNames, n as previewChangelog, r as reviewChangelog, s as writeChangelog, t as assertReviewTerminal, u as efforts, x as defaults, y as setLogger } from "../review-ClBbl31P.js";
-import { n as assertAmendable, t as amendRelease } from "../lib-advgvAk1.js";
+import { C as maxTimeoutMinutes, S as defaults, b as setLogger, d as rootChangelogs, i as generateChangelog, l as agentNames, n as previewChangelog, r as reviewChangelog, s as writeChangelog, t as assertReviewTerminal, u as efforts, w as version, x as defaultModels } from "../review-DftIAoEl.js";
+import { n as assertAmendable, t as amendRelease } from "../lib-Byxdn2st.js";
 import { t as createProgressLine } from "../progress-DQtRnH1N.js";
 import { createLogger } from "lognow";
 import path from "node:path";
@@ -109,6 +109,16 @@ try {
 		default: false,
 		description: "Amend a verified unpublished release commit and matching local tags",
 		type: "boolean"
+	}).option("root-changelog", {
+		choices: rootChangelogs,
+		defaultDescription: defaults.rootChangelog,
+		description: "Monorepo root changelog: a summary of package releases, the root package alone, or none",
+		type: "string"
+	}).option("skip-package", {
+		array: true,
+		defaultDescription: "none",
+		description: "Workspace package directory glob to leave without a changelog; repeatable",
+		type: "string"
 	}).option("github", {
 		defaultDescription: String(defaults.github),
 		description: "Enrich Git evidence using gh when available; disable with --no-github",
@@ -148,7 +158,9 @@ try {
 				reporter.report(message);
 			},
 			rebuild: args.rebuild,
+			rootChangelog: args.rootChangelog,
 			signal: controller.signal,
+			skipPackage: args.skipPackage,
 			timeout: args.timeout
 		}));
 		try {

package/dist/lib/bumpp.d.ts

@@ -1,4 +1,4 @@
-import { u as GenerateOptions } from "../types-COQP1I5w.js";
+import { u as GenerateOptions } from "../types-B6FOOkTQ.js";
 import { VersionBumpOptions } from "bumpp";
 type ExecuteHook = Exclude<NonNullable<VersionBumpOptions['execute']>, string>;
 export type BumppHookOptions = Omit<GenerateOptions, 'cwd' | 'release'> & {

package/dist/lib/bumpp.js

@@ -1,4 +1,4 @@
-import { g as git, i as generateChangelog, m as localDate, r as reviewChangelog, s as writeChangelog, t as assertReviewTerminal } from "../review-ClBbl31P.js";
+import { _ as git, h as localDate, i as generateChangelog, r as reviewChangelog, s as writeChangelog, t as assertReviewTerminal } from "../review-DftIAoEl.js";
 import { t as createProgressLine } from "../progress-DQtRnH1N.js";
 
 // src/lib/bumpp.ts

package/dist/lib/index.d.ts

@@ -1,4 +1,4 @@
-import { _ as Config, a as ChangeSet, c as Evidence, d as GenerationRequest, f as GenerationResponse, g as RunSettings, h as ReleaseSummary, i as Change, l as FileEdit, m as ReleaseRequest, n as AgentName, o as ChangelogPlan, p as ReleaseContext, r as Category, s as Effort, t as AgentAdapter, u as GenerateOptions, v as defineConfig, y as loadConfig } from "../types-COQP1I5w.js";
+import { _ as RunSettings, a as ChangeSet, b as loadConfig, c as Evidence, d as GenerationRequest, f as GenerationResponse, g as RootChangelog, h as ReleaseSummary, i as Change, l as FileEdit, m as ReleaseRequest, n as AgentName, o as ChangelogPlan, p as ReleaseContext, r as Category, s as Effort, t as AgentAdapter, u as GenerateOptions, v as Config, y as defineConfig } from "../types-B6FOOkTQ.js";
 import { ILogBasic, ILogLayer } from "lognow";
 /** Create an adapter for an installed CLI using its existing authentication. */
 export declare function createAgent(name: AgentName): AgentAdapter;
@@ -28,4 +28,4 @@ export declare function reviewChangelog(plan: ChangelogPlan, options?: {
  * writes.
  */
 export declare function writeChangelog(plan: ChangelogPlan): Promise<string[]>;
-export { type AgentAdapter, type AgentName, type Category, type Change, type ChangeSet, type ChangelogPlan, type Config, type Effort, type Evidence, type FileEdit, type GenerateOptions, type GenerationRequest, type GenerationResponse, type ReleaseContext, type ReleaseRequest, type ReleaseSummary, type RunSettings, defineConfig, loadConfig };
+export { type AgentAdapter, type AgentName, type Category, type Change, type ChangeSet, type ChangelogPlan, type Config, type Effort, type Evidence, type FileEdit, type GenerateOptions, type GenerationRequest, type GenerationResponse, type ReleaseContext, type ReleaseRequest, type ReleaseSummary, type RootChangelog, type RunSettings, defineConfig, loadConfig };

package/dist/lib/index.js

@@ -1,4 +1,4 @@
-import { a as defineConfig, c as createAgent, i as generateChangelog, n as previewChangelog, o as loadConfig, r as reviewChangelog, s as writeChangelog, y as setLogger } from "../review-ClBbl31P.js";
-import { t as amendRelease } from "../lib-advgvAk1.js";
+import { a as defineConfig, b as setLogger, c as createAgent, i as generateChangelog, n as previewChangelog, o as loadConfig, r as reviewChangelog, s as writeChangelog } from "../review-DftIAoEl.js";
+import { t as amendRelease } from "../lib-Byxdn2st.js";
 
 export { amendRelease, createAgent, defineConfig, generateChangelog, loadConfig, previewChangelog, reviewChangelog, setLogger, writeChangelog };

package/dist/{lib-advgvAk1.js → lib-Byxdn2st.js}

@@ -1,4 +1,4 @@
-import { _ as isAncestor, d as LOCKFILE_PATH, f as inspectRepository, g as git, h as manifestAt, p as isVersionOnlyChange, s as writeChangelog, v as runCommand } from "./review-ClBbl31P.js";
+import { _ as git, f as LOCKFILE_PATH, g as manifestAt, m as isVersionOnlyChange, p as inspectRepository, s as writeChangelog, v as isAncestor, y as runCommand } from "./review-DftIAoEl.js";
 import path from "node:path";
 import { realpath } from "node:fs/promises";
 

package/dist/{review-ClBbl31P.js → review-DftIAoEl.js}

@@ -15,7 +15,7 @@ import { isCancel, select } from "@clack/prompts";
 
 // package.json
 var name = "@kitschpatrol/chagent";
-var version = "0.3.0";
+var version = "0.4.0";
 var engines = { "node": "^24.16.0 || >=26.3.0" };
 
 // src/lib/defaults.ts
@@ -25,6 +25,7 @@ const defaults = {
 	effort: "xhigh",
 	github: true,
 	maxInputChars: 8e4,
+	rootChangelog: "summary",
 	timeout: 20
 };
 const defaultModels = {
@@ -486,21 +487,15 @@ function pnpmWorkspaceGlobs(text) {
 	if (!workspace.success) throw new Error(`Invalid pnpm-workspace.yaml:\n${z.prettifyError(workspace.error)}`, { cause: workspace.error });
 	return workspace.data?.packages;
 }
-async function workspacePackages(root, manifest, config) {
-	let patterns = Array.isArray(manifest?.workspaces) ? manifest.workspaces : manifest?.workspaces?.packages ?? [];
-	const workspaceText = await readOptional(path.join(root, "pnpm-workspace.yaml"));
-	if (workspaceText !== void 0) patterns = pnpmWorkspaceGlobs(workspaceText) ?? patterns;
-	patterns = config.packages ?? patterns;
+/** Find directories matching globs, as POSIX paths relative to the root. */
+async function matchDirectories(root, patterns, exclude = []) {
 	const directories = [];
-	const positive = patterns.filter((pattern) => !pattern.startsWith("!"));
-	const negative = patterns.filter((pattern) => pattern.startsWith("!")).map((pattern) => pattern.slice(1));
-	const matches = glob(positive, {
+	const matches = glob(patterns, {
 		cwd: root,
 		exclude: [
 			"**/node_modules/**",
 			"**/.git/**",
-			...negative,
-			...config.exclude ?? []
+			...exclude
 		],
 		withFileTypes: true
 	});
@@ -508,6 +503,27 @@ async function workspacePackages(root, manifest, config) {
 		if (!entry.isDirectory()) continue;
 		directories.push(path.relative(root, path.join(entry.parentPath, entry.name)).split(path.sep).join("/"));
 	}
+	return directories;
+}
+/** Mark the packages that remain boundaries but get no changelog. */
+async function markSkipped(root, packages, patterns) {
+	const skipped = /* @__PURE__ */ new Set();
+	for (const pattern of patterns) {
+		const matches = (await matchDirectories(root, [pattern])).filter((directory) => packages.some((pkg) => pkg.directory === directory));
+		if (matches.length === 0) throw new Error(`skipPackage pattern "${pattern}" matches no workspace package directory. Use a directory glob relative to the repository root, such as "packages/docs"; rootChangelog controls the root changelog.`);
+		for (const directory of matches) skipped.add(directory);
+	}
+	return packages.map((pkg) => skipped.has(pkg.directory) ? {
+		...pkg,
+		skipped: true
+	} : pkg);
+}
+async function workspacePackages(root, manifest, config) {
+	let patterns = Array.isArray(manifest?.workspaces) ? manifest.workspaces : manifest?.workspaces?.packages ?? [];
+	const workspaceText = await readOptional(path.join(root, "pnpm-workspace.yaml"));
+	if (workspaceText !== void 0) patterns = pnpmWorkspaceGlobs(workspaceText) ?? patterns;
+	patterns = config.packages ?? patterns;
+	const directories = await matchDirectories(root, patterns.filter((pattern) => !pattern.startsWith("!")), [...patterns.filter((pattern) => pattern.startsWith("!")).map((pattern) => pattern.slice(1)), ...config.exclude ?? []]);
 	const packages = [];
 	for (const directory of directories.toSorted()) {
 		if (!(await realpath(path.join(root, directory))).startsWith(root + path.sep)) throw new Error(`Workspace package escapes the repository: ${directory}`);
@@ -515,7 +531,11 @@ async function workspacePackages(root, manifest, config) {
 		if (text === void 0 && config.packages === void 0) continue;
 		packages.push(packageInfo(text === void 0 ? void 0 : parseManifest(text, `${directory}/package.json`), directory, path.posix.basename(directory)));
 	}
-	return packages;
+	return markSkipped(root, packages, config.skipPackage ?? []);
+}
+/** Select the workspace packages that get changelogs of their own. */
+function describedPackages(repository) {
+	return repository.packages.filter((pkg) => pkg.skipped !== true);
 }
 async function taggedReleases(repository, pkg, config) {
 	const candidates = [];
@@ -735,6 +755,11 @@ const efforts = [
 	"xhigh",
 	"max"
 ];
+const rootChangelogs = [
+	"summary",
+	"package",
+	"none"
+];
 
 // src/lib/agents.ts
 const CONTROL_CHARACTERS = /\p{Cc}/v;
@@ -1062,6 +1087,13 @@ const configSchema = z.strictObject({
 	model: z.string().min(1).optional(),
 	/** Workspace directory globs, overriding manifest workspace discovery. */
 	packages: z.array(z.string()).optional(),
+	/**
+	* What a monorepo's root changelog records: a summary of package releases,
+	* the root package's own changes, or nothing.
+	*/
+	rootChangelog: z.enum(rootChangelogs).optional(),
+	/** Workspace package directory globs that get no changelog of their own. */
+	skipPackage: z.array(z.string()).optional(),
 	/** Templates containing {version} and optionally {name}. */
 	tagPatterns: z.array(z.string().includes("{version}")).optional(),
 	/** Minutes each agent session may run. */
@@ -1073,6 +1105,7 @@ const resolvedConfigSchema = configSchema.required({
 	effort: true,
 	github: true,
 	maxInputChars: true,
+	rootChangelog: true,
 	timeout: true
 }).transform(({ timeout, ...config }) => ({
 	...config,
@@ -1331,8 +1364,11 @@ function ignored(file, packages) {
 	const relative = owner === void 0 ? file : file.slice(owner.directory.length + 1);
 	return LOCKFILE_PATH.test(file) || GENERATED_ANYWHERE.test(file) || GENERATED_DIRECTORY.test(relative);
 }
-async function scopes(repository, pkg, ref) {
-	if (pkg.directory === ".") return ["."];
+/**
+* A package's directory and, transitively, those of the workspace packages it
+* depends on at a ref.
+*/
+async function packageScope(repository, pkg, ref) {
 	const directories = /* @__PURE__ */ new Set([pkg.directory]);
 	const visit = async (current) => {
 		const manifest = await manifestAt(repository.root, current.directory, ref);
@@ -1402,7 +1438,7 @@ async function commitsInRange(root, range, paths) {
 /** Collect source changes, excluding generated notes and release-only commits. */
 async function collectEvidence(repository, pkg, release, excludeDirectories = []) {
 	const { packages, root } = repository;
-	const paths = [...(await scopes(repository, pkg, release.ref)).map((directory) => `:(literal)${directory}`), ...excludeDirectories.map((directory) => `:(exclude,literal)${directory}`)];
+	const paths = [...(pkg.directory === "." ? ["."] : await packageScope(repository, pkg, release.ref)).map((directory) => `:(literal)${directory}`), ...excludeDirectories.map((directory) => `:(exclude,literal)${directory}`)];
 	const range = release.previousRef === void 0 ? release.ref : `${release.previousRef}..${release.ref}`;
 	const from = release.previousRef ?? await git(root, [
 		"hash-object",
@@ -1642,7 +1678,7 @@ function researchEvidence(evidence, limit) {
 async function prepareRelease(context, pkg, release, existingEntries, mode, from, onlyRepositoryFiles = false) {
 	const { options, repository } = context;
 	options.signal?.throwIfAborted();
-	const excludeDirectories = onlyRepositoryFiles ? repository.packages.map((item) => item.directory) : [];
+	const excludeDirectories = await excludedPackages(context, pkg, release.ref, onlyRepositoryFiles);
 	return {
 		evidence: await collectEvidence(repository, pkg, from === void 0 ? release : {
 			...release,
@@ -1659,10 +1695,24 @@ async function prepareRelease(context, pkg, release, existingEntries, mode, from
 			from: from ?? release.previousRef,
 			to: release.ref
 		},
-		scope: pkg.directory === "." && repository.packages.length > 0 ? "repository" : "package",
+		scope: pkg.directory === "." && repository.packages.length > 0 && options.rootChangelog === "summary" ? "repository" : "package",
 		version: release.version
 	};
 }
+/**
+* Select the package directories a release leaves out: every package when
+* describing repository files alone, skipped packages in a whole-repository
+* summary, or, when the root is a package itself, those it does not depend on.
+*/
+async function excludedPackages(context, pkg, ref, onlyRepositoryFiles) {
+	const { options, repository } = context;
+	const directories = repository.packages.map((item) => item.directory);
+	if (onlyRepositoryFiles || directories.length === 0) return directories;
+	if (pkg.directory !== ".") return [];
+	if (options.rootChangelog === "summary") return repository.packages.filter((item) => item.skipped === true).map((item) => item.directory);
+	const scope = new Set(await packageScope(repository, pkg, ref));
+	return directories.filter((directory) => !scope.has(directory));
+}
 function cacheKey(context, release) {
 	const { effort, maxInputChars, model } = context.options;
 	return JSON.stringify({
@@ -2076,7 +2126,7 @@ function aggregateShared(context, prepared, results, exception, quiet) {
 	const rootEdit = plan.files.find((file) => path.dirname(file.path) === repository.root);
 	if (rootEdit === void 0) return;
 	const additions = prepared.summaries.map((summary) => ({
-		changes: aggregateChanges(repository, plan.releases.filter((item) => item.version === summary.version && !quiet.has(`${item.changelogPath}@${item.version}`))),
+		changes: aggregateChanges(repository, plan.releases.filter((item) => item.version === summary.version && item.ref === summary.ref && !quiet.has(`${item.changelogPath}@${item.version}`))),
 		existingBody: parseChangelog(rootEdit.after).sections.find((section) => section.version === summary.version)?.body,
 		release: prepared.releases.find((item) => item.version === summary.version)
 	}));
@@ -2089,11 +2139,11 @@ async function generateWorkspace(context) {
 	const shared = rootReleases.some((release) => release.version !== "Unreleased");
 	const rootFile = await findChangelog(repository.root);
 	const rootContent = options.rebuild ? void 0 : rootFile.content;
-	const rootMissing = shared ? new Set(missingReleases(rootReleases, rootContent).map((release) => release.version)) : void 0;
-	const needsPackageHistory = rootMissing === void 0 || rootMissing.values().some((version) => version !== "Unreleased");
-	const recordedAtRoot = (summary) => rootMissing === void 0 ? rootContent !== void 0 && missingPackageSummaries([summary], rootContent).length === 0 : !rootMissing.has(summary.version);
+	const rootMissing = shared ? missingReleases(rootReleases, rootContent) : void 0;
+	const needsPackageHistory = rootMissing === void 0 || rootMissing.some((release) => release.version !== "Unreleased");
+	const recordedAtRoot = (summary) => rootMissing === void 0 ? rootContent !== void 0 && missingPackageSummaries([summary], rootContent).length === 0 : rootMissing.every((release) => release.version !== summary.version || release.ref !== summary.ref);
 	const packages = [];
-	for (const pkg of repository.packages) packages.push(await preparePackage(context, pkg, needsPackageHistory, recordedAtRoot));
+	for (const pkg of describedPackages(repository)) packages.push(await preparePackage(context, pkg, needsPackageHistory, recordedAtRoot));
 	const root = shared ? await preparePackage(context, repository.rootPackage) : void 0;
 	const independent = shared ? void 0 : await prepareIndependent(context, packages.flatMap((pkg) => pkg.summaries));
 	const requests = [...packages, ...root === void 0 ? [] : [root]].flatMap((pkg) => pkg.work.map((item) => item.request));
@@ -2127,6 +2177,7 @@ async function generateChangelog(options = {}) {
 	log.debug(`Resolved options: ${JSON.stringify(config)}`);
 	const repository = await inspectRepository(root, config);
 	log.debug(`Repository ${root} at ${repository.head}: ${repository.tags.length} reachable tags, ${repository.packages.length} workspace packages.`);
+	if (config.rootChangelog === "none" && describedPackages(repository).length === 0) throw new Error("The root changelog is set to \"none\", but no workspace packages remain to describe, so there is no changelog to generate. Choose another root changelog mode, or configure packages that are not skipped.");
 	const agent = typeof selected === "object" ? selected : createAgent(config.agent);
 	const plan = {
 		checkpoints: [],
@@ -2154,14 +2205,20 @@ async function generateChangelog(options = {}) {
 		plan,
 		repository
 	};
-	if (repository.packages.length === 0) {
-		const prepared = await preparePackage(context, repository.rootPackage);
-		const results = await generateReleases(context, prepared.work.map((item) => item.request));
-		plan.releases.push(...renderPackage(context, prepared, results));
-	} else await generateWorkspace(context);
+	if (repository.packages.length > 0 && config.rootChangelog === "summary") await generateWorkspace(context);
+	else await generatePackages(context);
 	if (rebuild) keepEmptyRebuilds(plan);
 	return plan;
 }
+/** Generate each changelog on its own, with no root summary. */
+async function generatePackages(context) {
+	const { options, plan, repository } = context;
+	const packages = options.rootChangelog === "none" ? describedPackages(repository) : [repository.rootPackage, ...describedPackages(repository)];
+	const prepared = [];
+	for (const pkg of packages) prepared.push(await preparePackage(context, pkg));
+	const results = await generateReleases(context, prepared.flatMap((item) => item.work.map((work) => work.request)));
+	for (const item of prepared) plan.releases.push(...renderPackage(context, item, results));
+}
 /** A rebuild that finds nothing to record must not erase an existing changelog. */
 function keepEmptyRebuilds(plan) {
 	plan.files = plan.files.filter((edit) => {
@@ -2322,4 +2379,4 @@ async function reviewChangelog(plan, options = {}) {
 	}
 }
 
-export { version as C, maxTimeoutMinutes as S, isAncestor as _, defineConfig as a, defaultModels as b, createAgent as c, LOCKFILE_PATH as d, inspectRepository as f, git as g, manifestAt as h, generateChangelog as i, agentNames as l, localDate as m, previewChangelog as n, loadConfig as o, isVersionOnlyChange as p, reviewChangelog as r, writeChangelog as s, assertReviewTerminal as t, efforts as u, runCommand as v, defaults as x, setLogger as y };
+export { maxTimeoutMinutes as C, defaults as S, git as _, defineConfig as a, setLogger as b, createAgent as c, rootChangelogs as d, LOCKFILE_PATH as f, manifestAt as g, localDate as h, generateChangelog as i, agentNames as l, isVersionOnlyChange as m, previewChangelog as n, loadConfig as o, inspectRepository as p, reviewChangelog as r, writeChangelog as s, assertReviewTerminal as t, efforts as u, isAncestor as v, version as w, defaultModels as x, runCommand as y };

package/dist/{types-COQP1I5w.d.ts → types-B6FOOkTQ.d.ts}

@@ -17,6 +17,12 @@ declare const configSchema: z.ZodObject<{
   maxInputChars: z.ZodOptional<z.ZodNumber>;
   model: z.ZodOptional<z.ZodString>;
   packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  rootChangelog: z.ZodOptional<z.ZodEnum<{
+    summary: "summary";
+    package: "package";
+    none: "none";
+  }>>;
+  skipPackage: z.ZodOptional<z.ZodArray<z.ZodString>>;
   tagPatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
   timeout: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
@@ -29,8 +35,10 @@ declare const categories: readonly ["Added", "Changed", "Deprecated", "Removed",
 type Category = (typeof categories)[number];
 declare const agentNames: readonly ["codex", "claude"];
 declare const efforts: readonly ["low", "medium", "high", "xhigh", "max"];
+declare const rootChangelogs: readonly ["summary", "package", "none"];
 type AgentName = (typeof agentNames)[number];
 type Effort = (typeof efforts)[number];
+type RootChangelog = (typeof rootChangelogs)[number];
 type Change = {
   breaking: boolean;
   category: Category;
@@ -159,4 +167,4 @@ type ChangelogPlan = {
   releases: ReleaseSummary[];
   root: string;
 };
-export { Config as _, ChangeSet as a, Evidence as c, GenerationRequest as d, GenerationResponse as f, RunSettings as g, ReleaseSummary as h, Change as i, FileEdit as l, ReleaseRequest as m, AgentName as n, ChangelogPlan as o, ReleaseContext as p, Category as r, Effort as s, AgentAdapter as t, GenerateOptions as u, defineConfig as v, loadConfig as y };
+export { RunSettings as _, ChangeSet as a, loadConfig as b, Evidence as c, GenerationRequest as d, GenerationResponse as f, RootChangelog as g, ReleaseSummary as h, Change as i, FileEdit as l, ReleaseRequest as m, AgentName as n, ChangelogPlan as o, ReleaseContext as p, Category as r, Effort as s, AgentAdapter as t, GenerateOptions as u, Config as v, defineConfig as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitschpatrol/chagent",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Changelog agent. CLI tool and TypeScript library to generate and update changelogs with a little help from your LLMs.",
   "keywords": [
     "changelog",

package/readme.md

@@ -132,24 +132,26 @@ Usage:
 chagent
 ```
 
-| Option                  | Description                                                           | Type                                          | Default                                       |
-| ----------------------- | --------------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------- |
-| `--cwd`                 | Repository directory                                                  | `string`                                      | current directory                             |
-| `--agent`               | Installed agent CLI                                                   | `"codex"` `"claude"`                          | `codex`                                       |
-| `--model`               | Agent model                                                           | `string`                                      | gpt-6.1-sol (Codex); claude-opus-5-5 (Claude) |
-| `--effort`              | Reasoning effort                                                      | `"low"` `"medium"` `"high"` `"xhigh"` `"max"` | `xhigh`                                       |
-| `--interactive`<br>`-i` | Review a diff and optionally edit before writing                      | `boolean`                                     | `false`                                       |
-| `--editor`              | Editor command for interactive review; configure GUI editors to wait  | `string`                                      | git var GIT_EDITOR                            |
-| `--dry-run`             | Print a diff without applying changes                                 | `boolean`                                     | `false`                                       |
-| `--rebuild`             | Reconstruct all history, replacing existing release text              | `boolean`                                     | `false`                                       |
-| `--amend`               | Amend a verified unpublished release commit and matching local tags   | `boolean`                                     | `false`                                       |
-| `--github`              | Enrich Git evidence using gh when available; disable with --no-github | `boolean`                                     | `true`                                        |
-| `--cache`               | Cache drafts and incremental state; disable with --no-cache           | `boolean`                                     | `true`                                        |
-| `--config`              | Configuration file path                                               | `string`                                      | auto-detected from repository root            |
-| `--timeout`             | Agent timeout in minutes                                              | `number`                                      | `20`                                          |
-| `--verbose`             | Log commands, cache decisions, and session details to stderr          | `boolean`                                     | `false`                                       |
-| `--help`<br>`-h`        | Show help                                                             | `boolean`                                     |                                               |
-| `--version`<br>`-v`     | Show version number                                                   | `boolean`                                     |                                               |
+| Option                  | Description                                                                             | Type                                          | Default                                       |
+| ----------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------- |
+| `--cwd`                 | Repository directory                                                                    | `string`                                      | current directory                             |
+| `--agent`               | Installed agent CLI                                                                     | `"codex"` `"claude"`                          | `codex`                                       |
+| `--model`               | Agent model                                                                             | `string`                                      | gpt-6.1-sol (Codex); claude-opus-5-5 (Claude) |
+| `--effort`              | Reasoning effort                                                                        | `"low"` `"medium"` `"high"` `"xhigh"` `"max"` | `xhigh`                                       |
+| `--interactive`<br>`-i` | Review a diff and optionally edit before writing                                        | `boolean`                                     | `false`                                       |
+| `--editor`              | Editor command for interactive review; configure GUI editors to wait                    | `string`                                      | git var GIT_EDITOR                            |
+| `--dry-run`             | Print a diff without applying changes                                                   | `boolean`                                     | `false`                                       |
+| `--rebuild`             | Reconstruct all history, replacing existing release text                                | `boolean`                                     | `false`                                       |
+| `--amend`               | Amend a verified unpublished release commit and matching local tags                     | `boolean`                                     | `false`                                       |
+| `--root-changelog`      | Monorepo root changelog: a summary of package releases, the root package alone, or none | `"summary"` `"package"` `"none"`              | `summary`                                     |
+| `--skip-package`        | Workspace package directory glob to leave without a changelog; repeatable               | `array`                                       | `none`                                        |
+| `--github`              | Enrich Git evidence using gh when available; disable with --no-github                   | `boolean`                                     | `true`                                        |
+| `--cache`               | Cache drafts and incremental state; disable with --no-cache                             | `boolean`                                     | `true`                                        |
+| `--config`              | Configuration file path                                                                 | `string`                                      | auto-detected from repository root            |
+| `--timeout`             | Agent timeout in minutes                                                                | `number`                                      | `20`                                          |
+| `--verbose`             | Log commands, cache decisions, and session details to stderr                            | `boolean`                                     | `false`                                       |
+| `--help`<br>`-h`        | Show help                                                                               | `boolean`                                     |                                               |
+| `--version`<br>`-v`     | Show version number                                                                     | `boolean`                                     |                                               |
 
 <!-- /cli-help -->
 
@@ -246,6 +248,10 @@ For an existing post-bump workflow, `chagent --amend` explicitly amends an unpub
 
 Workspace declarations in `pnpm-workspace.yaml` or `package.json` determine the packages to process. Each current workspace package gets its own changelog. The root contains repository highlights and links to package releases.
 
+Use the `rootChangelog` option or `--root-changelog` flag to choose what the root changelog records. The default, `summary`, works as described above. `package` treats the root as a package of its own, for repositories whose main package lives at the root: its changelog describes the root's files and the workspace packages it depends on in full detail, without changes from other packages or links to their releases. `none` writes only the package changelogs. After changing the mode of an existing root changelog, run with `--rebuild` to reconstruct its history in the new form.
+
+Use `skipPackage` directory globs, or repeat `--skip-package`, to leave workspace packages such as documentation sites or examples without changelogs. A skipped package is left out of the root changelog, and its changes are not counted among the root's own, but packages that depend on it still include its relevant changes. To count a directory's changes as the root's instead, `exclude` it from workspace discovery. A pattern that matches no workspace package is an error.
+
 For other monorepo layouts, configure `packages` directory globs. These directories do not need npm manifests; their Git tags identify releases, using the directory basename as the package name.
 
 Shared-version repositories use repository versions at the root. Independently versioned repositories use package-qualified headings such as `@example/package@1.2.0`. Repository infrastructure changes appear in the root's `Unreleased` section. Explicit workspace dependencies contribute relevant source context to dependent packages. Dependency and tooling maintenance belongs under `Maintenance`. `build`, `coverage`, and `dist` directories at the top of a package count as generated output and are excluded, so a package named `packages/build` is still treated as source.
@@ -266,6 +272,7 @@ export default defineConfig({
   github: true,
   maxInputChars: 80_000,
   model: 'gpt-6.1-sol',
+  rootChangelog: 'summary',
   timeout: 20,
 })
 ```
@@ -274,7 +281,7 @@ Importing `defineConfig` requires chagent in the repository's own dependencies.
 
 Also supported: `chagent.config.mjs`, `chagent.config.js`, `chagent.config.json`, or a `chagent` key in `package.json`. CLI flags override configured values. `--config` selects a specific file.
 
-Use `packages` and `exclude` directory globs to customize workspace discovery. Use `tagPatterns` to select unusual release tag conventions. Templates support `{name}` and `{version}`; defaults recognize `v1.2.3`, `1.2.3`, `@scope/package@1.2.3`, and `@scope/package/v1.2.3`.
+Use `packages` and `exclude` directory globs to customize workspace discovery, and `skipPackage` to leave discovered packages without changelogs. Use `tagPatterns` to select unusual release tag conventions. Templates support `{name}` and `{version}`; defaults recognize `v1.2.3`, `1.2.3`, `@scope/package@1.2.3`, and `@scope/package/v1.2.3`.
 
 ## Background