@savvy-web/changesets 0.4.2 → 0.5.0

package/cjs/index.d.cts

@@ -20,124 +20,311 @@ import { ModCompWithPackage } from '@changesets/types';
 import { NewChangesetWithCommit } from '@changesets/types';
 import type { Root } from 'mdast';
 import { Schema } from 'effect';
+import type { Table } from 'mdast';
 import { VersionType as VersionType_2 } from '@changesets/types';
 import { YieldableError } from 'effect/Cause';
 
 /**
- * Static class wrapper for category operations.
+ * Static class wrapper for section category operations.
  *
  * Provides methods for resolving conventional commit types to changelog
- * section categories and validating section headings.
+ * section categories, validating section headings, and accessing the
+ * canonical set of 13 section categories used throughout the pipeline.
  *
- * @example
+ * @remarks
+ * This class wraps the pure functions and constants from the internal
+ * `categories/` module. Each {@link SectionCategory} is defined by the
+ * {@link SectionCategorySchema} Effect Schema, which provides runtime
+ * validation at system boundaries. The class itself is stateless; all
+ * methods and properties are `static`.
+ *
+ * Categories control how changelog entries are grouped and ordered.
+ * Lower priority numbers appear first in the output. The 13 built-in
+ * categories cover all conventional commit types plus special cases
+ * like dependency updates and breaking changes.
+ *
+ * @example Looking up categories from commit metadata
  * ```typescript
  * import { Categories } from "\@savvy-web/changesets";
  * import type { SectionCategory } from "\@savvy-web/changesets";
  *
- * const cat: SectionCategory = Categories.fromCommitType("feat");
- * console.log(cat.heading); // "Features"
- * console.log(cat.priority); // 2
+ * // Resolve a conventional commit type to its category
+ * const feature: SectionCategory = Categories.fromCommitType("feat");
+ * // feature.heading === "Features"
+ * // feature.priority === 2
+ *
+ * // Breaking changes always win regardless of commit type
+ * const breaking: SectionCategory = Categories.fromCommitType("fix", undefined, true);
+ * // breaking.heading === "Breaking Changes"
+ * // breaking.priority === 1
+ *
+ * // The special scope "deps" on "chore" maps to Dependencies
+ * const deps: SectionCategory = Categories.fromCommitType("chore", "deps");
+ * // deps.heading === "Dependencies"
+ * ```
+ *
+ * @example Validating section headings
+ * ```typescript
+ * import { Categories } from "\@savvy-web/changesets";
+ *
+ * const headings: readonly string[] = Categories.allHeadings();
+ * // ["Breaking Changes", "Features", "Bug Fixes", ...]
+ *
+ * const valid: boolean = Categories.isValidHeading("Bug Fixes");
+ * // true
+ *
+ * const unknown: boolean = Categories.isValidHeading("Miscellaneous");
+ * // false
+ * ```
+ *
+ * @example Reverse-lookup from heading text
+ * ```typescript
+ * import { Categories } from "\@savvy-web/changesets";
+ * import type { SectionCategory } from "\@savvy-web/changesets";
  *
- * const isValid: boolean = Categories.isValidHeading("Bug Fixes");
- * console.log(isValid); // true
+ * const category: SectionCategory | undefined = Categories.fromHeading("Features");
+ * if (category) {
+ *   const commitTypes: readonly string[] = category.commitTypes;
+ *   // ["feat"]
+ * }
  * ```
  *
- * @see {@link SectionCategory} for the category shape
+ * @see {@link SectionCategory} for the category shape (heading, priority, commitTypes, description)
+ * @see {@link SectionCategorySchema} for the Effect Schema that validates category data
  *
  * @public
  */
 export declare class Categories {
     private constructor();
-    /** Breaking changes - backward-incompatible changes (priority 1) */
+    /**
+     * Breaking changes -- backward-incompatible changes (priority 1).
+     *
+     * @remarks
+     * Mapped from any commit type when the `breaking` flag is `true`.
+     * Always appears first in changelog output.
+     */
     static readonly BREAKING_CHANGES: SectionCategory;
-    /** Features - new functionality (priority 2) */
+    /**
+     * Features -- new functionality (priority 2).
+     *
+     * @remarks
+     * Mapped from the `feat` commit type.
+     */
     static readonly FEATURES: SectionCategory;
-    /** Bug Fixes - bug corrections (priority 3) */
+    /**
+     * Bug Fixes -- bug corrections (priority 3).
+     *
+     * @remarks
+     * Mapped from the `fix` commit type.
+     */
     static readonly BUG_FIXES: SectionCategory;
-    /** Performance - performance improvements (priority 4) */
+    /**
+     * Performance -- performance improvements (priority 4).
+     *
+     * @remarks
+     * Mapped from the `perf` commit type.
+     */
     static readonly PERFORMANCE: SectionCategory;
-    /** Documentation - documentation changes (priority 5) */
+    /**
+     * Documentation -- documentation changes (priority 5).
+     *
+     * @remarks
+     * Mapped from the `docs` commit type.
+     */
     static readonly DOCUMENTATION: SectionCategory;
-    /** Refactoring - code restructuring (priority 6) */
+    /**
+     * Refactoring -- code restructuring (priority 6).
+     *
+     * @remarks
+     * Mapped from the `refactor` commit type.
+     */
     static readonly REFACTORING: SectionCategory;
-    /** Tests - test additions or modifications (priority 7) */
+    /**
+     * Tests -- test additions or modifications (priority 7).
+     *
+     * @remarks
+     * Mapped from the `test` commit type.
+     */
     static readonly TESTS: SectionCategory;
-    /** Build System - build configuration changes (priority 8) */
+    /**
+     * Build System -- build configuration changes (priority 8).
+     *
+     * @remarks
+     * Mapped from the `build` commit type.
+     */
     static readonly BUILD_SYSTEM: SectionCategory;
-    /** CI - continuous integration changes (priority 9) */
+    /**
+     * CI -- continuous integration changes (priority 9).
+     *
+     * @remarks
+     * Mapped from the `ci` commit type.
+     */
     static readonly CI: SectionCategory;
-    /** Dependencies - dependency updates (priority 10) */
+    /**
+     * Dependencies -- dependency updates (priority 10).
+     *
+     * @remarks
+     * Mapped from `chore(deps)` and similar dependency-scoped commits.
+     */
     static readonly DEPENDENCIES: SectionCategory;
-    /** Maintenance - general maintenance (priority 11) */
+    /**
+     * Maintenance -- general maintenance (priority 11).
+     *
+     * @remarks
+     * Mapped from the `chore` commit type (without the `deps` scope).
+     */
     static readonly MAINTENANCE: SectionCategory;
-    /** Reverts - reverted changes (priority 12) */
+    /**
+     * Reverts -- reverted changes (priority 12).
+     *
+     * @remarks
+     * Mapped from the `revert` commit type.
+     */
     static readonly REVERTS: SectionCategory;
-    /** Other - uncategorized changes (priority 13) */
+    /**
+     * Other -- uncategorized changes (priority 13).
+     *
+     * @remarks
+     * Fallback category for unrecognized commit types. Always appears
+     * last in changelog output.
+     */
     static readonly OTHER: SectionCategory;
-    /** All categories ordered by priority (ascending). */
+    /**
+     * All 13 categories ordered by priority (ascending, 1-13).
+     *
+     * @remarks
+     * This array is frozen and sorted from highest priority (Breaking Changes)
+     * to lowest (Other). Useful for iterating over categories in display order.
+     */
     static readonly ALL: readonly SectionCategory[];
     /**
-     * Resolve a conventional commit type to its category.
+     * Resolve a conventional commit type to its section category.
      *
      * @remarks
-     * The breaking flag takes highest precedence, always returning the
-     * "Breaking Changes" category. The special scope `chore(deps)` maps
-     * to "Dependencies" rather than "Maintenance". Unknown types fall
-     * back to "Other".
+     * Resolution follows a precedence chain:
+     *
+     * 1. If `breaking` is `true`, always returns {@link Categories.BREAKING_CHANGES}
+     * 2. If `type` is `"chore"` and `scope` is `"deps"`, returns {@link Categories.DEPENDENCIES}
+     * 3. Otherwise, looks up `type` in the `commitTypes` arrays of all categories
+     * 4. Falls back to {@link Categories.OTHER} for unrecognized types
      *
-     * @param type - The commit type (e.g., "feat", "fix", "chore")
-     * @param scope - Optional scope (e.g., "deps" in `chore(deps):`)
-     * @param breaking - Whether the commit has a `!` suffix
-     * @returns The resolved section category
+     * @param type - The conventional commit type (e.g., `"feat"`, `"fix"`, `"chore"`)
+     * @param scope - Optional commit scope (e.g., `"deps"` from `chore(deps):`)
+     * @param breaking - Whether the commit includes a breaking change indicator (`!`)
+     * @returns The resolved {@link SectionCategory}
      */
     static fromCommitType(type: string, scope?: string, breaking?: boolean): SectionCategory;
     /**
      * Look up a category by its section heading text.
-     * Comparison is case-insensitive.
      *
-     * @param heading - The heading text (e.g., "Features", "Bug Fixes")
-     * @returns The matching category, or `undefined` if not recognized
+     * @remarks
+     * Comparison is case-insensitive. For example, both `"Bug Fixes"` and
+     * `"bug fixes"` will match {@link Categories.BUG_FIXES}.
+     *
+     * @param heading - The heading text (e.g., `"Features"`, `"Bug Fixes"`)
+     * @returns The matching {@link SectionCategory}, or `undefined` if the heading
+     *   does not correspond to any known category
      */
     static fromHeading(heading: string): SectionCategory | undefined;
     /**
-     * Get all valid section heading strings.
+     * Get all valid section heading strings in priority order.
      *
-     * @returns Array of heading strings in priority order
+     * @remarks
+     * Returns the `heading` field from each category in {@link Categories.ALL},
+     * preserving priority order. Useful for building validation sets or
+     * rendering category pickers.
+     *
+     * @returns Readonly array of heading strings (e.g., `["Breaking Changes", "Features", ...]`)
      */
     static allHeadings(): readonly string[];
     /**
      * Check whether a heading string matches a known category.
-     * Comparison is case-insensitive.
      *
-     * @param heading - The heading text to check
-     * @returns `true` if the heading matches a known category
+     * @remarks
+     * Comparison is case-insensitive. Equivalent to
+     * `Categories.fromHeading(heading) !== undefined`.
+     *
+     * @param heading - The heading text to validate
+     * @returns `true` if the heading matches a known category, `false` otherwise
      */
     static isValidHeading(heading: string): boolean;
 }
 
 /**
- * Static class wrapper for changelog operations.
+ * Static class wrapper for changelog formatting operations.
  *
  * Delegates to the Changesets-compatible `getReleaseLine` and
- * `getDependencyReleaseLine` functions with Effect-based internals.
+ * `getDependencyReleaseLine` functions. Internally, these use the
+ * {@link ChangelogService} Effect service layer, which coordinates
+ * the {@link GitHubService} (for commit/PR metadata) and
+ * {@link MarkdownService} (for AST manipulation) to produce
+ * structured changelog entries.
  *
- * @example
+ * @remarks
+ * This class provides the same formatting capabilities as the
+ * `\@savvy-web/changesets/changelog` subpath export, but through a
+ * class-based API rather than the Changesets default-export convention.
+ * The underlying formatter parses conventional commit prefixes from the
+ * changeset summary to determine the section category (via
+ * {@link Categories}), resolves GitHub metadata (authors, PR links,
+ * commit hashes), and produces markdown output grouped by category.
+ *
+ * The `options` parameter must include a `repo` field in `"owner/repo"`
+ * format (e.g., `"savvy-web/changesets"`) so that GitHub links can be
+ * constructed. Additional options are defined by {@link ChangesetOptionsSchema}.
+ *
+ * @example Formatting a single changeset release line
  * ```typescript
  * import { Changelog } from "\@savvy-web/changesets";
  *
  * const changeset = {
  *   id: "brave-pandas-learn",
- *   summary: "feat: add authentication system",
+ *   summary: "feat: add token refresh endpoint",
  *   releases: [{ name: "\@savvy-web/auth", type: "minor" as const }],
- *   commit: "abc1234567890",
+ *   commit: "abc1234567890abcdef1234567890abcdef123456",
  * };
  *
- * const line = await Changelog.formatReleaseLine(changeset, "minor", {
+ * const line: string = await Changelog.formatReleaseLine(changeset, "minor", {
  *   repo: "savvy-web/auth",
  * });
+ * // line contains a markdown bullet under the "Features" section heading
+ * ```
+ *
+ * @example Formatting dependency update lines
+ * ```typescript
+ * import { Changelog } from "\@savvy-web/changesets";
+ *
+ * const changesets = [
+ *   {
+ *     id: "cool-dogs-fly",
+ *     summary: "chore(deps): update effect to 3.20.0",
+ *     releases: [{ name: "\@savvy-web/core", type: "patch" as const }],
+ *     commit: "def4567890abcdef1234567890abcdef456789ab",
+ *   },
+ * ];
+ *
+ * const dependenciesUpdated = [
+ *   {
+ *     name: "\@savvy-web/utils",
+ *     type: "patch" as const,
+ *     oldVersion: "1.2.0",
+ *     newVersion: "1.2.1",
+ *     changesets: ["cool-dogs-fly"],
+ *     packageJson: { name: "\@savvy-web/utils", version: "1.2.1" },
+ *   },
+ * ];
+ *
+ * const depLines: string = await Changelog.formatDependencyReleaseLine(
+ *   changesets,
+ *   dependenciesUpdated,
+ *   { repo: "savvy-web/core" },
+ * );
+ * // depLines contains a markdown table of dependency changes
  * ```
  *
- * @see {@link Categories} for resolving commit types to section categories
+ * @see {@link ChangelogService} for the underlying Effect service
+ * @see {@link Categories} for how commit types map to section headings
+ * @see {@link ChangesetOptionsSchema} for the full options schema
  *
  * @public
  */
@@ -146,30 +333,67 @@ export declare class Changelog {
     /**
      * Format a single changeset into a changelog release line.
      *
-     * @param changeset - The changeset to format
-     * @param versionType - The semantic version bump type
-     * @param options - Configuration with `repo` in `owner/repo` format
-     * @returns Formatted markdown string
+     * @remarks
+     * Parses the changeset summary for a conventional commit prefix
+     * (e.g., `"feat: ..."`, `"fix!: ..."`), resolves the corresponding
+     * {@link SectionCategory}, and produces a markdown bullet item with
+     * optional GitHub metadata (author, PR link, commit hash).
+     *
+     * @param changeset - The changeset to format, including its `id`, `summary`,
+     *   `releases` array, and optional `commit` hash
+     * @param versionType - The semantic version bump type (`"major"`, `"minor"`, or `"patch"`)
+     * @param options - Configuration object; must include `repo` in `"owner/repo"` format.
+     *   Pass `null` to use defaults (no GitHub link resolution).
+     * @returns A promise resolving to the formatted markdown string
      */
     static formatReleaseLine(changeset: NewChangesetWithCommit, versionType: VersionType_2, options: Record<string, unknown> | null): Promise<string>;
     /**
-     * Format dependency update release lines.
+     * Format dependency update release lines into a markdown table.
+     *
+     * @remarks
+     * Generates a structured dependency table showing package names,
+     * version transitions, and dependency types. The table is placed
+     * under the "Dependencies" section heading in the changelog.
      *
-     * @param changesets - Changesets that caused dependency updates
-     * @param dependenciesUpdated - Dependencies that were updated
-     * @param options - Configuration with `repo` in `owner/repo` format
-     * @returns Formatted markdown string
+     * @param changesets - The changesets that triggered the dependency updates
+     * @param dependenciesUpdated - Array of updated dependencies with their
+     *   old/new versions and package metadata
+     * @param options - Configuration object; must include `repo` in `"owner/repo"` format.
+     *   Pass `null` to use defaults.
+     * @returns A promise resolving to the formatted markdown string containing
+     *   the dependency update table
      */
     static formatDependencyReleaseLine(changesets: NewChangesetWithCommit[], dependenciesUpdated: ModCompWithPackage[], options: Record<string, unknown> | null): Promise<string>;
 }
 
 /**
- * Service for changelog formatting.
+ * Effect service tag for changelog formatting.
+ *
+ * Provides dependency-injected access to the two Changesets API formatter
+ * functions: `formatReleaseLine` and `formatDependencyReleaseLine`.
  *
  * @remarks
- * This service tag defines the interface. Use the Changesets API entry point
- * (`\@savvy-web/changesets/changelog`) or the {@link Changelog} class for
- * the concrete implementation.
+ * This is an abstract service tag — it has no default `Layer`. The concrete
+ * implementation is the `\@savvy-web/changesets/changelog` subpath export,
+ * which wires the formatting logic through `Effect.runPromise` for the
+ * Changesets CLI. For direct Effect usage, build your own layer or use
+ * the class-based `Changelog` wrapper.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { ChangesetOptions } from "\@savvy-web/changesets";
+ * import { ChangelogService, GitHubLive, MarkdownLive } from "\@savvy-web/changesets";
+ *
+ * const program = Effect.gen(function* () {
+ *   const changelog = yield* ChangelogService;
+ *   const line = yield* changelog.formatReleaseLine(changeset, "minor", options);
+ *   return line;
+ * });
+ * ```
+ *
+ * @see {@link ChangelogServiceShape} for the service interface
+ * @see {@link ChangelogServiceBase} for the api-extractor base class
  *
  * @public
  */
@@ -191,12 +415,37 @@ export declare const ChangelogServiceBase: Context.TagClass<ChangelogService, "C
 /**
  * Service interface for changelog formatting.
  *
- * @internal
+ * Describes the two operations a `ChangelogService` implementation must
+ * provide: formatting individual release lines and formatting dependency
+ * update tables.
+ *
+ * @remarks
+ * Both methods return `Effect.Effect` values that require additional
+ * services in their environment (`R` channel). `formatReleaseLine` needs
+ * both {@link GitHubService} (for commit metadata) and {@link MarkdownService}
+ * (for markdown parsing), while `formatDependencyReleaseLine` only needs
+ * {@link GitHubService}.
+ *
+ * @public
  */
 export declare interface ChangelogServiceShape {
-    /** Format a single changeset release line. */
+    /**
+     * Format a single changeset into a markdown release line.
+     *
+     * @param changeset - The changeset to format, including its commit hash and summary
+     * @param versionType - The semantic version bump type (`major`, `minor`, or `patch`)
+     * @param options - Validated changeset configuration options (must include `repo`)
+     * @returns An `Effect` that resolves to a formatted markdown string
+     */
     readonly formatReleaseLine: (changeset: NewChangesetWithCommit, versionType: VersionType_2, options: ChangesetOptions) => Effect.Effect<string, never, GitHubService | MarkdownService>;
-    /** Format dependency update release lines. */
+    /**
+     * Format dependency update release lines as a markdown table.
+     *
+     * @param changesets - The changesets that triggered the dependency updates
+     * @param dependenciesUpdated - The list of updated dependencies with version info
+     * @param options - Validated changeset configuration options (must include `repo`)
+     * @returns An `Effect` that resolves to a formatted markdown table string, or empty string if no updates
+     */
     readonly formatDependencyReleaseLine: (changesets: NewChangesetWithCommit[], dependenciesUpdated: ModCompWithPackage[], options: ChangesetOptions) => Effect.Effect<string, never, GitHubService>;
 }
 
@@ -204,43 +453,116 @@ export declare interface ChangelogServiceShape {
  * Class-based API wrapper for changelog transformation.
  *
  * Provides a static class interface that runs all remark transform
- * plugins against CHANGELOG markdown content.
+ * plugins against CHANGELOG markdown content as the post-processing
+ * layer of the three-layer pipeline.
+ *
+ * @internal
  */
 /**
- * Static class for transforming CHANGELOG.md files.
+ * Static class for post-processing CHANGELOG.md files.
  *
- * Runs all six remark transform plugins in the correct order:
- * merge-sections, reorder-sections, deduplicate-items,
- * contributor-footnotes, issue-link-refs, normalize-format.
+ * Implements the third layer of the three-layer pipeline by running
+ * six remark transform plugins in a fixed order to clean up, normalize,
+ * and enhance changelog output produced by the formatter layer.
  *
- * @example
+ * @remarks
+ * The six plugins run in this order:
+ *
+ * 1. **MergeSectionsPlugin** -- merges duplicate section headings (e.g., two
+ *    "Features" sections from separate changesets are combined into one)
+ * 2. **ReorderSectionsPlugin** -- reorders sections by category priority
+ *    (Breaking Changes first, Other last) using the {@link Categories} priority values
+ * 3. **DeduplicateItemsPlugin** -- removes duplicate list items within a section
+ * 4. **ContributorFootnotesPlugin** -- converts inline contributor mentions
+ *    into footnote references for cleaner formatting
+ * 5. **IssueLinkRefsPlugin** -- converts inline issue/PR links into markdown
+ *    reference-style links collected at the bottom of the document
+ * 6. **NormalizeFormatPlugin** -- applies consistent formatting (spacing,
+ *    trailing newlines, heading levels)
+ *
+ * The transformer operates on the full CHANGELOG.md content (all versions),
+ * not just the latest release block. It is idempotent -- running it multiple
+ * times produces the same output.
+ *
+ * @example Transform changelog content in memory
  * ```typescript
  * import { ChangelogTransformer } from "\@savvy-web/changesets";
  *
- * // Transform a string
- * const cleaned = ChangelogTransformer.transformContent(rawMarkdown);
+ * const rawChangelog = [
+ *   "# Changelog",
+ *   "",
+ *   "## 1.2.0",
+ *   "",
+ *   "### Features",
+ *   "",
+ *   "- Added new auth endpoint",
+ *   "",
+ *   "### Features",
+ *   "",
+ *   "- Added rate limiting",
+ * ].join("\n");
+ *
+ * const cleaned: string = ChangelogTransformer.transformContent(rawChangelog);
+ * // Duplicate "Features" sections are merged into one
+ * ```
+ *
+ * @example Transform a CHANGELOG.md file in-place
+ * ```typescript
+ * import { ChangelogTransformer } from "\@savvy-web/changesets";
  *
- * // Transform a file in-place
+ * // Reads, transforms, and writes back to the same path
  * ChangelogTransformer.transformFile("CHANGELOG.md");
  * ```
  *
+ * @example Check for changes without writing (dry-run pattern)
+ * ```typescript
+ * import { readFileSync } from "node:fs";
+ * import { ChangelogTransformer } from "\@savvy-web/changesets";
+ *
+ * const original: string = readFileSync("CHANGELOG.md", "utf-8");
+ * const transformed: string = ChangelogTransformer.transformContent(original);
+ *
+ * if (original !== transformed) {
+ *   console.error("CHANGELOG.md needs transformation");
+ *   process.exitCode = 1;
+ * }
+ * ```
+ *
+ * @see {@link Categories} for the priority order used by ReorderSectionsPlugin
+ * @see {@link ChangesetLinter} for the pre-validation layer (layer 1)
+ * @see {@link Changelog} for the formatter layer (layer 2)
+ *
  * @public
  */
 export declare class ChangelogTransformer {
     private constructor();
     /**
-     * Transform CHANGELOG markdown content by running all transform plugins.
+     * Transform CHANGELOG markdown content by running all six transform plugins.
+     *
+     * @remarks
+     * The input is parsed with `remark-parse` and `remark-gfm` (for table
+     * support), processed through all six plugins in order, and stringified
+     * back to markdown. The operation is synchronous and idempotent.
      *
-     * @param content - Raw CHANGELOG markdown string
-     * @returns The transformed markdown string
+     * @param content - Raw CHANGELOG markdown string (may contain multiple
+     *   version blocks, GFM tables, footnotes, and reference links)
+     * @returns The transformed markdown string with sections merged, reordered,
+     *   deduplicated, and normalized
      */
     static transformContent(content: string): string;
     /**
      * Transform a CHANGELOG file in-place.
      *
-     * Reads the file, runs all transform plugins, and writes the result back.
+     * @remarks
+     * Reads the file synchronously, runs all transform plugins via
+     * {@link ChangelogTransformer.transformContent}, and writes the result
+     * back to the same path. The file is overwritten atomically (single
+     * `writeFileSync` call).
+     *
+     * This is the method used by the Effect CLI's `transform` subcommand
+     * when invoked without the `--dry-run` or `--check` flags.
      *
-     * @param filePath - Path to the CHANGELOG.md file
+     * @param filePath - Absolute or relative path to the CHANGELOG.md file
      */
     static transformFile(filePath: string): void;
 }
@@ -248,60 +570,142 @@ export declare class ChangelogTransformer {
 /**
  * Inferred type for {@link ChangesetSchema}.
  *
+ * @remarks
+ * Use this interface when you need to type a variable or parameter as a
+ * decoded changeset object. It is structurally equivalent to the output
+ * of `Schema.decodeUnknownSync(ChangesetSchema)(...)`.
+ *
  * @public
  */
 export declare interface Changeset extends Schema.Schema.Type<typeof ChangesetSchema> {
 }
 
 /**
- * Static class for linting changeset files.
+ * Static class for linting changeset markdown files.
  *
  * Runs the four remark-lint rules (heading-hierarchy, required-sections,
  * content-structure, uncategorized-content) against changeset markdown
- * and returns structured diagnostic messages.
+ * and returns structured {@link LintMessage} diagnostics.
  *
- * @example
+ * @remarks
+ * This class implements the pre-validation layer of the three-layer
+ * pipeline. It validates that changeset markdown conforms to the
+ * expected structure before the changelog formatter processes it.
+ *
+ * YAML frontmatter (the `---` delimited block at the top of changeset
+ * files containing package bump declarations) is automatically stripped
+ * before validation, since frontmatter is managed by Changesets itself
+ * and is not part of the markdown structure being validated.
+ *
+ * The class provides three granularity levels:
+ *
+ * - {@link ChangesetLinter.validateContent} -- validate a markdown string directly
+ * - {@link ChangesetLinter.validateFile} -- validate a single file by path
+ * - {@link ChangesetLinter.validate} -- validate all changeset files in a directory
+ *
+ * @example Validate a single file and report errors
+ * ```typescript
+ * import { ChangesetLinter } from "\@savvy-web/changesets";
+ * import type { LintMessage } from "\@savvy-web/changesets";
+ *
+ * const messages: LintMessage[] = ChangesetLinter.validateFile(
+ *   ".changeset/brave-pandas-learn.md",
+ * );
+ *
+ * if (messages.length > 0) {
+ *   for (const msg of messages) {
+ *     console.error(`${msg.file}:${msg.line}:${msg.column} [${msg.rule}] ${msg.message}`);
+ *   }
+ *   process.exitCode = 1;
+ * }
+ * ```
+ *
+ * @example Validate all changesets in a directory
  * ```typescript
  * import { ChangesetLinter } from "\@savvy-web/changesets";
  * import type { LintMessage } from "\@savvy-web/changesets";
  *
- * const messages: LintMessage[] = ChangesetLinter.validateFile("path/to/changeset.md");
- * for (const msg of messages) {
- *   console.log(`${msg.file}:${msg.line}:${msg.column} ${msg.rule} ${msg.message}`);
+ * const allMessages: LintMessage[] = ChangesetLinter.validate(".changeset");
+ *
+ * const errorsByFile = new Map<string, LintMessage[]>();
+ * for (const msg of allMessages) {
+ *   const existing = errorsByFile.get(msg.file) ?? [];
+ *   existing.push(msg);
+ *   errorsByFile.set(msg.file, existing);
+ * }
+ *
+ * for (const [file, msgs] of errorsByFile) {
+ *   console.error(`${file}: ${msgs.length} issue(s)`);
  * }
  * ```
  *
+ * @example Validate markdown content directly (useful in tests)
+ * ```typescript
+ * import { ChangesetLinter } from "\@savvy-web/changesets";
+ * import type { LintMessage } from "\@savvy-web/changesets";
+ *
+ * const content = [
+ *   "---",
+ *   '"\@savvy-web/core": patch',
+ *   "---",
+ *   "",
+ *   "## Bug Fixes",
+ *   "",
+ *   "Fixed an edge case in token validation.",
+ * ].join("\n");
+ *
+ * const messages: LintMessage[] = ChangesetLinter.validateContent(content);
+ * // messages.length === 0 (valid changeset)
+ * ```
+ *
+ * @see {@link LintMessage} for the diagnostic message shape
+ * @see {@link Categories} for the valid section headings checked by the rules
+ *
  * @public
  */
 export declare class ChangesetLinter {
     private constructor();
     /**
-     * Validate a single changeset file.
+     * Validate a single changeset file by path.
      *
-     * Reads the file, strips YAML frontmatter, and runs all lint rules.
+     * @remarks
+     * Reads the file synchronously, strips YAML frontmatter, and runs all
+     * four lint rules. The file path is preserved in each returned
+     * {@link LintMessage} for error reporting.
      *
-     * @param filePath - Path to the changeset `.md` file
-     * @returns Array of lint messages (empty if valid)
+     * @param filePath - Absolute or relative path to the changeset `.md` file
+     * @returns Array of {@link LintMessage} diagnostics (empty if the file is valid)
      */
     static validateFile(filePath: string): LintMessage[];
     /**
      * Validate a markdown string directly.
      *
-     * Strips YAML frontmatter and runs all lint rules.
+     * @remarks
+     * Strips YAML frontmatter (if present) and runs all four lint rules
+     * against the remaining content. This method is useful for validating
+     * changeset content that is already in memory, such as in test suites
+     * or editor integrations.
      *
-     * @param content - Raw markdown content (may include frontmatter)
-     * @param filePath - File path for error reporting (defaults to `"<input>"`)
-     * @returns Array of lint messages (empty if valid)
+     * @param content - Raw markdown content (may include YAML frontmatter)
+     * @param filePath - File path for error reporting; defaults to `"<input>"`
+     *   when validating in-memory content
+     * @returns Array of {@link LintMessage} diagnostics (empty if the content is valid)
      */
     static validateContent(content: string, filePath?: string): LintMessage[];
     /**
      * Validate all changeset `.md` files in a directory.
      *
-     * Scans for `*.md` files (excluding `README.md`) and runs
-     * {@link ChangesetLinter.validateFile} on each.
+     * @remarks
+     * Scans the directory for `*.md` files (excluding `README.md`) and runs
+     * {@link ChangesetLinter.validateFile} on each. Results are aggregated
+     * into a single array. The directory is read synchronously.
+     *
+     * This is the method used by the Effect CLI's `lint` and `check`
+     * subcommands to validate the `.changeset/` directory.
      *
-     * @param dir - Directory path to scan
-     * @returns Aggregated lint messages from all files
+     * @param dir - Path to the directory containing changeset files
+     *   (typically `.changeset/`)
+     * @returns Aggregated array of {@link LintMessage} diagnostics from all files
      */
     static validate(dir: string): LintMessage[];
 }
@@ -309,6 +713,9 @@ export declare class ChangesetLinter {
 /**
  * Inferred type for {@link ChangesetOptionsSchema}.
  *
+ * @remarks
+ * The `repo` field is always present; all other fields are optional.
+ *
  * @public
  */
 export declare interface ChangesetOptions extends Schema.Schema.Type<typeof ChangesetOptionsSchema> {
@@ -317,6 +724,34 @@ export declare interface ChangesetOptions extends Schema.Schema.Type<typeof Chan
 /**
  * Schema for changeset configuration options.
  *
+ * @remarks
+ * The `repo` field is required; all other fields are optional with sensible
+ * defaults applied by the changelog formatter at runtime. The `versionFiles`
+ * option allows specifying additional JSON files (beyond `package.json`)
+ * whose version fields should be updated during `changeset version`.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { ChangesetOptionsSchema } from "@savvy-web/changesets";
+ * import type { ChangesetOptions } from "@savvy-web/changesets";
+ *
+ * const options: ChangesetOptions = Schema.decodeUnknownSync(ChangesetOptionsSchema)({
+ * 	repo: "savvy-web/changesets",
+ * 	commitLinks: true,
+ * 	prLinks: true,
+ * 	issueLinks: true,
+ * 	issuePrefixes: ["#", "GH-"],
+ * 	versionFiles: [
+ * 		{ glob: "manifest.json", paths: ["$.version"] },
+ * 	],
+ * });
+ * ```
+ *
+ * @see {@link ChangesetOptions} for the inferred TypeScript type
+ * @see {@link validateChangesetOptions} for Effect-idiomatic validation with detailed error messages
+ * @see {@link VersionFilesSchema} for the `versionFiles` entry format
+ *
  * @public
  */
 export declare const ChangesetOptionsSchema: Schema.Struct<{
@@ -340,6 +775,29 @@ export declare const ChangesetOptionsSchema: Schema.Struct<{
 /**
  * Schema for a changeset object.
  *
+ * @remarks
+ * Represents a single changeset entry as consumed by the changelog formatter.
+ * The `summary` is the human-readable description, `id` is a unique identifier
+ * (typically the changeset filename without extension), and `commit` is the
+ * optional git SHA that introduced the changeset.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { ChangesetSchema } from "@savvy-web/changesets";
+ * import type { Changeset } from "@savvy-web/changesets";
+ *
+ * const changeset: Changeset = Schema.decodeUnknownSync(ChangesetSchema)({
+ * 	summary: "Add retry logic to API client",
+ * 	id: "brave-dogs-laugh",
+ * 	commit: "a1b2c3d",
+ * });
+ * ```
+ *
+ * @see {@link Changeset} for the inferred TypeScript type
+ * @see {@link ChangesetSummarySchema} for summary validation rules
+ * @see {@link CommitHashSchema} for commit hash format requirements
+ *
  * @public
  */
 export declare const ChangesetSchema: Schema.Struct<{
@@ -352,7 +810,26 @@ export declare const ChangesetSchema: Schema.Struct<{
 }>;
 
 /**
- * Schema for a changeset summary (1-1000 characters).
+ * Schema for a changeset summary (1--1000 characters).
+ *
+ * @remarks
+ * Enforces that every changeset has a non-empty summary and caps length
+ * at 1000 characters. Longer descriptions should go in the changeset body,
+ * not the summary line. Validation messages guide users toward correct usage.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { ChangesetSummarySchema } from "@savvy-web/changesets";
+ *
+ * // Succeeds — valid summary
+ * const summary = Schema.decodeUnknownSync(ChangesetSummarySchema)(
+ * 	"Fix authentication timeout in login flow"
+ * );
+ *
+ * // Throws ParseError — empty string
+ * Schema.decodeUnknownSync(ChangesetSummarySchema)("");
+ * ```
  *
  * @public
  */
@@ -361,7 +838,30 @@ export declare const ChangesetSummarySchema: Schema.filter<Schema.filter<typeof
 /**
  * Changeset file validation failure.
  *
- * Carries structured issue details with JSON-path and message per issue.
+ * @remarks
+ * Raised when a changeset markdown file fails structural validation
+ * (e.g., missing summary, invalid heading, malformed dependency table).
+ * Carries an array of structured issues, each with a JSON-path pointing
+ * to the problematic field and a human-readable message.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { ChangesetValidationError } from "@savvy-web/changesets";
+ *
+ * declare const program: Effect.Effect<void, ChangesetValidationError>;
+ *
+ * const handled = program.pipe(
+ * 	Effect.catchTag("ChangesetValidationError", (err) => {
+ * 		for (const issue of err.issues) {
+ * 			console.error(`${issue.path}: ${issue.message}`);
+ * 		}
+ * 		return Effect.void;
+ * 	}),
+ * );
+ * ```
+ *
+ * @see {@link ChangesetSchema} for the schema that drives validation
  *
  * @public
  */
@@ -380,7 +880,7 @@ export declare class ChangesetValidationError extends ChangesetValidationErrorBa
 }
 
 /**
- * Base class for ChangesetValidationError.
+ * Base class for {@link ChangesetValidationError}.
  *
  * @privateRemarks
  * This export is required for api-extractor documentation generation.
@@ -396,6 +896,34 @@ export declare const ChangesetValidationErrorBase: new <A extends Record<string,
 /**
  * Schema for a git commit hash (at least 7 lowercase hex characters).
  *
+ * @remarks
+ * Accepts both abbreviated (7-character) and full (40-character) SHA-1 hashes.
+ * Only lowercase hexadecimal characters are allowed; uppercase letters will
+ * fail validation. This matches the output of `git rev-parse --short` and
+ * `git log --format=%h`.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { CommitHashSchema } from "@savvy-web/changesets";
+ *
+ * // Succeeds — abbreviated hash
+ * const short = Schema.decodeUnknownSync(CommitHashSchema)("a1b2c3d");
+ *
+ * // Succeeds — full 40-character SHA
+ * const full = Schema.decodeUnknownSync(CommitHashSchema)(
+ * 	"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+ * );
+ *
+ * // Throws ParseError — too short
+ * Schema.decodeUnknownSync(CommitHashSchema)("a1b2c3");
+ *
+ * // Throws ParseError — uppercase not allowed
+ * Schema.decodeUnknownSync(CommitHashSchema)("A1B2C3D");
+ * ```
+ *
+ * @see {@link ChangesetSchema} which uses this for the optional `commit` field
+ *
  * @public
  */
 export declare const CommitHashSchema: Schema.filter<typeof Schema.String>;
@@ -403,7 +931,27 @@ export declare const CommitHashSchema: Schema.filter<typeof Schema.String>;
 /**
  * Invalid or missing configuration.
  *
+ * @remarks
+ * Raised when the changeset configuration (typically from `.changeset/config.json`)
+ * is missing required fields, has invalid values, or cannot be parsed. The `field`
+ * property identifies which configuration field is problematic, and `reason`
+ * provides an actionable message.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { ConfigurationError, validateChangesetOptions } from "@savvy-web/changesets";
+ *
+ * const program = validateChangesetOptions({ repo: "invalid" }).pipe(
+ * 	Effect.catchTag("ConfigurationError", (err) => {
+ * 		console.error(`Field "${err.field}": ${err.reason}`);
+ * 		return Effect.fail(err);
+ * 	}),
+ * );
+ * ```
+ *
  * @see {@link ChangesetOptionsSchema} for the expected configuration shape
+ * @see {@link validateChangesetOptions} for the validation function that produces this error
  *
  * @public
  */
@@ -417,7 +965,7 @@ export declare class ConfigurationError extends ConfigurationErrorBase<{
 }
 
 /**
- * Base class for ConfigurationError.
+ * Base class for {@link ConfigurationError}.
  *
  * @privateRemarks
  * This export is required for api-extractor documentation generation.
@@ -431,70 +979,464 @@ export declare const ConfigurationErrorBase: new <A extends Record<string, any>
 } & Readonly<A>;
 
 /**
- * Inferred type for {@link DependencyTypeSchema}.
+ * Inferred type for {@link DependencyActionSchema}.
  *
- * @public
- */
-export declare type DependencyType = typeof DependencyTypeSchema.Type;
-
-/**
- * Schema for npm dependency types.
+ * @remarks
+ * One of `"added"`, `"updated"`, or `"removed"`.
  *
  * @public
  */
-export declare const DependencyTypeSchema: Schema.Literal<["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]>;
+export declare type DependencyAction = typeof DependencyActionSchema.Type;
 
 /**
- * Inferred type for {@link DependencyUpdateSchema}.
+ * Valid dependency table actions.
  *
- * @public
- */
-export declare interface DependencyUpdate extends Schema.Schema.Type<typeof DependencyUpdateSchema> {
-}
-
-/**
- * Schema for a dependency update entry.
+ * @remarks
+ * Represents the three possible operations on a dependency: `"added"` for
+ * new dependencies, `"updated"` for version changes, and `"removed"` for
+ * deletions. Used in the "Action" column of dependency tables.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { DependencyActionSchema } from "@savvy-web/changesets";
+ * import type { DependencyAction } from "@savvy-web/changesets";
+ *
+ * const action: DependencyAction = Schema.decodeUnknownSync(DependencyActionSchema)("updated");
+ * ```
  *
  * @public
  */
-export declare const DependencyUpdateSchema: Schema.Struct<{
-    /** Package name (must be non-empty). */
-    name: Schema.refine<string, typeof Schema.String>;
-    /** npm dependency type. */
-    type: Schema.Literal<["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]>;
-    /** Previous version string. */
-    oldVersion: typeof Schema.String;
-    /** New version string. */
-    newVersion: typeof Schema.String;
-}>;
+export declare const DependencyActionSchema: Schema.Literal<["added", "updated", "removed"]>;
 
 /**
- * GitHub API request failure.
+ * Static class for dependency table manipulation.
+ *
+ * Wraps the internal utility functions that operate on dependency tables --
+ * the structured markdown tables that appear in the "Dependencies" section
+ * of changelogs. Each row in a dependency table represents a single package
+ * change with its name, type, action, and version transition.
  *
  * @remarks
- * Use {@link GitHubApiError.isRetryable} to determine whether a retry
- * strategy should be applied. Rate-limited responses (403/429) and
- * server errors (5xx) are considered retryable.
+ * The typical workflow for processing dependency tables is:
  *
- * @public
- */
-export declare class GitHubApiError extends GitHubApiErrorBase<{
-    /** The API operation that failed (e.g., "getInfo"). */
-    readonly operation: string;
-    /** HTTP status code, if available. */
-    readonly statusCode?: number | undefined;
-    /** Human-readable failure reason. */
-    readonly reason: string;
-}> {
-    get message(): string;
-    /** Whether this error is a rate-limit response (403 or 429). */
-    get isRateLimited(): boolean;
-    /** Whether this error is eligible for retry (server errors or rate limits). */
+ * 1. **Parse** an mdast `Table` node into typed {@link DependencyTableRow} objects
+ * 2. **Collapse** duplicate rows (same package updated multiple times) into single entries
+ * 3. **Sort** rows by dependency type, then alphabetically by package name
+ * 4. **Serialize** back to an mdast `Table` node or directly to a markdown string
+ *
+ * The {@link DependencyTable.aggregate} method combines the collapse and sort
+ * steps into a single call, which is the most common usage pattern.
+ *
+ * Each {@link DependencyTableRow} is validated by the {@link DependencyTableRowSchema}
+ * Effect Schema at system boundaries, ensuring that dependency names, types,
+ * actions, and version strings conform to expected formats.
+ *
+ * @example Parse, aggregate, and serialize a dependency table
+ * ```typescript
+ * import { DependencyTable } from "\@savvy-web/changesets";
+ * import type { DependencyTableRow } from "\@savvy-web/changesets";
+ * import type { Table } from "mdast";
+ *
+ * // Given an mdast Table node from a parsed CHANGELOG
+ * declare const tableNode: Table;
+ *
+ * // Parse into typed rows
+ * const rows: DependencyTableRow[] = DependencyTable.parse(tableNode);
+ *
+ * // Collapse duplicates and sort by type, then name
+ * const aggregated: DependencyTableRow[] = DependencyTable.aggregate(rows);
+ *
+ * // Serialize back to an mdast Table node for further AST manipulation
+ * const outputNode: Table = DependencyTable.serialize(aggregated);
+ *
+ * // Or serialize directly to a markdown string
+ * const markdown: string = DependencyTable.toMarkdown(aggregated);
+ * ```
+ *
+ * @example Step-by-step collapse and sort
+ * ```typescript
+ * import { DependencyTable } from "\@savvy-web/changesets";
+ * import type { DependencyTableRow } from "\@savvy-web/changesets";
+ *
+ * declare const rows: DependencyTableRow[];
+ *
+ * // Collapse duplicate entries (same package appears multiple times)
+ * const collapsed: DependencyTableRow[] = DependencyTable.collapse(rows);
+ *
+ * // Sort by dependency type, then alphabetically by name
+ * const sorted: DependencyTableRow[] = DependencyTable.sort(collapsed);
+ * ```
+ *
+ * @see {@link DependencyTableRow} for the row shape (dependency, type, action, from, to)
+ * @see {@link DependencyTableRowSchema} for the Effect Schema that validates row data
+ * @see {@link DependencyTableSchema} for the non-empty array schema
+ *
+ * @public
+ */
+export declare class DependencyTable {
+    private constructor();
+    /**
+     * Parse an mdast `Table` node into typed dependency table rows.
+     *
+     * @remarks
+     * Extracts the text content from each table cell and maps it to the
+     * corresponding {@link DependencyTableRow} fields. The first row is
+     * treated as the header and skipped. Rows that do not have the expected
+     * number of columns are ignored.
+     *
+     * @param tableNode - An mdast `Table` node from a parsed markdown AST
+     * @returns Array of {@link DependencyTableRow} objects, one per data row
+     */
+    static parse(tableNode: Table): DependencyTableRow[];
+    /**
+     * Serialize typed dependency table rows into an mdast `Table` node.
+     *
+     * @remarks
+     * Produces a well-formed mdast `Table` with a header row
+     * (`Dependency | Type | Action | From | To`) followed by one data row
+     * per input entry. The resulting node can be inserted into a remark AST
+     * for further processing or stringification.
+     *
+     * @param rows - Array of {@link DependencyTableRow} objects to serialize
+     * @returns An mdast `Table` node ready for AST insertion
+     */
+    static serialize(rows: DependencyTableRow[]): Table;
+    /**
+     * Serialize typed dependency table rows directly to a markdown string.
+     *
+     * @remarks
+     * Convenience method that combines {@link DependencyTable.serialize} with
+     * remark stringification. Produces a GFM-compatible markdown table string.
+     *
+     * @param rows - Array of {@link DependencyTableRow} objects to render
+     * @returns A markdown string containing the formatted table
+     */
+    static toMarkdown(rows: DependencyTableRow[]): string;
+    /**
+     * Collapse duplicate dependency rows into single entries.
+     *
+     * @remarks
+     * When a package appears in multiple rows (e.g., updated in separate
+     * changesets), this method merges them by keeping the earliest `from`
+     * version and the latest `to` version, producing a single row that
+     * represents the net change.
+     *
+     * @param rows - Array of {@link DependencyTableRow} objects, possibly with duplicates
+     * @returns A new array with duplicate packages collapsed into single rows
+     */
+    static collapse(rows: DependencyTableRow[]): DependencyTableRow[];
+    /**
+     * Sort dependency rows by action, type, and package name.
+     *
+     * @remarks
+     * Applies a three-level stable sort:
+     * 1. **Action** — `removed` first, then `updated`, then `added`
+     * 2. **Type** — alphabetically (e.g., `config` before `dependency`)
+     * 3. **Dependency name** — alphabetically within each action+type group
+     *
+     * @param rows - Array of {@link DependencyTableRow} objects to sort
+     * @returns A new array sorted by action, type, then name
+     */
+    static sort(rows: DependencyTableRow[]): DependencyTableRow[];
+    /**
+     * Collapse duplicate rows and then sort the result.
+     *
+     * @remarks
+     * Equivalent to calling {@link DependencyTable.collapse} followed by
+     * {@link DependencyTable.sort}. This is the recommended method for
+     * preparing dependency table data for final output, as it produces
+     * a clean, deduplicated, and consistently ordered table.
+     *
+     * @param rows - Array of {@link DependencyTableRow} objects to aggregate
+     * @returns A new array with duplicates collapsed and rows sorted
+     */
+    static aggregate(rows: DependencyTableRow[]): DependencyTableRow[];
+}
+
+/**
+ * Inferred type for {@link DependencyTableRowSchema}.
+ *
+ * @public
+ */
+export declare interface DependencyTableRow extends Schema.Schema.Type<typeof DependencyTableRowSchema> {
+}
+
+/**
+ * Schema for a single dependency table row.
+ *
+ * @remarks
+ * Represents one row of a dependency update table in a CHANGELOG.
+ * Each row captures the dependency name, its type, the change action,
+ * and the "from" and "to" version strings. For added dependencies the
+ * `from` field is an em dash; for removed dependencies the `to` field
+ * is an em dash.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { DependencyTableRowSchema } from "@savvy-web/changesets";
+ * import type { DependencyTableRow } from "@savvy-web/changesets";
+ *
+ * const row: DependencyTableRow = Schema.decodeUnknownSync(DependencyTableRowSchema)({
+ * 	dependency: "effect",
+ * 	type: "dependency",
+ * 	action: "updated",
+ * 	from: "3.18.0",
+ * 	to: "3.19.1",
+ * });
+ *
+ * // Newly added dependency — "from" is em dash
+ * const addedRow: DependencyTableRow = Schema.decodeUnknownSync(DependencyTableRowSchema)({
+ * 	dependency: "@effect/cli",
+ * 	type: "dependency",
+ * 	action: "added",
+ * 	from: "\u2014",
+ * 	to: "0.50.0",
+ * });
+ * ```
+ *
+ * @see {@link DependencyTableRow} for the inferred TypeScript type
+ * @see {@link DependencyTableSchema} for a non-empty array of rows
+ *
+ * @public
+ */
+export declare const DependencyTableRowSchema: Schema.Struct<{
+    /** Package or toolchain name. */
+    dependency: Schema.filter<typeof Schema.String>;
+    /** Dependency type. */
+    type: Schema.Literal<["dependency", "devDependency", "peerDependency", "optionalDependency", "workspace", "config"]>;
+    /** Change action. */
+    action: Schema.Literal<["added", "updated", "removed"]>;
+    /** Previous version (em dash for added). */
+    from: Schema.filter<typeof Schema.String>;
+    /** New version (em dash for removed). */
+    to: Schema.filter<typeof Schema.String>;
+}>;
+
+/**
+ * Schema for a dependency table (non-empty array of rows).
+ *
+ * @remarks
+ * Validates that the table contains at least one row. Used to represent
+ * the full dependency update table in a changeset or CHANGELOG entry.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { DependencyTableSchema } from "@savvy-web/changesets";
+ *
+ * const table = Schema.decodeUnknownSync(DependencyTableSchema)([
+ * 	{
+ * 		dependency: "effect",
+ * 		type: "dependency",
+ * 		action: "updated",
+ * 		from: "3.18.0",
+ * 		to: "3.19.1",
+ * 	},
+ * 	{
+ * 		dependency: "typescript",
+ * 		type: "config",
+ * 		action: "updated",
+ * 		from: "5.6.0",
+ * 		to: "5.7.2",
+ * 	},
+ * ]);
+ *
+ * // Throws ParseError — empty array
+ * Schema.decodeUnknownSync(DependencyTableSchema)([]);
+ * ```
+ *
+ * @see {@link DependencyTableRowSchema} for the individual row schema
+ *
+ * @public
+ */
+export declare const DependencyTableSchema: Schema.filter<Schema.Array$<Schema.Struct<{
+    /** Package or toolchain name. */
+    dependency: Schema.filter<typeof Schema.String>;
+    /** Dependency type. */
+    type: Schema.Literal<["dependency", "devDependency", "peerDependency", "optionalDependency", "workspace", "config"]>;
+    /** Change action. */
+    action: Schema.Literal<["added", "updated", "removed"]>;
+    /** Previous version (em dash for added). */
+    from: Schema.filter<typeof Schema.String>;
+    /** New version (em dash for removed). */
+    to: Schema.filter<typeof Schema.String>;
+}>>>;
+
+/**
+ * Inferred type for {@link DependencyTableTypeSchema}.
+ *
+ * @remarks
+ * One of `"dependency"`, `"devDependency"`, `"peerDependency"`,
+ * `"optionalDependency"`, `"workspace"`, or `"config"`.
+ *
+ * @public
+ */
+export declare type DependencyTableType = typeof DependencyTableTypeSchema.Type;
+
+/**
+ * Extended dependency types for table format.
+ *
+ * @remarks
+ * Unlike {@link DependencyTypeSchema} (which uses plural npm field names like
+ * `"dependencies"`), this schema uses singular forms (`"dependency"`) and adds
+ * two additional types: `"workspace"` for monorepo workspace references and
+ * `"config"` for configuration toolchain updates (e.g., ESLint, TypeScript).
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { DependencyTableTypeSchema } from "@savvy-web/changesets";
+ * import type { DependencyTableType } from "@savvy-web/changesets";
+ *
+ * const tableType: DependencyTableType = Schema.decodeUnknownSync(
+ * 	DependencyTableTypeSchema
+ * )("workspace");
+ * ```
+ *
+ * @see {@link DependencyTypeSchema} for the plural npm-field variant
+ *
+ * @public
+ */
+export declare const DependencyTableTypeSchema: Schema.Literal<["dependency", "devDependency", "peerDependency", "optionalDependency", "workspace", "config"]>;
+
+/**
+ * Inferred type for {@link DependencyTypeSchema}.
+ *
+ * @remarks
+ * One of `"dependencies"`, `"devDependencies"`, `"peerDependencies"`,
+ * or `"optionalDependencies"`.
+ *
+ * @public
+ */
+export declare type DependencyType = typeof DependencyTypeSchema.Type;
+
+/**
+ * Schema for npm dependency types.
+ *
+ * @remarks
+ * Represents the four standard `package.json` dependency fields using their
+ * plural key names as they appear in the manifest. For the singular,
+ * table-oriented variant that includes `workspace` and `config` types,
+ * see {@link DependencyTableTypeSchema}.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { DependencyTypeSchema } from "@savvy-web/changesets";
+ * import type { DependencyType } from "@savvy-web/changesets";
+ *
+ * const depType: DependencyType = Schema.decodeUnknownSync(DependencyTypeSchema)(
+ * 	"devDependencies"
+ * );
+ * ```
+ *
+ * @see {@link DependencyTableTypeSchema} for the extended singular-form variant
+ *
+ * @public
+ */
+export declare const DependencyTypeSchema: Schema.Literal<["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]>;
+
+/**
+ * Inferred type for {@link DependencyUpdateSchema}.
+ *
+ * @remarks
+ * Use this interface when you need to type a variable or parameter as a
+ * decoded dependency update object.
+ *
+ * @public
+ */
+export declare interface DependencyUpdate extends Schema.Schema.Type<typeof DependencyUpdateSchema> {
+}
+
+/**
+ * Schema for a dependency update entry.
+ *
+ * @remarks
+ * Represents a single dependency version change as reported by
+ * the Changesets API. Captures the package name, which dependency
+ * field it belongs to, and the old and new version strings.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { DependencyUpdateSchema } from "@savvy-web/changesets";
+ * import type { DependencyUpdate } from "@savvy-web/changesets";
+ *
+ * const update: DependencyUpdate = Schema.decodeUnknownSync(DependencyUpdateSchema)({
+ * 	name: "effect",
+ * 	type: "dependencies",
+ * 	oldVersion: "3.18.0",
+ * 	newVersion: "3.19.1",
+ * });
+ * ```
+ *
+ * @see {@link DependencyUpdate} for the inferred TypeScript type
+ * @see {@link DependencyTableRowSchema} for the table-formatted variant
+ *
+ * @public
+ */
+export declare const DependencyUpdateSchema: Schema.Struct<{
+    /** Package name (must be non-empty). */
+    name: Schema.refine<string, typeof Schema.String>;
+    /** npm dependency type. */
+    type: Schema.Literal<["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]>;
+    /** Previous version string. */
+    oldVersion: typeof Schema.String;
+    /** New version string. */
+    newVersion: typeof Schema.String;
+}>;
+
+/**
+ * GitHub API request failure.
+ *
+ * @remarks
+ * Raised when a call to the GitHub API (via `\@changesets/get-github-info`)
+ * fails due to network issues, authentication errors, rate limiting, or
+ * server errors. Use the {@link GitHubApiError.isRetryable | isRetryable}
+ * property to determine whether a retry strategy should be applied.
+ * Rate-limited responses (403/429) and server errors (5xx) are considered
+ * retryable.
+ *
+ * @example
+ * ```typescript
+ * import { Effect, Schedule } from "effect";
+ * import { GitHubApiError } from "@savvy-web/changesets";
+ *
+ * declare const program: Effect.Effect<void, GitHubApiError>;
+ *
+ * const withRetry = program.pipe(
+ * 	Effect.catchTag("GitHubApiError", (err) => {
+ * 		if (err.isRetryable) {
+ * 			return Effect.retry(program, Schedule.exponential("1 second"));
+ * 		}
+ * 		return Effect.fail(err);
+ * 	}),
+ * );
+ * ```
+ *
+ * @see {@link GitHubService} for the Effect service that may produce this error
+ *
+ * @public
+ */
+export declare class GitHubApiError extends GitHubApiErrorBase<{
+    /** The API operation that failed (e.g., `"getInfo"`). */
+    readonly operation: string;
+    /** HTTP status code, if available. */
+    readonly statusCode?: number | undefined;
+    /** Human-readable failure reason. */
+    readonly reason: string;
+}> {
+    get message(): string;
+    /** Whether this error is a rate-limit response (403 or 429). */
+    get isRateLimited(): boolean;
+    /** Whether this error is eligible for retry (server errors or rate limits). */
     get isRetryable(): boolean;
 }
 
 /**
- * Base class for GitHubApiError.
+ * Base class for {@link GitHubApiError}.
  *
  * @privateRemarks
  * This export is required for api-extractor documentation generation.
@@ -510,6 +1452,27 @@ export declare const GitHubApiErrorBase: new <A extends Record<string, any> = {}
 /**
  * Structured result from the GitHub commit info API.
  *
+ * @remarks
+ * Represents the data returned by `\@changesets/get-github-info` for a
+ * single commit. Includes the commit author's GitHub username, the
+ * associated pull request number (if any), and pre-formatted markdown
+ * links for use in changelog entries.
+ *
+ * @example
+ * ```typescript
+ * import type { GitHubCommitInfo } from "\@savvy-web/changesets";
+ *
+ * const info: GitHubCommitInfo = {
+ *   user: "octocat",
+ *   pull: 42,
+ *   links: {
+ *     commit: "[`abc1234`](https://github.com/owner/repo/commit/abc1234)",
+ *     pull: "[#42](https://github.com/owner/repo/pull/42)",
+ *     user: "[\@octocat](https://github.com/octocat)",
+ *   },
+ * };
+ * ```
+ *
  * @public
  */
 export declare interface GitHubCommitInfo {
@@ -531,13 +1494,48 @@ export declare interface GitHubCommitInfo {
 /**
  * Inferred type for {@link GitHubInfoSchema}.
  *
+ * @remarks
+ * Contains optional `user` (GitHub username), optional `pull` (PR number),
+ * and a required `links` object with pre-formatted commit, pull, and user
+ * links.
+ *
  * @public
  */
 export declare interface GitHubInfo extends Schema.Schema.Type<typeof GitHubInfoSchema> {
 }
 
 /**
- * Schema for a GitHub info response from \@changesets/get-github-info.
+ * Schema for a GitHub info response from `\@changesets/get-github-info`.
+ *
+ * @remarks
+ * Represents the structured data returned when querying GitHub for commit
+ * metadata. The `user` and `pull` fields are optional because not every
+ * commit is associated with a pull request or a known GitHub user (e.g.,
+ * bot commits or squash-merged commits without a linked PR).
+ *
+ * The `links` object contains pre-formatted markdown or URL strings for
+ * the commit, pull request, and user profile -- ready for insertion into
+ * CHANGELOG entries.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { GitHubInfoSchema } from "@savvy-web/changesets";
+ * import type { GitHubInfo } from "@savvy-web/changesets";
+ *
+ * const info: GitHubInfo = Schema.decodeUnknownSync(GitHubInfoSchema)({
+ * 	user: "octocat",
+ * 	pull: 42,
+ * 	links: {
+ * 		commit: "[`a1b2c3d`](https://github.com/owner/repo/commit/a1b2c3d)",
+ * 		pull: "[#42](https://github.com/owner/repo/pull/42)",
+ * 		user: "[@octocat](https://github.com/octocat)",
+ * 	},
+ * });
+ * ```
+ *
+ * @see {@link GitHubInfo} for the inferred TypeScript type
+ * @see {@link GitHubService} for the Effect service that produces these values
  *
  * @public
  */
@@ -558,17 +1556,91 @@ export declare const GitHubInfoSchema: Schema.Struct<{
 }>;
 
 /**
- * Live layer that delegates to \@changesets/get-github-info.
+ * Production layer for {@link GitHubService}.
+ *
+ * Delegates to `\@changesets/get-github-info` to fetch commit metadata
+ * from the GitHub REST API. Requires a `GITHUB_TOKEN` environment variable
+ * to be set for authenticated requests.
+ *
+ * @remarks
+ * This layer is used by the `\@savvy-web/changesets/changelog` entry point
+ * to resolve commit hashes into PR numbers and author attribution. It is
+ * composed with {@link MarkdownLive} in the changelog formatter's
+ * `MainLayer`.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { GitHubService, GitHubLive } from "\@savvy-web/changesets";
+ *
+ * const program = Effect.gen(function* () {
+ *   const github = yield* GitHubService;
+ *   return yield* github.getInfo({ commit: "abc1234", repo: "owner/repo" });
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(GitHubLive)));
+ * ```
  *
  * @public
  */
 export declare const GitHubLive: Layer.Layer<GitHubService, never, never>;
 
 /**
- * Service for GitHub API operations.
+ * Effect service tag for GitHub API operations.
+ *
+ * Provides dependency-injected access to GitHub commit metadata lookups.
+ * Use `yield* GitHubService` inside an `Effect.gen` block to obtain the
+ * service instance.
+ *
+ * @remarks
+ * This tag follows the standard Effect `Context.Tag` pattern. Two layers
+ * are provided out of the box:
+ *
+ * - {@link GitHubLive} — production layer backed by the GitHub REST API
+ * - {@link makeGitHubTest} — factory for deterministic test layers
+ *
+ * @example
+ * ```typescript
+ * import { Effect, Layer } from "effect";
+ * import { GitHubService, GitHubLive } from "\@savvy-web/changesets";
+ *
+ * const program = Effect.gen(function* () {
+ *   const github = yield* GitHubService;
+ *   const info = yield* github.getInfo({
+ *     commit: "abc1234567890",
+ *     repo: "savvy-web/changesets",
+ *   });
+ *   console.log(info.user, info.pull, info.links);
+ * });
  *
+ * // Provide the live layer and run
+ * Effect.runPromise(program.pipe(Effect.provide(GitHubLive)));
+ * ```
+ *
+ * @example Creating a test layer with canned responses
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { GitHubCommitInfo } from "\@savvy-web/changesets";
+ * import { GitHubService, makeGitHubTest } from "\@savvy-web/changesets";
+ *
+ * const testResponses = new Map<string, GitHubCommitInfo>([
+ *   ["abc1234", { user: "octocat", pull: 42, links: { pull: "#42", user: "\@octocat" } }],
+ * ]);
+ *
+ * const TestLayer = makeGitHubTest(testResponses);
+ *
+ * const program = Effect.gen(function* () {
+ *   const github = yield* GitHubService;
+ *   return yield* github.getInfo({ commit: "abc1234", repo: "owner/repo" });
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(TestLayer)));
+ * ```
+ *
+ * @see {@link GitHubServiceShape} for the service interface
  * @see {@link GitHubLive} for the production layer
  * @see {@link makeGitHubTest} for creating test layers
+ * @see {@link GitHubServiceBase} for the api-extractor base class
  *
  * @public
  */
@@ -590,10 +1662,25 @@ export declare const GitHubServiceBase: Context.TagClass<GitHubService, "GitHubS
 /**
  * Service interface for GitHub API operations.
  *
- * @internal
+ * Describes the single `getInfo` operation that resolves a commit hash to
+ * its associated GitHub metadata (pull-request number, author, and links).
+ *
+ * @remarks
+ * The `getInfo` method may fail with a {@link GitHubApiError} when the
+ * GitHub API is unreachable or the commit is not found. Callers should
+ * handle this error channel — the changelog formatters recover gracefully
+ * by omitting attribution when the call fails.
+ *
+ * @public
  */
 export declare interface GitHubServiceShape {
-    /** Fetch commit info (author, PR, links) for a given commit. */
+    /**
+     * Fetch commit metadata from the GitHub API.
+     *
+     * @param params - The commit hash and repository identifier. Must include
+     * `commit` (full SHA-1 hash) and `repo` (in `owner/repo` format).
+     * @returns An `Effect` that resolves to {@link GitHubCommitInfo} or fails with {@link GitHubApiError}
+     */
     readonly getInfo: (params: {
         commit: string;
         repo: string;
@@ -603,6 +1690,25 @@ export declare interface GitHubServiceShape {
 /**
  * Schema for a GitHub issue or PR number (positive integer).
  *
+ * @remarks
+ * Built on {@link PositiveInteger}, this schema adds GitHub-specific
+ * annotations for documentation tooling. Issue and PR numbers in GitHub
+ * are always positive integers starting from 1.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { IssueNumberSchema } from "@savvy-web/changesets";
+ *
+ * // Succeeds
+ * const prNum = Schema.decodeUnknownSync(IssueNumberSchema)(42);
+ *
+ * // Throws ParseError — zero is not a valid issue number
+ * Schema.decodeUnknownSync(IssueNumberSchema)(0);
+ * ```
+ *
+ * @see {@link GitHubInfoSchema} which uses this for the `pull` field
+ *
  * @public
  */
 export declare const IssueNumberSchema: Schema.refine<number, Schema.filter<typeof Schema.Number>>;
@@ -610,8 +1716,29 @@ export declare const IssueNumberSchema: Schema.refine<number, Schema.filter<type
 /**
  * Schema for a JSONPath expression starting with `$.`.
  *
+ * @remarks
  * Supports property access (`$.foo.bar`), array wildcard (`$.foo[*].bar`),
- * and array index access (`$.foo[0].bar`).
+ * and array index access (`$.foo[0].bar`). The expression must begin with
+ * `$.` followed by at least one property segment.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { JsonPathSchema } from "@savvy-web/changesets";
+ *
+ * // Succeeds — simple property access
+ * Schema.decodeUnknownSync(JsonPathSchema)("$.version");
+ *
+ * // Succeeds — nested property access
+ * Schema.decodeUnknownSync(JsonPathSchema)("$.metadata.version");
+ *
+ * // Throws ParseError — missing "$." prefix
+ * Schema.decodeUnknownSync(JsonPathSchema)("version");
+ * ```
+ *
+ * @see {@link VersionFileConfigSchema} which uses this for the `paths` field
+ *
+ * @public
  */
 export declare const JsonPathSchema: Schema.filter<typeof Schema.String>;
 
@@ -619,38 +1746,141 @@ export declare const JsonPathSchema: Schema.filter<typeof Schema.String>;
  * Class-based API wrapper for changeset linting.
  *
  * Provides a static class interface that runs all remark-lint rules
- * against changeset markdown files.
+ * against changeset markdown files and returns structured diagnostics.
+ *
+ * @internal
  */
 /**
- * A single lint message from validation.
+ * A single lint diagnostic message produced by changeset validation.
+ *
+ * @remarks
+ * Each `LintMessage` corresponds to one remark-lint rule violation found
+ * during changeset validation. Messages include source location information
+ * (file, line, column) for integration with editors, CI reporters, and
+ * the Effect CLI's `lint` and `check` commands.
+ *
+ * The four rules that produce lint messages are:
+ *
+ * - **heading-hierarchy** -- ensures headings follow a valid nesting order
+ * - **required-sections** -- checks that mandatory sections are present
+ * - **content-structure** -- validates the structure of section content
+ * - **uncategorized-content** -- flags content outside recognized section headings
  *
  * @public
  */
 export declare interface LintMessage {
-    /** File path that was validated. */
+    /**
+     * File path that was validated.
+     *
+     * @remarks
+     * Set to the actual filesystem path when using {@link ChangesetLinter.validateFile}
+     * or {@link ChangesetLinter.validate}. Defaults to `"<input>"` when using
+     * {@link ChangesetLinter.validateContent} without an explicit path.
+     */
     file: string;
-    /** Rule name that produced the message. */
+    /**
+     * Identifier of the remark-lint rule that produced this message.
+     *
+     * @remarks
+     * Corresponds to one of the four built-in rules: `"heading-hierarchy"`,
+     * `"required-sections"`, `"content-structure"`, or `"uncategorized-content"`.
+     * Falls back to `"unknown"` if the underlying vfile message has no rule ID.
+     */
     rule: string;
-    /** Line number (1-based). */
+    /**
+     * Line number where the issue was detected (1-based).
+     *
+     * @remarks
+     * Line numbers are relative to the content after YAML frontmatter
+     * stripping. Defaults to `1` if the underlying rule does not provide
+     * position information.
+     */
     line: number;
-    /** Column number (1-based). */
+    /**
+     * Column number where the issue was detected (1-based).
+     *
+     * @remarks
+     * Defaults to `1` if the underlying rule does not provide position
+     * information.
+     */
     column: number;
-    /** Human-readable message. */
+    /**
+     * Human-readable description of the lint violation.
+     *
+     * @remarks
+     * Suitable for display in terminal output, editor diagnostics, or
+     * CI annotations. Includes enough context to understand the issue
+     * without referencing the source file.
+     */
     message: string;
 }
 
 /**
- * Create a test layer with pre-configured responses keyed by commit hash.
+ * Create a test layer for {@link GitHubService} with pre-configured responses.
+ *
+ * Returns a `Layer` that resolves commit hashes from the provided `Map`.
+ * Lookups for commits not present in the map fail with a
+ * {@link GitHubApiError}.
+ *
+ * @remarks
+ * This helper is the recommended way to test code that depends on
+ * `GitHubService` without making real API calls. Provide the layer
+ * via `Effect.provide` in your test setup.
+ *
+ * @param responses - A `Map` of full commit hash to {@link GitHubCommitInfo} objects
+ * @returns A `Layer` providing the {@link GitHubService} with deterministic responses
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { GitHubCommitInfo } from "\@savvy-web/changesets";
+ * import { GitHubService, makeGitHubTest } from "\@savvy-web/changesets";
+ *
+ * const responses = new Map<string, GitHubCommitInfo>([
+ *   ["abc1234", { user: "octocat", pull: 42, links: { pull: "#42", user: "\@octocat" } }],
+ * ]);
  *
- * @param responses - A map of commit hash to {@link GitHubCommitInfo}
- * @returns A Layer providing the {@link GitHubService}
+ * const TestGitHub = makeGitHubTest(responses);
+ *
+ * const program = Effect.gen(function* () {
+ *   const github = yield* GitHubService;
+ *   return yield* github.getInfo({ commit: "abc1234", repo: "owner/repo" });
+ * });
+ *
+ * // In a Vitest test:
+ * const result = await Effect.runPromise(program.pipe(Effect.provide(TestGitHub)));
+ * // result.user === "octocat"
+ * ```
  *
  * @public
  */
 export declare function makeGitHubTest(responses: Map<string, GitHubCommitInfo>): Layer.Layer<GitHubService>;
 
 /**
- * Live layer wrapping the remark-pipeline functions.
+ * Production layer for {@link MarkdownService}.
+ *
+ * Wraps the remark-pipeline utility functions (`parseMarkdown` and
+ * `stringifyMarkdown`) in `Effect.sync` for use in Effect programs.
+ * Both operations are synchronous and infallible.
+ *
+ * @remarks
+ * This layer is composed with {@link GitHubLive} in the
+ * `\@savvy-web/changesets/changelog` entry point to form the `MainLayer`
+ * that powers the Changesets API integration.
+ *
+ * @example
+ * ```typescript
+ * import { Effect, Layer } from "effect";
+ * import { MarkdownService, MarkdownLive } from "\@savvy-web/changesets";
+ *
+ * const program = Effect.gen(function* () {
+ *   const md = yield* MarkdownService;
+ *   const tree = yield* md.parse("**bold** text");
+ *   return yield* md.stringify(tree);
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(MarkdownLive)));
+ * ```
  *
  * @public
  */
@@ -659,6 +1889,28 @@ export declare const MarkdownLive: Layer.Layer<MarkdownService, never, never>;
 /**
  * Markdown parsing failure.
  *
+ * @remarks
+ * Raised when a markdown file cannot be parsed into an AST by the unified/remark
+ * pipeline. Carries optional source file location information (line, column)
+ * for diagnostic display.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { MarkdownParseError } from "@savvy-web/changesets";
+ *
+ * declare const program: Effect.Effect<string, MarkdownParseError>;
+ *
+ * const handled = program.pipe(
+ * 	Effect.catchTag("MarkdownParseError", (err) => {
+ * 		console.error(err.message);
+ * 		return Effect.succeed("");
+ * 	}),
+ * );
+ * ```
+ *
+ * @see {@link MarkdownService} for the Effect service that may produce this error
+ *
  * @public
  */
 export declare class MarkdownParseError extends MarkdownParseErrorBase<{
@@ -675,7 +1927,7 @@ export declare class MarkdownParseError extends MarkdownParseErrorBase<{
 }
 
 /**
- * Base class for MarkdownParseError.
+ * Base class for {@link MarkdownParseError}.
  *
  * @privateRemarks
  * This export is required for api-extractor documentation generation.
@@ -689,9 +1941,36 @@ export declare const MarkdownParseErrorBase: new <A extends Record<string, any>
 } & Readonly<A>;
 
 /**
- * Service for markdown parsing and stringification.
+ * Effect service tag for markdown parsing and stringification.
+ *
+ * Provides dependency-injected access to markdown parse/stringify operations.
+ * Use `yield* MarkdownService` inside an `Effect.gen` block to obtain the
+ * service instance.
+ *
+ * @remarks
+ * This tag follows the standard Effect `Context.Tag` pattern. The
+ * {@link MarkdownLive} layer provides the default implementation backed by
+ * the remark/unified pipeline. For testing, you can supply a custom layer
+ * via `Layer.succeed(MarkdownService, { parse: ..., stringify: ... })`.
  *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { MarkdownService, MarkdownLive } from "\@savvy-web/changesets";
+ *
+ * const program = Effect.gen(function* () {
+ *   const md = yield* MarkdownService;
+ *   const tree = yield* md.parse("# Hello\n\nWorld");
+ *   const output = yield* md.stringify(tree);
+ *   console.log(output); // "# Hello\n\nWorld\n"
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(MarkdownLive)));
+ * ```
+ *
+ * @see {@link MarkdownServiceShape} for the service interface
  * @see {@link MarkdownLive} for the production layer
+ * @see {@link MarkdownServiceBase} for the api-extractor base class
  *
  * @public
  */
@@ -713,18 +1992,57 @@ export declare const MarkdownServiceBase: Context.TagClass<MarkdownService, "Mar
 /**
  * Service interface for markdown parsing and stringification.
  *
- * @internal
+ * Describes the two operations a `MarkdownService` implementation must
+ * provide: parsing markdown text into an mdast AST and stringifying an
+ * mdast AST back to markdown text.
+ *
+ * @remarks
+ * Both operations are infallible (no error channel) because the underlying
+ * remark pipeline is configured to handle all valid markdown input. The
+ * `Root` type comes from the `mdast` package and represents the root node
+ * of a markdown abstract syntax tree.
+ *
+ * @public
  */
 export declare interface MarkdownServiceShape {
-    /** Parse a markdown string into an mdast AST. */
+    /**
+     * Parse a markdown string into an mdast abstract syntax tree.
+     *
+     * @param content - Raw markdown text to parse
+     * @returns An `Effect` that resolves to an mdast `Root` node
+     */
     readonly parse: (content: string) => Effect.Effect<Root>;
-    /** Stringify an mdast AST back to markdown. */
+    /**
+     * Stringify an mdast abstract syntax tree back to markdown text.
+     *
+     * @param tree - The mdast `Root` node to serialize
+     * @returns An `Effect` that resolves to a markdown string
+     */
     readonly stringify: (tree: Root) => Effect.Effect<string>;
 }
 
 /**
  * A non-empty string schema.
  *
+ * @remarks
+ * Validates that a string has at least one character. Used as the base
+ * constraint for package names, dependency identifiers, and other fields
+ * that must not be blank.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { NonEmptyString } from "@savvy-web/changesets";
+ *
+ * // Succeeds — non-empty string
+ * const name = Schema.decodeUnknownSync(NonEmptyString)("react");
+ *
+ * // Throws ParseError — empty string
+ * Schema.decodeUnknownSync(NonEmptyString)("");
+ * ```
+ *
+ * @see {@link ChangesetSummarySchema} for a length-bounded variant used for changeset summaries
+ *
  * @public
  */
 export declare const NonEmptyString: Schema.filter<typeof Schema.String>;
@@ -732,6 +2050,28 @@ export declare const NonEmptyString: Schema.filter<typeof Schema.String>;
 /**
  * A positive integer schema.
  *
+ * @remarks
+ * Validates that a number is both an integer and strictly greater than zero.
+ * Used as the base constraint for GitHub issue numbers and similar
+ * identifiers that must be positive whole numbers.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { PositiveInteger } from "@savvy-web/changesets";
+ *
+ * // Succeeds — positive integer
+ * const issueNum = Schema.decodeUnknownSync(PositiveInteger)(42);
+ *
+ * // Throws ParseError — zero is not positive
+ * Schema.decodeUnknownSync(PositiveInteger)(0);
+ *
+ * // Throws ParseError — floats are not integers
+ * Schema.decodeUnknownSync(PositiveInteger)(3.14);
+ * ```
+ *
+ * @see {@link IssueNumberSchema} which builds on this for GitHub issue/PR numbers
+ *
  * @public
  */
 export declare const PositiveInteger: Schema.filter<Schema.filter<typeof Schema.Number>>;
@@ -739,15 +2079,35 @@ export declare const PositiveInteger: Schema.filter<Schema.filter<typeof Schema.
 /**
  * Schema for a GitHub repository in `owner/repo` format.
  *
+ * @remarks
+ * Validates that the string matches the `owner/repository` format used
+ * by GitHub. Both the owner and repository segments accept alphanumeric
+ * characters, dots, underscores, and hyphens.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { RepoSchema } from "@savvy-web/changesets";
+ *
+ * // Succeeds
+ * Schema.decodeUnknownSync(RepoSchema)("microsoft/vscode");
+ *
+ * // Throws ParseError — missing slash
+ * Schema.decodeUnknownSync(RepoSchema)("vscode");
+ * ```
+ *
+ * @see {@link ChangesetOptionsSchema} which uses this for the `repo` field
+ *
  * @public
  */
 export declare const RepoSchema: Schema.filter<typeof Schema.String>;
 
 /**
  * A section category defines how changes are grouped in release notes.
- * Used across all three processing layers.
  *
- * Inferred from {@link SectionCategorySchema}.
+ * @remarks
+ * Inferred from {@link SectionCategorySchema}. Use this type to annotate
+ * variables and parameters that hold category data.
  *
  * @public
  */
@@ -756,9 +2116,34 @@ export declare interface SectionCategory extends Schema.Schema.Type<typeof Secti
 
 /**
  * Schema for a section category that defines how changes are grouped in release notes.
- * Used across all three processing layers.
  *
- * Provides runtime validation and type inference via Effect Schema.
+ * @remarks
+ * A section category has four fields:
+ * - `heading` -- the display heading used in CHANGELOG output (e.g., `"Features"`, `"Bug Fixes"`)
+ * - `priority` -- an integer controlling display order (lower = higher priority)
+ * - `commitTypes` -- conventional commit type prefixes that map to this category (e.g., `["feat"]`)
+ * - `description` -- a brief human-readable description for documentation
+ *
+ * Categories with an empty `commitTypes` array are resolved through other means:
+ * `BREAKING_CHANGES` is resolved via the `!` suffix on any commit type, and
+ * `OTHER` is the fallback for unrecognized types.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { SectionCategorySchema } from "@savvy-web/changesets";
+ * import type { SectionCategory } from "@savvy-web/changesets";
+ *
+ * const category: SectionCategory = Schema.decodeUnknownSync(SectionCategorySchema)({
+ * 	heading: "Features",
+ * 	priority: 2,
+ * 	commitTypes: ["feat"],
+ * 	description: "New functionality",
+ * });
+ * ```
+ *
+ * @see {@link SectionCategory} for the inferred TypeScript type
+ * @see {@link CATEGORIES} for all predefined categories
  *
  * @public
  */
@@ -776,7 +2161,33 @@ export declare const SectionCategorySchema: Schema.Struct<{
 /**
  * Schema accepting either a plain URL or a markdown link `[text](url)`.
  *
- * Used for GitHub API responses from \@changesets/get-github-info.
+ * @remarks
+ * The `\@changesets/get-github-info` vendor module returns links in two
+ * possible formats depending on context: a bare URL string or a markdown
+ * link like `[#42](https://github.com/owner/repo/pull/42)`. This schema
+ * accepts both, validating that the URL portion is parseable by the
+ * `URL` constructor.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { UrlOrMarkdownLinkSchema } from "@savvy-web/changesets";
+ *
+ * // Succeeds — plain URL
+ * Schema.decodeUnknownSync(UrlOrMarkdownLinkSchema)(
+ * 	"https://github.com/owner/repo/pull/42"
+ * );
+ *
+ * // Succeeds — markdown link
+ * Schema.decodeUnknownSync(UrlOrMarkdownLinkSchema)(
+ * 	"[#42](https://github.com/owner/repo/pull/42)"
+ * );
+ *
+ * // Throws ParseError — not a URL or markdown link
+ * Schema.decodeUnknownSync(UrlOrMarkdownLinkSchema)("not-a-url");
+ * ```
+ *
+ * @see {@link GitHubInfoSchema} which uses this for commit, pull, and user links
  *
  * @public
  */
@@ -785,7 +2196,25 @@ export declare const UrlOrMarkdownLinkSchema: Schema.filter<typeof Schema.String
 /**
  * Schema for a GitHub username.
  *
- * Rules: alphanumeric and hyphens, cannot start/end with hyphen.
+ * @remarks
+ * Validates against GitHub's username rules: alphanumeric characters and
+ * hyphens only, cannot start or end with a hyphen. Does not enforce the
+ * 39-character maximum length since GitHub may change that limit.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { UsernameSchema } from "@savvy-web/changesets";
+ *
+ * // Succeeds
+ * Schema.decodeUnknownSync(UsernameSchema)("octocat");
+ * Schema.decodeUnknownSync(UsernameSchema)("my-user-123");
+ *
+ * // Throws ParseError — starts with hyphen
+ * Schema.decodeUnknownSync(UsernameSchema)("-invalid");
+ * ```
+ *
+ * @see {@link GitHubInfoSchema} which uses this for the `user` field
  *
  * @public
  */
@@ -793,12 +2222,43 @@ export declare const UsernameSchema: Schema.filter<typeof Schema.String>;
 
 /**
  * Inferred type for {@link VersionFileConfigSchema}.
+ *
+ * @public
  */
 export declare interface VersionFileConfig extends Schema.Schema.Type<typeof VersionFileConfigSchema> {
 }
 
 /**
  * Schema for a single version file configuration entry.
+ *
+ * @remarks
+ * Each entry specifies a glob pattern that matches one or more JSON files
+ * and an optional array of JSONPath expressions indicating which fields
+ * within those files contain version numbers. When `paths` is omitted,
+ * it defaults to `["$.version"]` at runtime.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { VersionFileConfigSchema } from "@savvy-web/changesets";
+ * import type { VersionFileConfig } from "@savvy-web/changesets";
+ *
+ * const config: VersionFileConfig = Schema.decodeUnknownSync(VersionFileConfigSchema)({
+ * 	glob: "manifest.json",
+ * 	paths: ["$.version", "$.metadata.version"],
+ * });
+ *
+ * // Paths are optional — defaults to ["$.version"] at runtime
+ * const simpleConfig: VersionFileConfig = Schema.decodeUnknownSync(VersionFileConfigSchema)({
+ * 	glob: "**\/deno.json",
+ * });
+ * ```
+ *
+ * @see {@link VersionFileConfig} for the inferred TypeScript type
+ * @see {@link VersionFilesSchema} for the array of entries
+ * @see {@link JsonPathSchema} for JSONPath validation rules
+ *
+ * @public
  */
 export declare const VersionFileConfigSchema: Schema.Struct<{
     /** Glob pattern to match JSON files. */
@@ -810,8 +2270,32 @@ export declare const VersionFileConfigSchema: Schema.Struct<{
 /**
  * Version file update failure.
  *
- * Raised when a JSON file targeted by the `versionFiles` config cannot
- * be read, parsed, or updated at the specified JSONPath.
+ * @remarks
+ * Raised when a JSON file targeted by the `versionFiles` configuration option
+ * cannot be read, parsed, or updated at the specified JSONPath. Common causes
+ * include missing files, invalid JSON, or JSONPath expressions that do not
+ * match any field in the target file.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { VersionFileError } from "@savvy-web/changesets";
+ *
+ * declare const program: Effect.Effect<void, VersionFileError>;
+ *
+ * const handled = program.pipe(
+ * 	Effect.catchTag("VersionFileError", (err) => {
+ * 		console.error(`Failed to update ${err.filePath}: ${err.reason}`);
+ * 		if (err.jsonPath) {
+ * 			console.error(`  at JSONPath: ${err.jsonPath}`);
+ * 		}
+ * 		return Effect.void;
+ * 	}),
+ * );
+ * ```
+ *
+ * @see {@link VersionFilesSchema} for the configuration that drives version file updates
+ * @see {@link JsonPathSchema} for JSONPath expression validation
  *
  * @public
  */
@@ -827,7 +2311,7 @@ export declare class VersionFileError extends VersionFileErrorBase<{
 }
 
 /**
- * Base class for VersionFileError.
+ * Base class for {@link VersionFileError}.
  *
  * @privateRemarks
  * This export is required for api-extractor documentation generation.
@@ -842,6 +2326,26 @@ export declare const VersionFileErrorBase: new <A extends Record<string, any> =
 
 /**
  * Schema for the `versionFiles` array.
+ *
+ * @remarks
+ * An array of {@link VersionFileConfigSchema} entries. Each entry targets
+ * a set of JSON files via glob and specifies which JSONPath expressions
+ * point to version fields that should be updated.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { VersionFilesSchema } from "@savvy-web/changesets";
+ *
+ * const versionFiles = Schema.decodeUnknownSync(VersionFilesSchema)([
+ * 	{ glob: "manifest.json", paths: ["$.version"] },
+ * 	{ glob: "deno.json" },
+ * ]);
+ * ```
+ *
+ * @see {@link ChangesetOptionsSchema} where this is used as an optional field
+ *
+ * @public
  */
 export declare const VersionFilesSchema: Schema.Array$<Schema.Struct<{
     /** Glob pattern to match JSON files. */
@@ -850,9 +2354,40 @@ export declare const VersionFilesSchema: Schema.Array$<Schema.Struct<{
     paths: Schema.optional<Schema.Array$<Schema.filter<typeof Schema.String>>>;
 }>>;
 
+/**
+ * Version string or em dash (U+2014) sentinel for added/removed entries.
+ *
+ * @remarks
+ * Accepts either a semver-like version string (with optional `~` or `^`
+ * prefix and pre-release/build suffixes) or the em dash character `\u2014`
+ * which serves as a sentinel: the "From" column uses `\u2014` for newly
+ * added dependencies, and the "To" column uses it for removed ones.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { VersionOrEmptySchema } from "@savvy-web/changesets";
+ *
+ * // Succeeds — semver version
+ * Schema.decodeUnknownSync(VersionOrEmptySchema)("^3.19.1");
+ *
+ * // Succeeds — em dash sentinel for "no version"
+ * Schema.decodeUnknownSync(VersionOrEmptySchema)("\u2014");
+ *
+ * // Throws ParseError — arbitrary text
+ * Schema.decodeUnknownSync(VersionOrEmptySchema)("latest");
+ * ```
+ *
+ * @public
+ */
+export declare const VersionOrEmptySchema: Schema.filter<typeof Schema.String>;
+
 /**
  * Inferred type for {@link VersionTypeSchema}.
  *
+ * @remarks
+ * One of `"major"`, `"minor"`, `"patch"`, or `"none"`.
+ *
  * @public
  */
 export declare type VersionType = typeof VersionTypeSchema.Type;
@@ -860,6 +2395,22 @@ export declare type VersionType = typeof VersionTypeSchema.Type;
 /**
  * Semantic version bump type.
  *
+ * @remarks
+ * Represents the four possible version bump levels used by Changesets:
+ * - `"major"` -- breaking changes (e.g., 1.x.x to 2.0.0)
+ * - `"minor"` -- new features (e.g., 1.1.x to 1.2.0)
+ * - `"patch"` -- bug fixes (e.g., 1.1.1 to 1.1.2)
+ * - `"none"` -- no version bump (internal changes only)
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { VersionTypeSchema } from "@savvy-web/changesets";
+ * import type { VersionType } from "@savvy-web/changesets";
+ *
+ * const bump: VersionType = Schema.decodeUnknownSync(VersionTypeSchema)("minor");
+ * ```
+ *
  * @public
  */
 export declare const VersionTypeSchema: Schema.Literal<["major", "minor", "patch", "none"]>;