@codluv/versionguard 0.8.0 → 0.9.0

package/dist/cli.js

@@ -1,743 +1,851 @@
 #!/usr/bin/env node
-import * as fs from "node:fs";
+import { $ as generateDependabotConfig, A as createCkmEngine, B as detectManifests, C as suggestNextVersion, D as getVersionFeedback, J as areHooksInstalled, L as getPackageVersion, O as getConfig, S as fixSyncIssues, T as getSyncFeedback, X as uninstallHooks, Y as installHooks, at as isValidCalVerFormat, et as writeDependabotConfig, f as findProjectRoot, i as validate, l as handlePostTag, n as doctor, nt as isChangesetMangled, o as createTag, p as formatNotProjectError, tt as fixChangesetMangling, v as runGuardChecks, w as getChangelogFeedback, y as fixAll, z as setPackageVersion } from "./chunks/src-BPMDUQfR.js";
 import * as path from "node:path";
+import * as fs from "node:fs";
+import * as yaml from "js-yaml";
 import { fileURLToPath } from "node:url";
 import chalk from "chalk";
 import { Command } from "commander";
-import { i as isValidCalVerFormat, c as createCkmEngine, g as getConfig, a as installHooks, b as getPackageVersion, d as getVersionFeedback, v as validate, h as handlePostTag, r as runGuardChecks, e as getSyncFeedback, f as getChangelogFeedback, j as doctor, k as fixAll, l as isChangesetMangled, m as fixChangesetMangling, n as fixSyncIssues, s as suggestNextVersion, o as setPackageVersion, p as createTag, u as uninstallHooks, q as areHooksInstalled, t as findProjectRoot, w as formatNotProjectError } from "./chunks/index-Cipg9sxE.js";
 import * as p from "@clack/prompts";
-import * as yaml from "js-yaml";
-const ckmRaw = '{\n  "$schema": "https://forge-ts.dev/schemas/ckm/v1.json",\n  "version": "1.0.0",\n  "project": "@codluv/versionguard",\n  "generated": "2026-03-26T21:16:11.940Z",\n  "concepts": [\n    {\n      "id": "concept-ManifestConfig",\n      "name": "ManifestConfig",\n      "what": "Configures the version source manifest.",\n      "properties": [\n        {\n          "name": "source",\n          "type": "ManifestSourceType",\n          "description": "Manifest file to read the version from.  Use `\'auto\'` for file-existence detection or a specific filename."\n        },\n        {\n          "name": "path",\n          "type": "string | undefined",\n          "description": "Dotted key path to the version field within the manifest.  For example `\'version\'` for package.json, `\'package.version\'` for Cargo.toml, or `\'project.version\'` for pyproject.toml."\n        },\n        {\n          "name": "regex",\n          "type": "string | undefined",\n          "description": "Regex pattern to extract the version from source-code manifests.  Capture group 1 must contain the version string."\n        }\n      ]\n    },\n    {\n      "id": "concept-SemVerConfig",\n      "name": "SemVerConfig",\n      "what": "Configures SemVer validation rules.",\n      "properties": [\n        {\n          "name": "allowVPrefix",\n          "type": "boolean",\n          "description": "Tolerates a leading `v` prefix (e.g. `v1.2.3`).  When enabled the prefix is stripped before parsing."\n        },\n        {\n          "name": "allowBuildMetadata",\n          "type": "boolean",\n          "description": "Permits `+build` metadata on version strings."\n        },\n        {\n          "name": "requirePrerelease",\n          "type": "boolean",\n          "description": "Requires every version to carry a prerelease label."\n        }\n      ]\n    },\n    {\n      "id": "concept-CalVerConfig",\n      "name": "CalVerConfig",\n      "what": "Configures CalVer validation rules.",\n      "properties": [\n        {\n          "name": "format",\n          "type": "CalVerFormat",\n          "description": "Calendar format used when parsing and validating versions."\n        },\n        {\n          "name": "preventFutureDates",\n          "type": "boolean",\n          "description": "Rejects versions that point to a future date."\n        },\n        {\n          "name": "strictMutualExclusion",\n          "type": "boolean | undefined",\n          "description": "Enforces that week tokens (WW/0W) cannot be mixed with month/day tokens."\n        }\n      ]\n    },\n    {\n      "id": "concept-SyncConfig",\n      "name": "SyncConfig",\n      "what": "Configures files and patterns that should stay in sync with the canonical version.",\n      "properties": [\n        {\n          "name": "files",\n          "type": "string[]",\n          "description": "File globs or paths that should be scanned for version updates."\n        },\n        {\n          "name": "patterns",\n          "type": "SyncPattern[]",\n          "description": "Replacement patterns applied to matching files."\n        }\n      ]\n    },\n    {\n      "id": "concept-ChangelogConfig",\n      "name": "ChangelogConfig",\n      "what": "Controls changelog validation behavior.",\n      "properties": [\n        {\n          "name": "enabled",\n          "type": "boolean",\n          "description": "Enables changelog validation."\n        },\n        {\n          "name": "file",\n          "type": "string",\n          "description": "Path to the changelog file to inspect."\n        },\n        {\n          "name": "strict",\n          "type": "boolean",\n          "description": "Treats changelog problems as hard failures."\n        },\n        {\n          "name": "requireEntry",\n          "type": "boolean",\n          "description": "Requires an entry for the current version."\n        },\n        {\n          "name": "enforceStructure",\n          "type": "boolean | undefined",\n          "description": "Validates that changelog section headers use only allowed names.  When enabled, any `### SectionName` header not present in `sections` is reported as an error."\n        },\n        {\n          "name": "sections",\n          "type": "string[] | undefined",\n          "description": "Allowed Keep a Changelog section names.  Only applied when `enforceStructure` is `true`."\n        }\n      ]\n    },\n    {\n      "id": "concept-GitHooksConfig",\n      "name": "GitHooksConfig",\n      "what": "Toggles each supported git hook integration.",\n      "properties": [\n        {\n          "name": "\'pre-commit\'",\n          "type": "boolean",\n          "description": "Enables validation during the `pre-commit` hook."\n        },\n        {\n          "name": "\'pre-push\'",\n          "type": "boolean",\n          "description": "Enables validation during the `pre-push` hook."\n        },\n        {\n          "name": "\'post-tag\'",\n          "type": "boolean",\n          "description": "Enables follow-up tasks after a tag is created."\n        }\n      ]\n    },\n    {\n      "id": "concept-GitConfig",\n      "name": "GitConfig",\n      "what": "Configures git-related enforcement.",\n      "properties": [\n        {\n          "name": "hooks",\n          "type": "GitHooksConfig",\n          "description": "Hook toggles used by the CLI and validation workflow."\n        },\n        {\n          "name": "enforceHooks",\n          "type": "boolean",\n          "description": "Fails validation when required hooks are missing."\n        }\n      ]\n    },\n    {\n      "id": "concept-VersioningConfig",\n      "name": "VersioningConfig",\n      "what": "Configures the active versioning mode.",\n      "properties": [\n        {\n          "name": "type",\n          "type": "VersioningType",\n          "description": "Versioning strategy used for the project."\n        },\n        {\n          "name": "schemeRules",\n          "type": "SchemeRules | undefined",\n          "description": "Scheme-level validation rules applied regardless of versioning type."\n        },\n        {\n          "name": "semver",\n          "type": "SemVerConfig | undefined",\n          "description": "SemVer-specific settings when `type` is `\'semver\'`."\n        },\n        {\n          "name": "calver",\n          "type": "CalVerConfig | undefined",\n          "description": "CalVer-specific settings when `type` is `\'calver\'`."\n        }\n      ]\n    },\n    {\n      "id": "concept-ScanAllowlistEntry",\n      "name": "ScanAllowlistEntry",\n      "what": "An intentional version reference that should be excluded from scan results.",\n      "properties": [\n        {\n          "name": "file",\n          "type": "string",\n          "description": "Glob pattern matching the file(s) where this reference is intentional."\n        },\n        {\n          "name": "reason",\n          "type": "string | undefined",\n          "description": "Reason this reference is allowed (for documentation / review)."\n        }\n      ]\n    },\n    {\n      "id": "concept-ScanConfig",\n      "name": "ScanConfig",\n      "what": "Configures repo-wide scanning for hardcoded version literals.",\n      "properties": [\n        {\n          "name": "enabled",\n          "type": "boolean",\n          "description": "Enables repo-wide scanning for stale version literals."\n        },\n        {\n          "name": "patterns",\n          "type": "string[]",\n          "description": "Regex patterns that match version-like strings in source files.  Capture group 1 must contain the version string."\n        },\n        {\n          "name": "allowlist",\n          "type": "ScanAllowlistEntry[]",\n          "description": "Files containing intentional version references that should not be flagged."\n        }\n      ]\n    },\n    {\n      "id": "concept-VersionGuardConfig",\n      "name": "VersionGuardConfig",\n      "what": "Top-level configuration consumed by versionguard.",\n      "properties": [\n        {\n          "name": "versioning",\n          "type": "VersioningConfig",\n          "description": "Active versioning settings."\n        },\n        {\n          "name": "manifest",\n          "type": "ManifestConfig",\n          "description": "Version source manifest settings."\n        },\n        {\n          "name": "sync",\n          "type": "SyncConfig",\n          "description": "Synchronization settings for mirrored version strings."\n        },\n        {\n          "name": "changelog",\n          "type": "ChangelogConfig",\n          "description": "Changelog validation settings."\n        },\n        {\n          "name": "git",\n          "type": "GitConfig",\n          "description": "Git enforcement settings."\n        },\n        {\n          "name": "scan",\n          "type": "ScanConfig",\n          "description": "Repo-wide version literal scanning."\n        },\n        {\n          "name": "ignore",\n          "type": "string[]",\n          "description": "Files or patterns excluded from validation."\n        }\n      ]\n    },\n    {\n      "id": "concept-ValidationResult",\n      "name": "ValidationResult",\n      "what": "Result returned by version parsing and validation helpers.",\n      "properties": [\n        {\n          "name": "valid",\n          "type": "boolean",\n          "description": "Indicates whether validation completed without errors."\n        },\n        {\n          "name": "errors",\n          "type": "ValidationError[]",\n          "description": "Collected validation issues."\n        },\n        {\n          "name": "version",\n          "type": "ParsedVersion | undefined",\n          "description": "Parsed version details when validation succeeds."\n        }\n      ]\n    },\n    {\n      "id": "concept-SyncResult",\n      "name": "SyncResult",\n      "what": "Reports the result of synchronizing a single file.",\n      "properties": [\n        {\n          "name": "file",\n          "type": "string",\n          "description": "File that was inspected or updated."\n        },\n        {\n          "name": "updated",\n          "type": "boolean",\n          "description": "Indicates whether the file content changed."\n        },\n        {\n          "name": "changes",\n          "type": "SyncChange[]",\n          "description": "Detailed replacements applied within the file."\n        }\n      ]\n    },\n    {\n      "id": "concept-FullValidationResult",\n      "name": "FullValidationResult",\n      "what": "Combined result from a full project validation run.",\n      "properties": [\n        {\n          "name": "valid",\n          "type": "boolean",\n          "description": "Indicates whether all checks passed."\n        },\n        {\n          "name": "version",\n          "type": "string",\n          "description": "Canonical version string used for validation."\n        },\n        {\n          "name": "versionValid",\n          "type": "boolean",\n          "description": "Indicates whether the root version string is valid."\n        },\n        {\n          "name": "syncValid",\n          "type": "boolean",\n          "description": "Indicates whether synchronized files are in sync."\n        },\n        {\n          "name": "changelogValid",\n          "type": "boolean",\n          "description": "Indicates whether changelog checks passed."\n        },\n        {\n          "name": "errors",\n          "type": "string[]",\n          "description": "Human-readable validation failures collected during the run."\n        }\n      ]\n    },\n    {\n      "id": "concept-ChangelogValidationResult",\n      "name": "ChangelogValidationResult",\n      "what": "Describes the outcome of validating a changelog file.",\n      "properties": [\n        {\n          "name": "valid",\n          "type": "boolean",\n          "description": "Indicates whether the changelog satisfies all requested checks."\n        },\n        {\n          "name": "errors",\n          "type": "string[]",\n          "description": "Human-readable validation errors."\n        },\n        {\n          "name": "hasEntryForVersion",\n          "type": "boolean",\n          "description": "Indicates whether the changelog contains an entry for the requested version."\n        }\n      ]\n    },\n    {\n      "id": "concept-ChangelogStructureOptions",\n      "name": "ChangelogStructureOptions",\n      "what": "Options for changelog structure enforcement.",\n      "properties": [\n        {\n          "name": "enforceStructure",\n          "type": "boolean | undefined",\n          "description": "Validate section headers against an allowed list."\n        },\n        {\n          "name": "sections",\n          "type": "string[] | undefined",\n          "description": "Allowed section names. Defaults to Keep a Changelog standard sections."\n        }\n      ]\n    },\n    {\n      "id": "concept-CkmConfigEntry",\n      "name": "CkmConfigEntry",\n      "what": "A config schema entry with type, description, and default.",\n      "properties": [\n        {\n          "name": "key",\n          "type": "string",\n          "description": "Dotted key path (e.g., `\'CalVerConfig.format\'`)."\n        },\n        {\n          "name": "type",\n          "type": "string",\n          "description": "TypeScript type."\n        },\n        {\n          "name": "description",\n          "type": "string",\n          "description": "Description from TSDoc."\n        },\n        {\n          "name": "default",\n          "type": "string | undefined",\n          "description": "Default value if specified via `@defaultValue`."\n        }\n      ]\n    },\n    {\n      "id": "concept-FeedbackResult",\n      "name": "FeedbackResult",\n      "what": "Aggregates validation errors with suggested next steps.",\n      "properties": [\n        {\n          "name": "valid",\n          "type": "boolean",\n          "description": "Indicates whether the inspected version state is valid."\n        },\n        {\n          "name": "errors",\n          "type": "ValidationError[]",\n          "description": "Validation errors collected during the check."\n        },\n        {\n          "name": "suggestions",\n          "type": "Suggestion[]",\n          "description": "Suggested next steps for resolving the reported issues."\n        },\n        {\n          "name": "canAutoFix",\n          "type": "boolean",\n          "description": "Indicates whether at least one suggestion can be auto-applied."\n        }\n      ]\n    },\n    {\n      "id": "concept-FixResult",\n      "name": "FixResult",\n      "what": "Fix entry point exports for auto-remediation helpers.",\n      "properties": [\n        {\n          "name": "fixed",\n          "type": "boolean",\n          "description": "Indicates whether the operation changed repository state."\n        },\n        {\n          "name": "message",\n          "type": "string",\n          "description": "Human-readable description of the fix attempt."\n        },\n        {\n          "name": "file",\n          "type": "string | undefined",\n          "description": "Absolute path to the file that was updated, when applicable."\n        }\n      ]\n    },\n    {\n      "id": "concept-ProjectRootResult",\n      "name": "ProjectRootResult",\n      "what": "Result of project root detection.",\n      "properties": [\n        {\n          "name": "found",\n          "type": "boolean",\n          "description": "Whether a project root was found."\n        },\n        {\n          "name": "root",\n          "type": "string",\n          "description": "The resolved project root directory, or the original cwd if not found."\n        },\n        {\n          "name": "marker",\n          "type": "string | undefined",\n          "description": "Which marker file was found."\n        },\n        {\n          "name": "hasConfig",\n          "type": "boolean",\n          "description": "Whether the directory has a VersionGuard config."\n        },\n        {\n          "name": "hasGit",\n          "type": "boolean",\n          "description": "Whether the directory is inside a git repository."\n        },\n        {\n          "name": "hasManifest",\n          "type": "boolean",\n          "description": "Whether a version manifest file exists."\n        }\n      ]\n    },\n    {\n      "id": "concept-InitOptions",\n      "name": "InitOptions",\n      "what": "Options for headless (non-interactive) initialization.",\n      "properties": [\n        {\n          "name": "cwd",\n          "type": "string",\n          "description": "Working directory path."\n        },\n        {\n          "name": "type",\n          "type": "\\"semver\\" | \\"calver\\" | undefined",\n          "description": "Versioning type (semver or calver)."\n        },\n        {\n          "name": "format",\n          "type": "string | undefined",\n          "description": "CalVer format string."\n        },\n        {\n          "name": "allowVPrefix",\n          "type": "boolean | undefined",\n          "description": "Allow v-prefix on SemVer versions."\n        },\n        {\n          "name": "allowBuildMetadata",\n          "type": "boolean | undefined",\n          "description": "Allow build metadata on SemVer versions."\n        },\n        {\n          "name": "requirePrerelease",\n          "type": "boolean | undefined",\n          "description": "Require prerelease labels on SemVer versions."\n        },\n        {\n          "name": "manifest",\n          "type": "string | undefined",\n          "description": "Manifest source type."\n        },\n        {\n          "name": "hooks",\n          "type": "boolean | undefined",\n          "description": "Whether to install git hooks."\n        },\n        {\n          "name": "changelog",\n          "type": "boolean | undefined",\n          "description": "Whether to enable changelog validation."\n        },\n        {\n          "name": "yes",\n          "type": "boolean | undefined",\n          "description": "Accept defaults without prompting."\n        },\n        {\n          "name": "force",\n          "type": "boolean | undefined",\n          "description": "Overwrite existing config."\n        }\n      ]\n    }\n  ],\n  "operations": [\n    {\n      "id": "op-validateModifier",\n      "name": "validateModifier",\n      "what": "Validates a pre-release / modifier tag against the allowed modifiers list.",\n      "inputs": [\n        {\n          "name": "modifier",\n          "type": "unknown",\n          "required": true,\n          "description": "Raw modifier string (e.g. `\\"alpha.1\\"`, `\\"rc2\\"`, `\\"dev\\"`)."\n        },\n        {\n          "name": "schemeRules",\n          "type": "unknown",\n          "required": true,\n          "description": "Scheme rules containing the allowed modifiers list."\n        }\n      ],\n      "outputs": {\n        "text": "A validation error when the modifier is disallowed, otherwise `null`."\n      }\n    },\n    {\n      "id": "op-validate",\n      "name": "validate",\n      "what": "Validates a CalVer string against formatting and date rules.",\n      "inputs": [\n        {\n          "name": "version",\n          "type": "unknown",\n          "required": true,\n          "description": "Version string to validate."\n        },\n        {\n          "name": "calverFormat",\n          "type": "unknown",\n          "required": true,\n          "description": "Format expected for the version string."\n        },\n        {\n          "name": "preventFutureDates",\n          "type": "unknown",\n          "required": true,\n          "description": "Whether future dates should be reported as errors."\n        },\n        {\n          "name": "schemeRules",\n          "type": "unknown",\n          "required": true,\n          "description": "Optional scheme rules for modifier validation and segment count warnings."\n        }\n      ],\n      "outputs": {\n        "text": "A validation result containing any discovered errors and the parsed version on success."\n      }\n    },\n    {\n      "id": "op-validateChangelog",\n      "name": "validateChangelog",\n      "what": "Validates a changelog file for release readiness.",\n      "inputs": [\n        {\n          "name": "changelogPath",\n          "type": "unknown",\n          "required": true,\n          "description": "Path to the changelog file."\n        },\n        {\n          "name": "version",\n          "type": "unknown",\n          "required": true,\n          "description": "Version that must be present in the changelog."\n        },\n        {\n          "name": "strict",\n          "type": "unknown",\n          "required": true,\n          "description": "Whether to require compare links and dated release headings."\n        },\n        {\n          "name": "requireEntry",\n          "type": "unknown",\n          "required": true,\n          "description": "Whether the requested version must already have an entry."\n        },\n        {\n          "name": "structure",\n          "type": "unknown",\n          "required": true,\n          "description": "Optional structure enforcement options."\n        }\n      ],\n      "outputs": {\n        "text": "The result of validating the changelog file."\n      }\n    },\n    {\n      "id": "op-createCkmEngine",\n      "name": "createCkmEngine",\n      "what": "Creates a CKM engine from a parsed manifest.",\n      "inputs": [\n        {\n          "name": "manifest",\n          "type": "unknown",\n          "required": true,\n          "description": "Parsed CKM manifest (from forge-ts `ckm.json`)."\n        }\n      ],\n      "outputs": {\n        "text": "A configured CKM engine."\n      }\n    },\n    {\n      "id": "op-checkHardcodedVersions",\n      "name": "checkHardcodedVersions",\n      "what": "Checks configured files for hardcoded version mismatches.",\n      "inputs": [\n        {\n          "name": "expectedVersion",\n          "type": "unknown",\n          "required": true,\n          "description": "Version all matching entries should use."\n        },\n        {\n          "name": "config",\n          "type": "unknown",\n          "required": true,\n          "description": "Sync configuration describing files and replacement patterns."\n        },\n        {\n          "name": "ignorePatterns",\n          "type": "unknown",\n          "required": true,\n          "description": "Glob patterns to exclude while scanning."\n        },\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Project directory used to resolve file globs."\n        }\n      ],\n      "outputs": {\n        "text": "A list of detected version mismatches."\n      }\n    },\n    {\n      "id": "op-generateHookScript",\n      "name": "generateHookScript",\n      "what": "Generates the shell script content for a Git hook.",\n      "inputs": [\n        {\n          "name": "hookName",\n          "type": "unknown",\n          "required": true,\n          "description": "Name of the Git hook to generate."\n        }\n      ],\n      "outputs": {\n        "text": "Executable shell script contents for the hook."\n      }\n    },\n    {\n      "id": "op-checkHooksPathOverride",\n      "name": "checkHooksPathOverride",\n      "what": "Checks whether git hooks have been redirected away from the repository.",\n      "inputs": [\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Repository directory to inspect."\n        }\n      ],\n      "outputs": {\n        "text": "A guard warning when a hooksPath override is detected."\n      }\n    },\n    {\n      "id": "op-checkHuskyBypass",\n      "name": "checkHuskyBypass",\n      "what": "Checks whether the HUSKY environment variable is disabling hooks.",\n      "inputs": [],\n      "outputs": {\n        "text": "A guard warning when the HUSKY bypass is detected."\n      }\n    },\n    {\n      "id": "op-checkHookIntegrity",\n      "name": "checkHookIntegrity",\n      "what": "Verifies that installed hook scripts match the expected content.",\n      "inputs": [\n        {\n          "name": "config",\n          "type": "unknown",\n          "required": true,\n          "description": "VersionGuard configuration that defines which hooks should exist."\n        },\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Repository directory to inspect."\n        }\n      ],\n      "outputs": {\n        "text": "Guard warnings for each hook that has been tampered with."\n      }\n    },\n    {\n      "id": "op-checkEnforceHooksPolicy",\n      "name": "checkEnforceHooksPolicy",\n      "what": "Checks whether hooks are configured as required but not enforced.",\n      "inputs": [\n        {\n          "name": "config",\n          "type": "unknown",\n          "required": true,\n          "description": "VersionGuard configuration to inspect."\n        }\n      ],\n      "outputs": {\n        "text": "A guard warning when hooks are enabled but not enforced."\n      }\n    },\n    {\n      "id": "op-runGuardChecks",\n      "name": "runGuardChecks",\n      "what": "Runs all guard checks and returns a consolidated report.",\n      "inputs": [\n        {\n          "name": "config",\n          "type": "unknown",\n          "required": true,\n          "description": "VersionGuard configuration."\n        },\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Repository directory to inspect."\n        }\n      ],\n      "outputs": {\n        "text": "A guard report with all findings."\n      }\n    },\n    {\n      "id": "op-initConfig",\n      "name": "initConfig",\n      "what": "Initializes a new VersionGuard config file in a project.",\n      "inputs": [\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Project directory where the config should be created."\n        }\n      ],\n      "outputs": {\n        "text": "The path to the created config file."\n      }\n    },\n    {\n      "id": "op-createTag",\n      "name": "createTag",\n      "what": "Creates a release tag and optionally fixes version state first.",\n      "inputs": [\n        {\n          "name": "version",\n          "type": "unknown",\n          "required": true,\n          "description": "Version to embed in the new tag name."\n        },\n        {\n          "name": "message",\n          "type": "unknown",\n          "required": true,\n          "description": "Custom annotated tag message."\n        },\n        {\n          "name": "autoFix",\n          "type": "unknown",\n          "required": true,\n          "description": "Whether to auto-fix version mismatches before tagging."\n        },\n        {\n          "name": "config",\n          "type": "unknown",\n          "required": true,\n          "description": "Loaded VersionGuard configuration used for validation and fixes."\n        },\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Repository directory where git commands should run."\n        }\n      ],\n      "outputs": {\n        "text": "The tagging outcome and any actions performed along the way."\n      }\n    },\n    {\n      "id": "op-validateTagForPush",\n      "name": "validateTagForPush",\n      "what": "Validates that a local tag is safe to push to the default remote.",\n      "inputs": [\n        {\n          "name": "tagName",\n          "type": "unknown",\n          "required": true,\n          "description": "Name of the tag to validate."\n        },\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Repository directory where git commands should run."\n        }\n      ],\n      "outputs": {\n        "text": "A validation result with an optional suggested fix command."\n      }\n    },\n    {\n      "id": "op-validateVersion",\n      "name": "validateVersion",\n      "what": "Validates a version string against the active versioning strategy.",\n      "inputs": [\n        {\n          "name": "version",\n          "type": "unknown",\n          "required": true,\n          "description": "Version string to validate."\n        },\n        {\n          "name": "config",\n          "type": "unknown",\n          "required": true,\n          "description": "VersionGuard configuration that selects the validation rules."\n        }\n      ],\n      "outputs": {\n        "text": "The validation result for the provided version."\n      }\n    },\n    {\n      "id": "op-runWizard",\n      "name": "runWizard",\n      "what": "Runs the interactive setup wizard.",\n      "inputs": [\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Project directory to initialize."\n        }\n      ],\n      "outputs": {\n        "text": "The path to the created config file, or `null` if cancelled."\n      }\n    },\n    {\n      "id": "op-runHeadless",\n      "name": "runHeadless",\n      "what": "Initializes VersionGuard non-interactively using CLI flags.",\n      "inputs": [\n        {\n          "name": "options",\n          "type": "unknown",\n          "required": true,\n          "description": "Headless initialization options."\n        }\n      ],\n      "outputs": {\n        "text": "The path to the created config file."\n      }\n    },\n    {\n      "id": "op-createProgram",\n      "name": "createProgram",\n      "what": "Creates the VersionGuard CLI program definition.",\n      "inputs": [],\n      "outputs": {\n        "text": "A configured Commander program for the VersionGuard CLI."\n      }\n    },\n    {\n      "id": "op-runCli",\n      "name": "runCli",\n      "what": "Parses CLI arguments and executes the matching command.",\n      "inputs": [\n        {\n          "name": "argv",\n          "type": "unknown",\n          "required": true,\n          "description": "Full argument vector to parse."\n        }\n      ]\n    },\n    {\n      "id": "op-createTempProject",\n      "name": "createTempProject",\n      "what": "Creates a temporary project directory with a minimal `package.json` fixture.",\n      "inputs": [],\n      "outputs": {\n        "text": "The absolute path to the temporary project directory."\n      }\n    },\n    {\n      "id": "op-initGitRepo",\n      "name": "initGitRepo",\n      "what": "Initializes a git repository in a fixture directory with a first commit.",\n      "inputs": [\n        {\n          "name": "cwd",\n          "type": "unknown",\n          "required": true,\n          "description": "Absolute path to the fixture repository."\n        }\n      ]\n    },\n    {\n      "id": "op-createBareRemote",\n      "name": "createBareRemote",\n      "what": "Creates a bare git repository to use as a remote in integration tests.",\n      "inputs": [],\n      "outputs": {\n        "text": "The absolute path to the new bare repository."\n      }\n    }\n  ],\n  "constraints": [],\n  "workflows": [],\n  "configSchema": [\n    {\n      "key": "ManifestConfig.source",\n      "type": "ManifestSourceType",\n      "description": "Manifest file to read the version from.  Use `\'auto\'` for file-existence detection or a specific filename.",\n      "default": "\'auto\'"\n    },\n    {\n      "key": "ManifestConfig.path",\n      "type": "string | undefined",\n      "description": "Dotted key path to the version field within the manifest.  For example `\'version\'` for package.json, `\'package.version\'` for Cargo.toml, or `\'project.version\'` for pyproject.toml.",\n      "default": "undefined (uses the provider\'s built-in default)"\n    },\n    {\n      "key": "ManifestConfig.regex",\n      "type": "string | undefined",\n      "description": "Regex pattern to extract the version from source-code manifests.  Capture group 1 must contain the version string.",\n      "default": "undefined"\n    },\n    {\n      "key": "SemVerConfig.allowVPrefix",\n      "type": "boolean",\n      "description": "Tolerates a leading `v` prefix (e.g. `v1.2.3`).  When enabled the prefix is stripped before parsing.",\n      "default": "false"\n    },\n    {\n      "key": "SemVerConfig.allowBuildMetadata",\n      "type": "boolean",\n      "description": "Permits `+build` metadata on version strings.",\n      "default": "true"\n    },\n    {\n      "key": "SemVerConfig.requirePrerelease",\n      "type": "boolean",\n      "description": "Requires every version to carry a prerelease label.",\n      "default": "false"\n    },\n    {\n      "key": "CalVerConfig.format",\n      "type": "CalVerFormat",\n      "description": "Calendar format used when parsing and validating versions."\n    },\n    {\n      "key": "CalVerConfig.preventFutureDates",\n      "type": "boolean",\n      "description": "Rejects versions that point to a future date.",\n      "default": "true"\n    },\n    {\n      "key": "CalVerConfig.strictMutualExclusion",\n      "type": "boolean | undefined",\n      "description": "Enforces that week tokens (WW/0W) cannot be mixed with month/day tokens.",\n      "default": "true"\n    },\n    {\n      "key": "SyncConfig.files",\n      "type": "string[]",\n      "description": "File globs or paths that should be scanned for version updates."\n    },\n    {\n      "key": "SyncConfig.patterns",\n      "type": "SyncPattern[]",\n      "description": "Replacement patterns applied to matching files."\n    },\n    {\n      "key": "ChangelogConfig.enabled",\n      "type": "boolean",\n      "description": "Enables changelog validation.",\n      "default": "false"\n    },\n    {\n      "key": "ChangelogConfig.file",\n      "type": "string",\n      "description": "Path to the changelog file to inspect."\n    },\n    {\n      "key": "ChangelogConfig.strict",\n      "type": "boolean",\n      "description": "Treats changelog problems as hard failures.",\n      "default": "false"\n    },\n    {\n      "key": "ChangelogConfig.requireEntry",\n      "type": "boolean",\n      "description": "Requires an entry for the current version.",\n      "default": "false"\n    },\n    {\n      "key": "ChangelogConfig.enforceStructure",\n      "type": "boolean | undefined",\n      "description": "Validates that changelog section headers use only allowed names.  When enabled, any `### SectionName` header not present in `sections` is reported as an error.",\n      "default": "false"\n    },\n    {\n      "key": "ChangelogConfig.sections",\n      "type": "string[] | undefined",\n      "description": "Allowed Keep a Changelog section names.  Only applied when `enforceStructure` is `true`.",\n      "default": "[\'Added\', \'Changed\', \'Deprecated\', \'Removed\', \'Fixed\', \'Security\']"\n    },\n    {\n      "key": "GitHooksConfig.\'pre-commit\'",\n      "type": "boolean",\n      "description": "Enables validation during the `pre-commit` hook.",\n      "default": "false"\n    },\n    {\n      "key": "GitHooksConfig.\'pre-push\'",\n      "type": "boolean",\n      "description": "Enables validation during the `pre-push` hook.",\n      "default": "false"\n    },\n    {\n      "key": "GitHooksConfig.\'post-tag\'",\n      "type": "boolean",\n      "description": "Enables follow-up tasks after a tag is created.",\n      "default": "false"\n    },\n    {\n      "key": "GitConfig.hooks",\n      "type": "GitHooksConfig",\n      "description": "Hook toggles used by the CLI and validation workflow."\n    },\n    {\n      "key": "GitConfig.enforceHooks",\n      "type": "boolean",\n      "description": "Fails validation when required hooks are missing.",\n      "default": "false"\n    },\n    {\n      "key": "VersioningConfig.type",\n      "type": "VersioningType",\n      "description": "Versioning strategy used for the project."\n    },\n    {\n      "key": "VersioningConfig.schemeRules",\n      "type": "SchemeRules | undefined",\n      "description": "Scheme-level validation rules applied regardless of versioning type.",\n      "default": "`{ maxNumericSegments: 3, allowedModifiers: [\'dev\', \'alpha\', \'beta\', \'rc\'] }`"\n    },\n    {\n      "key": "VersioningConfig.semver",\n      "type": "SemVerConfig | undefined",\n      "description": "SemVer-specific settings when `type` is `\'semver\'`.",\n      "default": "`{ allowVPrefix: false, allowBuildMetadata: true, requirePrerelease: false }`"\n    },\n    {\n      "key": "VersioningConfig.calver",\n      "type": "CalVerConfig | undefined",\n      "description": "CalVer-specific settings when `type` is `\'calver\'`.",\n      "default": "undefined"\n    },\n    {\n      "key": "ScanConfig.enabled",\n      "type": "boolean",\n      "description": "Enables repo-wide scanning for stale version literals.",\n      "default": "false"\n    },\n    {\n      "key": "ScanConfig.patterns",\n      "type": "string[]",\n      "description": "Regex patterns that match version-like strings in source files.  Capture group 1 must contain the version string.",\n      "default": "Patterns matching common version formats in code, CI, and Docker files."\n    },\n    {\n      "key": "ScanConfig.allowlist",\n      "type": "ScanAllowlistEntry[]",\n      "description": "Files containing intentional version references that should not be flagged.",\n      "default": "[]"\n    },\n    {\n      "key": "VersionGuardConfig.versioning",\n      "type": "VersioningConfig",\n      "description": "Active versioning settings."\n    },\n    {\n      "key": "VersionGuardConfig.manifest",\n      "type": "ManifestConfig",\n      "description": "Version source manifest settings.",\n      "default": "`{ source: \'auto\' }`"\n    },\n    {\n      "key": "VersionGuardConfig.sync",\n      "type": "SyncConfig",\n      "description": "Synchronization settings for mirrored version strings."\n    },\n    {\n      "key": "VersionGuardConfig.changelog",\n      "type": "ChangelogConfig",\n      "description": "Changelog validation settings."\n    },\n    {\n      "key": "VersionGuardConfig.git",\n      "type": "GitConfig",\n      "description": "Git enforcement settings."\n    },\n    {\n      "key": "VersionGuardConfig.scan",\n      "type": "ScanConfig",\n      "description": "Repo-wide version literal scanning.",\n      "default": "`{ enabled: false, patterns: [...], allowlist: [] }`"\n    },\n    {\n      "key": "VersionGuardConfig.ignore",\n      "type": "string[]",\n      "description": "Files or patterns excluded from validation."\n    },\n    {\n      "key": "ChangelogStructureOptions.enforceStructure",\n      "type": "boolean | undefined",\n      "description": "Validate section headers against an allowed list."\n    },\n    {\n      "key": "ChangelogStructureOptions.sections",\n      "type": "string[] | undefined",\n      "description": "Allowed section names. Defaults to Keep a Changelog standard sections."\n    },\n    {\n      "key": "CkmConfigEntry.key",\n      "type": "string",\n      "description": "Dotted key path (e.g., `\'CalVerConfig.format\'`)."\n    },\n    {\n      "key": "CkmConfigEntry.type",\n      "type": "string",\n      "description": "TypeScript type."\n    },\n    {\n      "key": "CkmConfigEntry.description",\n      "type": "string",\n      "description": "Description from TSDoc."\n    },\n    {\n      "key": "CkmConfigEntry.default",\n      "type": "string | undefined",\n      "description": "Default value if specified via `@defaultValue`."\n    },\n    {\n      "key": "InitOptions.cwd",\n      "type": "string",\n      "description": "Working directory path."\n    },\n    {\n      "key": "InitOptions.type",\n      "type": "\\"semver\\" | \\"calver\\" | undefined",\n      "description": "Versioning type (semver or calver)."\n    },\n    {\n      "key": "InitOptions.format",\n      "type": "string | undefined",\n      "description": "CalVer format string."\n    },\n    {\n      "key": "InitOptions.allowVPrefix",\n      "type": "boolean | undefined",\n      "description": "Allow v-prefix on SemVer versions."\n    },\n    {\n      "key": "InitOptions.allowBuildMetadata",\n      "type": "boolean | undefined",\n      "description": "Allow build metadata on SemVer versions."\n    },\n    {\n      "key": "InitOptions.requirePrerelease",\n      "type": "boolean | undefined",\n      "description": "Require prerelease labels on SemVer versions."\n    },\n    {\n      "key": "InitOptions.manifest",\n      "type": "string | undefined",\n      "description": "Manifest source type."\n    },\n    {\n      "key": "InitOptions.hooks",\n      "type": "boolean | undefined",\n      "description": "Whether to install git hooks."\n    },\n    {\n      "key": "InitOptions.changelog",\n      "type": "boolean | undefined",\n      "description": "Whether to enable changelog validation."\n    },\n    {\n      "key": "InitOptions.yes",\n      "type": "boolean | undefined",\n      "description": "Accept defaults without prompting."\n    },\n    {\n      "key": "InitOptions.force",\n      "type": "boolean | undefined",\n      "description": "Overwrite existing config."\n    }\n  ]\n}';
-const llmsRaw = "# @codluv/versionguard\n> Strict versioning enforcement for SemVer and CalVer — language-agnostic manifest support, git hooks, changelog validation, and file sync\n> Version: 0.7.0\n\n## Install\n\n```bash\nnpm install -D @codluv/versionguard\n```\n\n## Documentation\n\n- [API Reference](./api-reference.mdx): Full API documentation (MDX)\n- [Full Context](./llms-full.txt): Complete symbol documentation for deep LLM consumption\n\n## Packages\n\n### main\n90 functions, 55 types\n\n- getSemVerConfig() — Resolves the SemVer config from a VersionGuard config.\n- getCalVerConfig() — Extracts the CalVer config from a VersionGuard config, throwing if missing.\n- validateModifier() — Validates a pre-release / modifier tag against the allowed modifiers list.\n- isValidCalVerFormat() — Validates that a CalVer format string is composed of valid tokens and follows structural rules.\n- parseFormat() — Breaks a CalVer format string into its component tokens.\n- getRegexForFormat() — Builds a regular expression that matches a supported CalVer format.\n- parse() — Parses a CalVer string using the supplied format.\n- validate() — Validates a CalVer string against formatting and date rules.\n- format() — Formats a parsed CalVer object back into a version string.\n- getCurrentVersion() — Creates the current CalVer string for a format.\n- compare() — Compares two CalVer strings using a shared format.\n- increment() — Increments a CalVer string.\n- getNextVersions() — Returns the most likely next CalVer candidates.\n- validateChangelog() — Validates a changelog file for release readiness.\n- getLatestVersion() — Gets the most recent released version from a changelog.\n- addVersionEntry() — Inserts a new version entry beneath the `[Unreleased]` section.\n- isChangesetMangled() — Detects whether a changelog has been mangled by Changesets.\n- fixChangesetMangling() — Fixes a Changesets-mangled changelog into proper Keep a Changelog format.\n- createCkmEngine() — Creates a CKM engine from a parsed manifest.\n- parse() — Parses a semantic version string.\n- validate() — Validates that a string is a supported semantic version.\n- compare() — Compares two semantic version strings.\n- gt() — Checks whether one semantic version is greater than another.\n- lt() — Checks whether one semantic version is less than another.\n- eq() — Checks whether two semantic versions are equal in precedence.\n- increment() — Increments a semantic version string by release type.\n- format() — Formats a parsed semantic version object.\n- getVersionFeedback() — Generates actionable feedback for a version string.\n- getSyncFeedback() — Generates suggestions for version sync mismatches in a file.\n- getChangelogFeedback() — Generates suggestions for changelog-related validation issues.\n- getTagFeedback() — Generates suggestions for git tag mismatches.\n- getNestedValue() — Traverses a nested object using a dotted key path.\n- setNestedValue() — Sets a value at a dotted key path, throwing if intermediate segments are missing.\n- escapeRegExp() — Escapes special regex characters in a string for safe use in `new RegExp()`.\n- resolveVersionSource() — Resolves the version source provider for a project.\n- detectManifests() — Detects all manifest files present in a project directory.\n- getPackageJsonPath() — Gets the `package.json` path for a project directory.\n- readPackageJson() — Reads and parses a project's `package.json` file.\n- writePackageJson() — Writes a `package.json` document back to disk.\n- getPackageVersion() — Gets the version string from the project manifest.  When a `manifest` config is provided, uses the configured version source provider (auto-detection or explicit). Falls back to `package.json` for backwards compatibility when no config is provided.\n- setPackageVersion() — Sets the version field in the project manifest.  When a `manifest` config is provided, uses the configured version source provider. Falls back to `package.json` for backwards compatibility when no config is provided.\n- getVersionSource() — Resolves the version source provider for a project.\n- syncVersion() — Synchronizes configured files to a single version string.\n- syncFile() — Synchronizes a single file to a target version.\n- checkHardcodedVersions() — Checks configured files for hardcoded version mismatches.\n- scanRepoForVersions() — Scans the entire repository for hardcoded version literals.\n- fixPackageVersion() — Updates the `package.json` version field when needed.\n- fixSyncIssues() — Synchronizes configured files to the package version.\n- fixChangelog() — Ensures the changelog contains an entry for a version.\n- fixAll() — Runs all configured auto-fix operations.\n- suggestNextVersion() — Suggests candidate next versions for a release.\n- installHooks() — Installs VersionGuard-managed Git hooks in a repository.\n- uninstallHooks() — Removes VersionGuard-managed Git hooks from a repository.\n- findGitDir() — Finds the nearest `.git` directory by walking up from a starting directory.\n- areHooksInstalled() — Checks whether all VersionGuard-managed hooks are installed.\n- generateHookScript() — Generates the shell script content for a Git hook.\n- checkHooksPathOverride() — Checks whether git hooks have been redirected away from the repository.\n- checkHuskyBypass() — Checks whether the HUSKY environment variable is disabling hooks.\n- checkHookIntegrity() — Verifies that installed hook scripts match the expected content.\n- checkEnforceHooksPolicy() — Checks whether hooks are configured as required but not enforced.\n- runGuardChecks() — Runs all guard checks and returns a consolidated report.\n- getDefaultConfig() — Returns a deep-cloned copy of the built-in VersionGuard configuration.\n- findConfig() — Finds the first supported VersionGuard config file in a directory.\n- loadConfig() — Loads a VersionGuard config file from disk.\n- getConfig() — Resolves the active VersionGuard configuration for a project.\n- initConfig() — Initializes a new VersionGuard config file in a project.\n- findProjectRoot() — Walks up from `startDir` to find the nearest project root.\n- formatNotProjectError() — Formats a helpful error message when a command can't find a project.\n- getLatestTag() — Returns the most recent reachable git tag for a repository.\n- getAllTags() — Lists all tags in a repository.\n- createTag() — Creates a release tag and optionally fixes version state first.\n- handlePostTag() — Runs post-tag validation and sync checks.\n- validateTagForPush() — Validates that a local tag is safe to push to the default remote.\n- suggestTagMessage() — Suggests an annotated tag message from changelog content.\n- validateVersion() — Validates a version string against the active versioning strategy.\n- validate() — Validates the current project state against the supplied configuration.\n- doctor() — Runs an extended readiness check for a project.\n- sync() — Synchronizes configured files to the current package version.\n- canBump() — Determines whether a project can move from one version to another.\n- runWizard() — Runs the interactive setup wizard.\n- runHeadless() — Initializes VersionGuard non-interactively using CLI flags.\n- createProgram() — Creates the VersionGuard CLI program definition.\n- runCli() — Parses CLI arguments and executes the matching command.\n- shouldRunCli() — Determines whether the current module is the invoked CLI entry point.\n- createTempProject() — Creates a temporary project directory with a minimal `package.json` fixture.\n- initGitRepo() — Initializes a git repository in a fixture directory with a first commit.\n- writeTextFile() — Writes a text fixture file relative to a temporary project directory.\n- createBareRemote() — Creates a bare git repository to use as a remote in integration tests.\n- addGitRemote() — Adds a local bare repository as the `origin` remote for a fixture repo.\n- commitAll() — Stages all changes and creates a commit in a fixture repository.\n\n- VersioningType — Supported versioning strategies.\n- ManifestSourceType — Supported manifest source types for version extraction.\n- ManifestConfig — Configures the version source manifest.\n- CalVerToken — Valid CalVer token names for building format strings.\n- CalVerFormat — A CalVer format string composed of dot-separated tokens.\n- SchemeRules — Configures scheme-level validation rules applied regardless of versioning type.\n- SemVerConfig — Configures SemVer validation rules.\n- CalVerConfig — Configures CalVer validation rules.\n- SyncPattern — Describes a search-and-replace pattern used during version synchronization.\n- SyncConfig — Configures files and patterns that should stay in sync with the canonical version.\n- ChangelogConfig — Controls changelog validation behavior.\n- GitHooksConfig — Toggles each supported git hook integration.\n- GitConfig — Configures git-related enforcement.\n- VersioningConfig — Configures the active versioning mode.\n- ScanAllowlistEntry — An intentional version reference that should be excluded from scan results.\n- ScanConfig — Configures repo-wide scanning for hardcoded version literals.\n- VersionGuardConfig — Top-level configuration consumed by versionguard.\n- SemVer — Parsed semantic version components.\n- CalVer — Parsed calendar version components.\n- ParsedSemVer — Parsed semantic version result wrapper.\n- ParsedCalVer — Parsed calendar version result wrapper.\n- ParsedVersion — Union of supported parsed version payloads.\n- ValidationError — Describes a single validation problem.\n- ValidationResult — Result returned by version parsing and validation helpers.\n- SyncChange — Describes a single in-file version replacement.\n- SyncResult — Reports the result of synchronizing a single file.\n- VersionMismatch — Reports a discovered version mismatch.\n- FullValidationResult — Combined result from a full project validation run.\n- DoctorReport — Reports whether a project is ready to pass VersionGuard checks.\n- ParsedCalVerFormat — Parsed token layout for a supported CalVer format string.\n- ChangelogValidationResult — Describes the outcome of validating a changelog file.\n- ChangelogStructureOptions — Options for changelog structure enforcement.\n- CkmConcept — A domain concept extracted from an exported interface or type.\n- CkmProperty — A property within a concept.\n- CkmOperation — A user-facing operation extracted from an exported function.\n- CkmInput — A function parameter within an operation.\n- CkmConstraint — A constraint enforced by the tool.\n- CkmWorkflow — A multi-step workflow for a common goal.\n- CkmConfigEntry — A config schema entry with type, description, and default.\n- CkmManifest — The complete Codebase Knowledge Manifest.\n- CkmTopic — An auto-generated topic derived from CKM data.\n- CkmEngine — The CKM engine — provides topic derivation, filtering, and output formatting.\n- Suggestion — Feedback entry point exports for suggestion and guidance helpers.\n- FeedbackResult — Aggregates validation errors with suggested next steps.\n- VersionSourceProvider — Abstraction for reading and writing a version string from any manifest format.\n- PackageJsonValue — JSON-compatible scalar, array, or object value used by package metadata.\n- PackageJsonArray — Recursive array type used for arbitrary JSON-compatible package values.\n- PackageJsonObject — Recursive object type used for arbitrary JSON-compatible package values.\n- PackageJson — Minimal shape of a `package.json` document used by VersionGuard.\n- FixResult — Fix entry point exports for auto-remediation helpers.\n- GuardWarning — Describes a single guard finding.\n- GuardReport — Result of a full guard check pass.\n- ProjectRootResult — Result of project root detection.\n- TagInfo — Tag entry point exports for release-tag management helpers.\n- InitOptions — Options for headless (non-interactive) initialization.\n";
+//#region docs/ckm.json?raw
+var ckm_default = "{\n  \"$schema\": \"https://forge-ts.dev/schemas/ckm/v1.json\",\n  \"version\": \"1.0.0\",\n  \"project\": \"@codluv/versionguard\",\n  \"generated\": \"2026-03-26T22:14:21.976Z\",\n  \"concepts\": [\n    {\n      \"id\": \"concept-ManifestConfig\",\n      \"name\": \"ManifestConfig\",\n      \"what\": \"Configures the version source manifest.\",\n      \"properties\": [\n        {\n          \"name\": \"source\",\n          \"type\": \"ManifestSourceType\",\n          \"description\": \"Manifest file to read the version from.  Use `'auto'` for file-existence detection or a specific filename.\"\n        },\n        {\n          \"name\": \"path\",\n          \"type\": \"string | undefined\",\n          \"description\": \"Dotted key path to the version field within the manifest.  For example `'version'` for package.json, `'package.version'` for Cargo.toml, or `'project.version'` for pyproject.toml.\"\n        },\n        {\n          \"name\": \"regex\",\n          \"type\": \"string | undefined\",\n          \"description\": \"Regex pattern to extract the version from source-code manifests.  Capture group 1 must contain the version string.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-SemVerConfig\",\n      \"name\": \"SemVerConfig\",\n      \"what\": \"Configures SemVer validation rules.\",\n      \"properties\": [\n        {\n          \"name\": \"allowVPrefix\",\n          \"type\": \"boolean\",\n          \"description\": \"Tolerates a leading `v` prefix (e.g. `v1.2.3`).  When enabled the prefix is stripped before parsing.\"\n        },\n        {\n          \"name\": \"allowBuildMetadata\",\n          \"type\": \"boolean\",\n          \"description\": \"Permits `+build` metadata on version strings.\"\n        },\n        {\n          \"name\": \"requirePrerelease\",\n          \"type\": \"boolean\",\n          \"description\": \"Requires every version to carry a prerelease label.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-CalVerConfig\",\n      \"name\": \"CalVerConfig\",\n      \"what\": \"Configures CalVer validation rules.\",\n      \"properties\": [\n        {\n          \"name\": \"format\",\n          \"type\": \"CalVerFormat\",\n          \"description\": \"Calendar format used when parsing and validating versions.\"\n        },\n        {\n          \"name\": \"preventFutureDates\",\n          \"type\": \"boolean\",\n          \"description\": \"Rejects versions that point to a future date.\"\n        },\n        {\n          \"name\": \"strictMutualExclusion\",\n          \"type\": \"boolean | undefined\",\n          \"description\": \"Enforces that week tokens (WW/0W) cannot be mixed with month/day tokens.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-SyncConfig\",\n      \"name\": \"SyncConfig\",\n      \"what\": \"Configures files and patterns that should stay in sync with the canonical version.\",\n      \"properties\": [\n        {\n          \"name\": \"files\",\n          \"type\": \"string[]\",\n          \"description\": \"File globs or paths that should be scanned for version updates.\"\n        },\n        {\n          \"name\": \"patterns\",\n          \"type\": \"SyncPattern[]\",\n          \"description\": \"Replacement patterns applied to matching files.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-ChangelogConfig\",\n      \"name\": \"ChangelogConfig\",\n      \"what\": \"Controls changelog validation behavior.\",\n      \"properties\": [\n        {\n          \"name\": \"enabled\",\n          \"type\": \"boolean\",\n          \"description\": \"Enables changelog validation.\"\n        },\n        {\n          \"name\": \"file\",\n          \"type\": \"string\",\n          \"description\": \"Path to the changelog file to inspect.\"\n        },\n        {\n          \"name\": \"strict\",\n          \"type\": \"boolean\",\n          \"description\": \"Treats changelog problems as hard failures.\"\n        },\n        {\n          \"name\": \"requireEntry\",\n          \"type\": \"boolean\",\n          \"description\": \"Requires an entry for the current version.\"\n        },\n        {\n          \"name\": \"enforceStructure\",\n          \"type\": \"boolean | undefined\",\n          \"description\": \"Validates that changelog section headers use only allowed names.  When enabled, any `### SectionName` header not present in `sections` is reported as an error.\"\n        },\n        {\n          \"name\": \"sections\",\n          \"type\": \"string[] | undefined\",\n          \"description\": \"Allowed Keep a Changelog section names.  Only applied when `enforceStructure` is `true`.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-GitHooksConfig\",\n      \"name\": \"GitHooksConfig\",\n      \"what\": \"Toggles each supported git hook integration.\",\n      \"properties\": [\n        {\n          \"name\": \"'pre-commit'\",\n          \"type\": \"boolean\",\n          \"description\": \"Enables validation during the `pre-commit` hook.\"\n        },\n        {\n          \"name\": \"'pre-push'\",\n          \"type\": \"boolean\",\n          \"description\": \"Enables validation during the `pre-push` hook.\"\n        },\n        {\n          \"name\": \"'post-tag'\",\n          \"type\": \"boolean\",\n          \"description\": \"Enables follow-up tasks after a tag is created.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-GitConfig\",\n      \"name\": \"GitConfig\",\n      \"what\": \"Configures git-related enforcement.\",\n      \"properties\": [\n        {\n          \"name\": \"hooks\",\n          \"type\": \"GitHooksConfig\",\n          \"description\": \"Hook toggles used by the CLI and validation workflow.\"\n        },\n        {\n          \"name\": \"enforceHooks\",\n          \"type\": \"boolean\",\n          \"description\": \"Fails validation when required hooks are missing.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-GitHubConfig\",\n      \"name\": \"GitHubConfig\",\n      \"what\": \"Configures GitHub-specific integration features.\",\n      \"properties\": [\n        {\n          \"name\": \"dependabot\",\n          \"type\": \"boolean\",\n          \"description\": \"Generates `.github/dependabot.yml` from detected manifests during init.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-VersioningConfig\",\n      \"name\": \"VersioningConfig\",\n      \"what\": \"Configures the active versioning mode.\",\n      \"properties\": [\n        {\n          \"name\": \"type\",\n          \"type\": \"VersioningType\",\n          \"description\": \"Versioning strategy used for the project.\"\n        },\n        {\n          \"name\": \"schemeRules\",\n          \"type\": \"SchemeRules | undefined\",\n          \"description\": \"Scheme-level validation rules applied regardless of versioning type.\"\n        },\n        {\n          \"name\": \"semver\",\n          \"type\": \"SemVerConfig | undefined\",\n          \"description\": \"SemVer-specific settings when `type` is `'semver'`.\"\n        },\n        {\n          \"name\": \"calver\",\n          \"type\": \"CalVerConfig | undefined\",\n          \"description\": \"CalVer-specific settings when `type` is `'calver'`.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-ScanAllowlistEntry\",\n      \"name\": \"ScanAllowlistEntry\",\n      \"what\": \"An intentional version reference that should be excluded from scan results.\",\n      \"properties\": [\n        {\n          \"name\": \"file\",\n          \"type\": \"string\",\n          \"description\": \"Glob pattern matching the file(s) where this reference is intentional.\"\n        },\n        {\n          \"name\": \"reason\",\n          \"type\": \"string | undefined\",\n          \"description\": \"Reason this reference is allowed (for documentation / review).\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-ScanConfig\",\n      \"name\": \"ScanConfig\",\n      \"what\": \"Configures repo-wide scanning for hardcoded version literals.\",\n      \"properties\": [\n        {\n          \"name\": \"enabled\",\n          \"type\": \"boolean\",\n          \"description\": \"Enables repo-wide scanning for stale version literals.\"\n        },\n        {\n          \"name\": \"patterns\",\n          \"type\": \"string[]\",\n          \"description\": \"Regex patterns that match version-like strings in source files.  Capture group 1 must contain the version string.\"\n        },\n        {\n          \"name\": \"allowlist\",\n          \"type\": \"ScanAllowlistEntry[]\",\n          \"description\": \"Files containing intentional version references that should not be flagged.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-VersionGuardConfig\",\n      \"name\": \"VersionGuardConfig\",\n      \"what\": \"Top-level configuration consumed by versionguard.\",\n      \"properties\": [\n        {\n          \"name\": \"versioning\",\n          \"type\": \"VersioningConfig\",\n          \"description\": \"Active versioning settings.\"\n        },\n        {\n          \"name\": \"manifest\",\n          \"type\": \"ManifestConfig\",\n          \"description\": \"Version source manifest settings.\"\n        },\n        {\n          \"name\": \"sync\",\n          \"type\": \"SyncConfig\",\n          \"description\": \"Synchronization settings for mirrored version strings.\"\n        },\n        {\n          \"name\": \"changelog\",\n          \"type\": \"ChangelogConfig\",\n          \"description\": \"Changelog validation settings.\"\n        },\n        {\n          \"name\": \"git\",\n          \"type\": \"GitConfig\",\n          \"description\": \"Git enforcement settings.\"\n        },\n        {\n          \"name\": \"github\",\n          \"type\": \"GitHubConfig\",\n          \"description\": \"GitHub integration settings.\"\n        },\n        {\n          \"name\": \"scan\",\n          \"type\": \"ScanConfig\",\n          \"description\": \"Repo-wide version literal scanning.\"\n        },\n        {\n          \"name\": \"ignore\",\n          \"type\": \"string[]\",\n          \"description\": \"Files or patterns excluded from validation.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-ValidationResult\",\n      \"name\": \"ValidationResult\",\n      \"what\": \"Result returned by version parsing and validation helpers.\",\n      \"properties\": [\n        {\n          \"name\": \"valid\",\n          \"type\": \"boolean\",\n          \"description\": \"Indicates whether validation completed without errors.\"\n        },\n        {\n          \"name\": \"errors\",\n          \"type\": \"ValidationError[]\",\n          \"description\": \"Collected validation issues.\"\n        },\n        {\n          \"name\": \"version\",\n          \"type\": \"ParsedVersion | undefined\",\n          \"description\": \"Parsed version details when validation succeeds.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-SyncResult\",\n      \"name\": \"SyncResult\",\n      \"what\": \"Reports the result of synchronizing a single file.\",\n      \"properties\": [\n        {\n          \"name\": \"file\",\n          \"type\": \"string\",\n          \"description\": \"File that was inspected or updated.\"\n        },\n        {\n          \"name\": \"updated\",\n          \"type\": \"boolean\",\n          \"description\": \"Indicates whether the file content changed.\"\n        },\n        {\n          \"name\": \"changes\",\n          \"type\": \"SyncChange[]\",\n          \"description\": \"Detailed replacements applied within the file.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-FullValidationResult\",\n      \"name\": \"FullValidationResult\",\n      \"what\": \"Combined result from a full project validation run.\",\n      \"properties\": [\n        {\n          \"name\": \"valid\",\n          \"type\": \"boolean\",\n          \"description\": \"Indicates whether all checks passed.\"\n        },\n        {\n          \"name\": \"version\",\n          \"type\": \"string\",\n          \"description\": \"Canonical version string used for validation.\"\n        },\n        {\n          \"name\": \"versionValid\",\n          \"type\": \"boolean\",\n          \"description\": \"Indicates whether the root version string is valid.\"\n        },\n        {\n          \"name\": \"syncValid\",\n          \"type\": \"boolean\",\n          \"description\": \"Indicates whether synchronized files are in sync.\"\n        },\n        {\n          \"name\": \"changelogValid\",\n          \"type\": \"boolean\",\n          \"description\": \"Indicates whether changelog checks passed.\"\n        },\n        {\n          \"name\": \"errors\",\n          \"type\": \"string[]\",\n          \"description\": \"Human-readable validation failures collected during the run.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-ChangelogValidationResult\",\n      \"name\": \"ChangelogValidationResult\",\n      \"what\": \"Describes the outcome of validating a changelog file.\",\n      \"properties\": [\n        {\n          \"name\": \"valid\",\n          \"type\": \"boolean\",\n          \"description\": \"Indicates whether the changelog satisfies all requested checks.\"\n        },\n        {\n          \"name\": \"errors\",\n          \"type\": \"string[]\",\n          \"description\": \"Human-readable validation errors.\"\n        },\n        {\n          \"name\": \"hasEntryForVersion\",\n          \"type\": \"boolean\",\n          \"description\": \"Indicates whether the changelog contains an entry for the requested version.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-ChangelogStructureOptions\",\n      \"name\": \"ChangelogStructureOptions\",\n      \"what\": \"Options for changelog structure enforcement.\",\n      \"properties\": [\n        {\n          \"name\": \"enforceStructure\",\n          \"type\": \"boolean | undefined\",\n          \"description\": \"Validate section headers against an allowed list.\"\n        },\n        {\n          \"name\": \"sections\",\n          \"type\": \"string[] | undefined\",\n          \"description\": \"Allowed section names. Defaults to Keep a Changelog standard sections.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-CkmConfigEntry\",\n      \"name\": \"CkmConfigEntry\",\n      \"what\": \"A config schema entry with type, description, and default.\",\n      \"properties\": [\n        {\n          \"name\": \"key\",\n          \"type\": \"string\",\n          \"description\": \"Dotted key path (e.g., `'CalVerConfig.format'`).\"\n        },\n        {\n          \"name\": \"type\",\n          \"type\": \"string\",\n          \"description\": \"TypeScript type.\"\n        },\n        {\n          \"name\": \"description\",\n          \"type\": \"string\",\n          \"description\": \"Description from TSDoc.\"\n        },\n        {\n          \"name\": \"default\",\n          \"type\": \"string | undefined\",\n          \"description\": \"Default value if specified via `@defaultValue`.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-FeedbackResult\",\n      \"name\": \"FeedbackResult\",\n      \"what\": \"Aggregates validation errors with suggested next steps.\",\n      \"properties\": [\n        {\n          \"name\": \"valid\",\n          \"type\": \"boolean\",\n          \"description\": \"Indicates whether the inspected version state is valid.\"\n        },\n        {\n          \"name\": \"errors\",\n          \"type\": \"ValidationError[]\",\n          \"description\": \"Validation errors collected during the check.\"\n        },\n        {\n          \"name\": \"suggestions\",\n          \"type\": \"Suggestion[]\",\n          \"description\": \"Suggested next steps for resolving the reported issues.\"\n        },\n        {\n          \"name\": \"canAutoFix\",\n          \"type\": \"boolean\",\n          \"description\": \"Indicates whether at least one suggestion can be auto-applied.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-FixResult\",\n      \"name\": \"FixResult\",\n      \"what\": \"Fix entry point exports for auto-remediation helpers.\",\n      \"properties\": [\n        {\n          \"name\": \"fixed\",\n          \"type\": \"boolean\",\n          \"description\": \"Indicates whether the operation changed repository state.\"\n        },\n        {\n          \"name\": \"message\",\n          \"type\": \"string\",\n          \"description\": \"Human-readable description of the fix attempt.\"\n        },\n        {\n          \"name\": \"file\",\n          \"type\": \"string | undefined\",\n          \"description\": \"Absolute path to the file that was updated, when applicable.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-ProjectRootResult\",\n      \"name\": \"ProjectRootResult\",\n      \"what\": \"Result of project root detection.\",\n      \"properties\": [\n        {\n          \"name\": \"found\",\n          \"type\": \"boolean\",\n          \"description\": \"Whether a project root was found.\"\n        },\n        {\n          \"name\": \"root\",\n          \"type\": \"string\",\n          \"description\": \"The resolved project root directory, or the original cwd if not found.\"\n        },\n        {\n          \"name\": \"marker\",\n          \"type\": \"string | undefined\",\n          \"description\": \"Which marker file was found.\"\n        },\n        {\n          \"name\": \"hasConfig\",\n          \"type\": \"boolean\",\n          \"description\": \"Whether the directory has a VersionGuard config.\"\n        },\n        {\n          \"name\": \"hasGit\",\n          \"type\": \"boolean\",\n          \"description\": \"Whether the directory is inside a git repository.\"\n        },\n        {\n          \"name\": \"hasManifest\",\n          \"type\": \"boolean\",\n          \"description\": \"Whether a version manifest file exists.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"concept-InitOptions\",\n      \"name\": \"InitOptions\",\n      \"what\": \"Options for headless (non-interactive) initialization.\",\n      \"properties\": [\n        {\n          \"name\": \"cwd\",\n          \"type\": \"string\",\n          \"description\": \"Working directory path.\"\n        },\n        {\n          \"name\": \"type\",\n          \"type\": \"\\\"semver\\\" | \\\"calver\\\" | undefined\",\n          \"description\": \"Versioning type (semver or calver).\"\n        },\n        {\n          \"name\": \"format\",\n          \"type\": \"string | undefined\",\n          \"description\": \"CalVer format string.\"\n        },\n        {\n          \"name\": \"allowVPrefix\",\n          \"type\": \"boolean | undefined\",\n          \"description\": \"Allow v-prefix on SemVer versions.\"\n        },\n        {\n          \"name\": \"allowBuildMetadata\",\n          \"type\": \"boolean | undefined\",\n          \"description\": \"Allow build metadata on SemVer versions.\"\n        },\n        {\n          \"name\": \"requirePrerelease\",\n          \"type\": \"boolean | undefined\",\n          \"description\": \"Require prerelease labels on SemVer versions.\"\n        },\n        {\n          \"name\": \"manifest\",\n          \"type\": \"string | undefined\",\n          \"description\": \"Manifest source type.\"\n        },\n        {\n          \"name\": \"github\",\n          \"type\": \"boolean | undefined\",\n          \"description\": \"Whether to generate GitHub integration files (dependabot.yml).\"\n        },\n        {\n          \"name\": \"hooks\",\n          \"type\": \"boolean | undefined\",\n          \"description\": \"Whether to install git hooks.\"\n        },\n        {\n          \"name\": \"changelog\",\n          \"type\": \"boolean | undefined\",\n          \"description\": \"Whether to enable changelog validation.\"\n        },\n        {\n          \"name\": \"yes\",\n          \"type\": \"boolean | undefined\",\n          \"description\": \"Accept defaults without prompting.\"\n        },\n        {\n          \"name\": \"force\",\n          \"type\": \"boolean | undefined\",\n          \"description\": \"Overwrite existing config.\"\n        }\n      ]\n    }\n  ],\n  \"operations\": [\n    {\n      \"id\": \"op-validateModifier\",\n      \"name\": \"validateModifier\",\n      \"what\": \"Validates a pre-release / modifier tag against the allowed modifiers list.\",\n      \"inputs\": [\n        {\n          \"name\": \"modifier\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Raw modifier string (e.g. `\\\"alpha.1\\\"`, `\\\"rc2\\\"`, `\\\"dev\\\"`).\"\n        },\n        {\n          \"name\": \"schemeRules\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Scheme rules containing the allowed modifiers list.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"A validation error when the modifier is disallowed, otherwise `null`.\"\n      }\n    },\n    {\n      \"id\": \"op-validate\",\n      \"name\": \"validate\",\n      \"what\": \"Validates a CalVer string against formatting and date rules.\",\n      \"inputs\": [\n        {\n          \"name\": \"version\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Version string to validate.\"\n        },\n        {\n          \"name\": \"calverFormat\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Format expected for the version string.\"\n        },\n        {\n          \"name\": \"preventFutureDates\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Whether future dates should be reported as errors.\"\n        },\n        {\n          \"name\": \"schemeRules\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Optional scheme rules for modifier validation and segment count warnings.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"A validation result containing any discovered errors and the parsed version on success.\"\n      }\n    },\n    {\n      \"id\": \"op-validateChangelog\",\n      \"name\": \"validateChangelog\",\n      \"what\": \"Validates a changelog file for release readiness.\",\n      \"inputs\": [\n        {\n          \"name\": \"changelogPath\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Path to the changelog file.\"\n        },\n        {\n          \"name\": \"version\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Version that must be present in the changelog.\"\n        },\n        {\n          \"name\": \"strict\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Whether to require compare links and dated release headings.\"\n        },\n        {\n          \"name\": \"requireEntry\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Whether the requested version must already have an entry.\"\n        },\n        {\n          \"name\": \"structure\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Optional structure enforcement options.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"The result of validating the changelog file.\"\n      }\n    },\n    {\n      \"id\": \"op-createCkmEngine\",\n      \"name\": \"createCkmEngine\",\n      \"what\": \"Creates a CKM engine from a parsed manifest.\",\n      \"inputs\": [\n        {\n          \"name\": \"manifest\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Parsed CKM manifest (from forge-ts `ckm.json`).\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"A configured CKM engine.\"\n      }\n    },\n    {\n      \"id\": \"op-checkHardcodedVersions\",\n      \"name\": \"checkHardcodedVersions\",\n      \"what\": \"Checks configured files for hardcoded version mismatches.\",\n      \"inputs\": [\n        {\n          \"name\": \"expectedVersion\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Version all matching entries should use.\"\n        },\n        {\n          \"name\": \"config\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Sync configuration describing files and replacement patterns.\"\n        },\n        {\n          \"name\": \"ignorePatterns\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Glob patterns to exclude while scanning.\"\n        },\n        {\n          \"name\": \"cwd\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Project directory used to resolve file globs.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"A list of detected version mismatches.\"\n      }\n    },\n    {\n      \"id\": \"op-generateHookScript\",\n      \"name\": \"generateHookScript\",\n      \"what\": \"Generates the shell script content for a Git hook.\",\n      \"inputs\": [\n        {\n          \"name\": \"hookName\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Name of the Git hook to generate.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"Executable shell script contents for the hook.\"\n      }\n    },\n    {\n      \"id\": \"op-checkHooksPathOverride\",\n      \"name\": \"checkHooksPathOverride\",\n      \"what\": \"Checks whether git hooks have been redirected away from the repository.\",\n      \"inputs\": [\n        {\n          \"name\": \"cwd\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Repository directory to inspect.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"A guard warning when a hooksPath override is detected.\"\n      }\n    },\n    {\n      \"id\": \"op-checkHuskyBypass\",\n      \"name\": \"checkHuskyBypass\",\n      \"what\": \"Checks whether the HUSKY environment variable is disabling hooks.\",\n      \"inputs\": [],\n      \"outputs\": {\n        \"text\": \"A guard warning when the HUSKY bypass is detected.\"\n      }\n    },\n    {\n      \"id\": \"op-checkHookIntegrity\",\n      \"name\": \"checkHookIntegrity\",\n      \"what\": \"Verifies that installed hook scripts match the expected content.\",\n      \"inputs\": [\n        {\n          \"name\": \"config\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"VersionGuard configuration that defines which hooks should exist.\"\n        },\n        {\n          \"name\": \"cwd\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Repository directory to inspect.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"Guard warnings for each hook that has been tampered with.\"\n      }\n    },\n    {\n      \"id\": \"op-checkEnforceHooksPolicy\",\n      \"name\": \"checkEnforceHooksPolicy\",\n      \"what\": \"Checks whether hooks are configured as required but not enforced.\",\n      \"inputs\": [\n        {\n          \"name\": \"config\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"VersionGuard configuration to inspect.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"A guard warning when hooks are enabled but not enforced.\"\n      }\n    },\n    {\n      \"id\": \"op-runGuardChecks\",\n      \"name\": \"runGuardChecks\",\n      \"what\": \"Runs all guard checks and returns a consolidated report.\",\n      \"inputs\": [\n        {\n          \"name\": \"config\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"VersionGuard configuration.\"\n        },\n        {\n          \"name\": \"cwd\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Repository directory to inspect.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"A guard report with all findings.\"\n      }\n    },\n    {\n      \"id\": \"op-generateDependabotConfig\",\n      \"name\": \"generateDependabotConfig\",\n      \"what\": \"Generates Dependabot YAML configuration from detected manifests.\",\n      \"inputs\": [\n        {\n          \"name\": \"manifests\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Detected manifest source types from the project.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"The Dependabot configuration as a YAML string.\"\n      }\n    },\n    {\n      \"id\": \"op-initConfig\",\n      \"name\": \"initConfig\",\n      \"what\": \"Initializes a new VersionGuard config file in a project.\",\n      \"inputs\": [\n        {\n          \"name\": \"cwd\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Project directory where the config should be created.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"The path to the created config file.\"\n      }\n    },\n    {\n      \"id\": \"op-createTag\",\n      \"name\": \"createTag\",\n      \"what\": \"Creates a release tag and optionally fixes version state first.\",\n      \"inputs\": [\n        {\n          \"name\": \"version\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Version to embed in the new tag name.\"\n        },\n        {\n          \"name\": \"message\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Custom annotated tag message.\"\n        },\n        {\n          \"name\": \"autoFix\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Whether to auto-fix version mismatches before tagging.\"\n        },\n        {\n          \"name\": \"config\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Loaded VersionGuard configuration used for validation and fixes.\"\n        },\n        {\n          \"name\": \"cwd\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Repository directory where git commands should run.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"The tagging outcome and any actions performed along the way.\"\n      }\n    },\n    {\n      \"id\": \"op-validateTagForPush\",\n      \"name\": \"validateTagForPush\",\n      \"what\": \"Validates that a local tag is safe to push to the default remote.\",\n      \"inputs\": [\n        {\n          \"name\": \"tagName\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Name of the tag to validate.\"\n        },\n        {\n          \"name\": \"cwd\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Repository directory where git commands should run.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"A validation result with an optional suggested fix command.\"\n      }\n    },\n    {\n      \"id\": \"op-validateVersion\",\n      \"name\": \"validateVersion\",\n      \"what\": \"Validates a version string against the active versioning strategy.\",\n      \"inputs\": [\n        {\n          \"name\": \"version\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Version string to validate.\"\n        },\n        {\n          \"name\": \"config\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"VersionGuard configuration that selects the validation rules.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"The validation result for the provided version.\"\n      }\n    },\n    {\n      \"id\": \"op-runWizard\",\n      \"name\": \"runWizard\",\n      \"what\": \"Runs the interactive setup wizard.\",\n      \"inputs\": [\n        {\n          \"name\": \"cwd\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Project directory to initialize.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"The path to the created config file, or `null` if cancelled.\"\n      }\n    },\n    {\n      \"id\": \"op-runHeadless\",\n      \"name\": \"runHeadless\",\n      \"what\": \"Initializes VersionGuard non-interactively using CLI flags.\",\n      \"inputs\": [\n        {\n          \"name\": \"options\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Headless initialization options.\"\n        }\n      ],\n      \"outputs\": {\n        \"text\": \"The path to the created config file.\"\n      }\n    },\n    {\n      \"id\": \"op-createProgram\",\n      \"name\": \"createProgram\",\n      \"what\": \"Creates the VersionGuard CLI program definition.\",\n      \"inputs\": [],\n      \"outputs\": {\n        \"text\": \"A configured Commander program for the VersionGuard CLI.\"\n      }\n    },\n    {\n      \"id\": \"op-runCli\",\n      \"name\": \"runCli\",\n      \"what\": \"Parses CLI arguments and executes the matching command.\",\n      \"inputs\": [\n        {\n          \"name\": \"argv\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Full argument vector to parse.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"op-createTempProject\",\n      \"name\": \"createTempProject\",\n      \"what\": \"Creates a temporary project directory with a minimal `package.json` fixture.\",\n      \"inputs\": [],\n      \"outputs\": {\n        \"text\": \"The absolute path to the temporary project directory.\"\n      }\n    },\n    {\n      \"id\": \"op-initGitRepo\",\n      \"name\": \"initGitRepo\",\n      \"what\": \"Initializes a git repository in a fixture directory with a first commit.\",\n      \"inputs\": [\n        {\n          \"name\": \"cwd\",\n          \"type\": \"unknown\",\n          \"required\": true,\n          \"description\": \"Absolute path to the fixture repository.\"\n        }\n      ]\n    },\n    {\n      \"id\": \"op-createBareRemote\",\n      \"name\": \"createBareRemote\",\n      \"what\": \"Creates a bare git repository to use as a remote in integration tests.\",\n      \"inputs\": [],\n      \"outputs\": {\n        \"text\": \"The absolute path to the new bare repository.\"\n      }\n    }\n  ],\n  \"constraints\": [],\n  \"workflows\": [],\n  \"configSchema\": [\n    {\n      \"key\": \"ManifestConfig.source\",\n      \"type\": \"ManifestSourceType\",\n      \"description\": \"Manifest file to read the version from.  Use `'auto'` for file-existence detection or a specific filename.\",\n      \"default\": \"'auto'\"\n    },\n    {\n      \"key\": \"ManifestConfig.path\",\n      \"type\": \"string | undefined\",\n      \"description\": \"Dotted key path to the version field within the manifest.  For example `'version'` for package.json, `'package.version'` for Cargo.toml, or `'project.version'` for pyproject.toml.\",\n      \"default\": \"undefined (uses the provider's built-in default)\"\n    },\n    {\n      \"key\": \"ManifestConfig.regex\",\n      \"type\": \"string | undefined\",\n      \"description\": \"Regex pattern to extract the version from source-code manifests.  Capture group 1 must contain the version string.\",\n      \"default\": \"undefined\"\n    },\n    {\n      \"key\": \"SemVerConfig.allowVPrefix\",\n      \"type\": \"boolean\",\n      \"description\": \"Tolerates a leading `v` prefix (e.g. `v1.2.3`).  When enabled the prefix is stripped before parsing.\",\n      \"default\": \"false\"\n    },\n    {\n      \"key\": \"SemVerConfig.allowBuildMetadata\",\n      \"type\": \"boolean\",\n      \"description\": \"Permits `+build` metadata on version strings.\",\n      \"default\": \"true\"\n    },\n    {\n      \"key\": \"SemVerConfig.requirePrerelease\",\n      \"type\": \"boolean\",\n      \"description\": \"Requires every version to carry a prerelease label.\",\n      \"default\": \"false\"\n    },\n    {\n      \"key\": \"CalVerConfig.format\",\n      \"type\": \"CalVerFormat\",\n      \"description\": \"Calendar format used when parsing and validating versions.\"\n    },\n    {\n      \"key\": \"CalVerConfig.preventFutureDates\",\n      \"type\": \"boolean\",\n      \"description\": \"Rejects versions that point to a future date.\",\n      \"default\": \"true\"\n    },\n    {\n      \"key\": \"CalVerConfig.strictMutualExclusion\",\n      \"type\": \"boolean | undefined\",\n      \"description\": \"Enforces that week tokens (WW/0W) cannot be mixed with month/day tokens.\",\n      \"default\": \"true\"\n    },\n    {\n      \"key\": \"SyncConfig.files\",\n      \"type\": \"string[]\",\n      \"description\": \"File globs or paths that should be scanned for version updates.\"\n    },\n    {\n      \"key\": \"SyncConfig.patterns\",\n      \"type\": \"SyncPattern[]\",\n      \"description\": \"Replacement patterns applied to matching files.\"\n    },\n    {\n      \"key\": \"ChangelogConfig.enabled\",\n      \"type\": \"boolean\",\n      \"description\": \"Enables changelog validation.\",\n      \"default\": \"false\"\n    },\n    {\n      \"key\": \"ChangelogConfig.file\",\n      \"type\": \"string\",\n      \"description\": \"Path to the changelog file to inspect.\"\n    },\n    {\n      \"key\": \"ChangelogConfig.strict\",\n      \"type\": \"boolean\",\n      \"description\": \"Treats changelog problems as hard failures.\",\n      \"default\": \"false\"\n    },\n    {\n      \"key\": \"ChangelogConfig.requireEntry\",\n      \"type\": \"boolean\",\n      \"description\": \"Requires an entry for the current version.\",\n      \"default\": \"false\"\n    },\n    {\n      \"key\": \"ChangelogConfig.enforceStructure\",\n      \"type\": \"boolean | undefined\",\n      \"description\": \"Validates that changelog section headers use only allowed names.  When enabled, any `### SectionName` header not present in `sections` is reported as an error.\",\n      \"default\": \"false\"\n    },\n    {\n      \"key\": \"ChangelogConfig.sections\",\n      \"type\": \"string[] | undefined\",\n      \"description\": \"Allowed Keep a Changelog section names.  Only applied when `enforceStructure` is `true`.\",\n      \"default\": \"['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security']\"\n    },\n    {\n      \"key\": \"GitHooksConfig.'pre-commit'\",\n      \"type\": \"boolean\",\n      \"description\": \"Enables validation during the `pre-commit` hook.\",\n      \"default\": \"false\"\n    },\n    {\n      \"key\": \"GitHooksConfig.'pre-push'\",\n      \"type\": \"boolean\",\n      \"description\": \"Enables validation during the `pre-push` hook.\",\n      \"default\": \"false\"\n    },\n    {\n      \"key\": \"GitHooksConfig.'post-tag'\",\n      \"type\": \"boolean\",\n      \"description\": \"Enables follow-up tasks after a tag is created.\",\n      \"default\": \"false\"\n    },\n    {\n      \"key\": \"GitConfig.hooks\",\n      \"type\": \"GitHooksConfig\",\n      \"description\": \"Hook toggles used by the CLI and validation workflow.\"\n    },\n    {\n      \"key\": \"GitConfig.enforceHooks\",\n      \"type\": \"boolean\",\n      \"description\": \"Fails validation when required hooks are missing.\",\n      \"default\": \"false\"\n    },\n    {\n      \"key\": \"GitHubConfig.dependabot\",\n      \"type\": \"boolean\",\n      \"description\": \"Generates `.github/dependabot.yml` from detected manifests during init.\",\n      \"default\": \"true\"\n    },\n    {\n      \"key\": \"VersioningConfig.type\",\n      \"type\": \"VersioningType\",\n      \"description\": \"Versioning strategy used for the project.\"\n    },\n    {\n      \"key\": \"VersioningConfig.schemeRules\",\n      \"type\": \"SchemeRules | undefined\",\n      \"description\": \"Scheme-level validation rules applied regardless of versioning type.\",\n      \"default\": \"`{ maxNumericSegments: 3, allowedModifiers: ['dev', 'alpha', 'beta', 'rc'] }`\"\n    },\n    {\n      \"key\": \"VersioningConfig.semver\",\n      \"type\": \"SemVerConfig | undefined\",\n      \"description\": \"SemVer-specific settings when `type` is `'semver'`.\",\n      \"default\": \"`{ allowVPrefix: false, allowBuildMetadata: true, requirePrerelease: false }`\"\n    },\n    {\n      \"key\": \"VersioningConfig.calver\",\n      \"type\": \"CalVerConfig | undefined\",\n      \"description\": \"CalVer-specific settings when `type` is `'calver'`.\",\n      \"default\": \"undefined\"\n    },\n    {\n      \"key\": \"ScanConfig.enabled\",\n      \"type\": \"boolean\",\n      \"description\": \"Enables repo-wide scanning for stale version literals.\",\n      \"default\": \"false\"\n    },\n    {\n      \"key\": \"ScanConfig.patterns\",\n      \"type\": \"string[]\",\n      \"description\": \"Regex patterns that match version-like strings in source files.  Capture group 1 must contain the version string.\",\n      \"default\": \"Patterns matching common version formats in code, CI, and Docker files.\"\n    },\n    {\n      \"key\": \"ScanConfig.allowlist\",\n      \"type\": \"ScanAllowlistEntry[]\",\n      \"description\": \"Files containing intentional version references that should not be flagged.\",\n      \"default\": \"[]\"\n    },\n    {\n      \"key\": \"VersionGuardConfig.versioning\",\n      \"type\": \"VersioningConfig\",\n      \"description\": \"Active versioning settings.\"\n    },\n    {\n      \"key\": \"VersionGuardConfig.manifest\",\n      \"type\": \"ManifestConfig\",\n      \"description\": \"Version source manifest settings.\",\n      \"default\": \"`{ source: 'auto' }`\"\n    },\n    {\n      \"key\": \"VersionGuardConfig.sync\",\n      \"type\": \"SyncConfig\",\n      \"description\": \"Synchronization settings for mirrored version strings.\"\n    },\n    {\n      \"key\": \"VersionGuardConfig.changelog\",\n      \"type\": \"ChangelogConfig\",\n      \"description\": \"Changelog validation settings.\"\n    },\n    {\n      \"key\": \"VersionGuardConfig.git\",\n      \"type\": \"GitConfig\",\n      \"description\": \"Git enforcement settings.\"\n    },\n    {\n      \"key\": \"VersionGuardConfig.github\",\n      \"type\": \"GitHubConfig\",\n      \"description\": \"GitHub integration settings.\",\n      \"default\": \"`{ dependabot: true }`\"\n    },\n    {\n      \"key\": \"VersionGuardConfig.scan\",\n      \"type\": \"ScanConfig\",\n      \"description\": \"Repo-wide version literal scanning.\",\n      \"default\": \"`{ enabled: false, patterns: [...], allowlist: [] }`\"\n    },\n    {\n      \"key\": \"VersionGuardConfig.ignore\",\n      \"type\": \"string[]\",\n      \"description\": \"Files or patterns excluded from validation.\"\n    },\n    {\n      \"key\": \"ChangelogStructureOptions.enforceStructure\",\n      \"type\": \"boolean | undefined\",\n      \"description\": \"Validate section headers against an allowed list.\"\n    },\n    {\n      \"key\": \"ChangelogStructureOptions.sections\",\n      \"type\": \"string[] | undefined\",\n      \"description\": \"Allowed section names. Defaults to Keep a Changelog standard sections.\"\n    },\n    {\n      \"key\": \"CkmConfigEntry.key\",\n      \"type\": \"string\",\n      \"description\": \"Dotted key path (e.g., `'CalVerConfig.format'`).\"\n    },\n    {\n      \"key\": \"CkmConfigEntry.type\",\n      \"type\": \"string\",\n      \"description\": \"TypeScript type.\"\n    },\n    {\n      \"key\": \"CkmConfigEntry.description\",\n      \"type\": \"string\",\n      \"description\": \"Description from TSDoc.\"\n    },\n    {\n      \"key\": \"CkmConfigEntry.default\",\n      \"type\": \"string | undefined\",\n      \"description\": \"Default value if specified via `@defaultValue`.\"\n    },\n    {\n      \"key\": \"InitOptions.cwd\",\n      \"type\": \"string\",\n      \"description\": \"Working directory path.\"\n    },\n    {\n      \"key\": \"InitOptions.type\",\n      \"type\": \"\\\"semver\\\" | \\\"calver\\\" | undefined\",\n      \"description\": \"Versioning type (semver or calver).\"\n    },\n    {\n      \"key\": \"InitOptions.format\",\n      \"type\": \"string | undefined\",\n      \"description\": \"CalVer format string.\"\n    },\n    {\n      \"key\": \"InitOptions.allowVPrefix\",\n      \"type\": \"boolean | undefined\",\n      \"description\": \"Allow v-prefix on SemVer versions.\"\n    },\n    {\n      \"key\": \"InitOptions.allowBuildMetadata\",\n      \"type\": \"boolean | undefined\",\n      \"description\": \"Allow build metadata on SemVer versions.\"\n    },\n    {\n      \"key\": \"InitOptions.requirePrerelease\",\n      \"type\": \"boolean | undefined\",\n      \"description\": \"Require prerelease labels on SemVer versions.\"\n    },\n    {\n      \"key\": \"InitOptions.manifest\",\n      \"type\": \"string | undefined\",\n      \"description\": \"Manifest source type.\"\n    },\n    {\n      \"key\": \"InitOptions.github\",\n      \"type\": \"boolean | undefined\",\n      \"description\": \"Whether to generate GitHub integration files (dependabot.yml).\"\n    },\n    {\n      \"key\": \"InitOptions.hooks\",\n      \"type\": \"boolean | undefined\",\n      \"description\": \"Whether to install git hooks.\"\n    },\n    {\n      \"key\": \"InitOptions.changelog\",\n      \"type\": \"boolean | undefined\",\n      \"description\": \"Whether to enable changelog validation.\"\n    },\n    {\n      \"key\": \"InitOptions.yes\",\n      \"type\": \"boolean | undefined\",\n      \"description\": \"Accept defaults without prompting.\"\n    },\n    {\n      \"key\": \"InitOptions.force\",\n      \"type\": \"boolean | undefined\",\n      \"description\": \"Overwrite existing config.\"\n    }\n  ]\n}";
+//#endregion
+//#region docs/llms.txt?raw
+var llms_default = "# @codluv/versionguard\n> Strict versioning enforcement for SemVer and CalVer — language-agnostic manifest support, git hooks, changelog validation, and file sync\n> Version: 0.8.1\n\n## Install\n\n```bash\nnpm install -D @codluv/versionguard\n```\n\n## Documentation\n\n- [API Reference](./api-reference.mdx): Full API documentation (MDX)\n- [Full Context](./llms-full.txt): Complete symbol documentation for deep LLM consumption\n\n## Packages\n\n### main\n93 functions, 56 types\n\n- getSemVerConfig() — Resolves the SemVer config from a VersionGuard config.\n- getCalVerConfig() — Extracts the CalVer config from a VersionGuard config, throwing if missing.\n- validateModifier() — Validates a pre-release / modifier tag against the allowed modifiers list.\n- isValidCalVerFormat() — Validates that a CalVer format string is composed of valid tokens and follows structural rules.\n- parseFormat() — Breaks a CalVer format string into its component tokens.\n- getRegexForFormat() — Builds a regular expression that matches a supported CalVer format.\n- parse() — Parses a CalVer string using the supplied format.\n- validate() — Validates a CalVer string against formatting and date rules.\n- format() — Formats a parsed CalVer object back into a version string.\n- getCurrentVersion() — Creates the current CalVer string for a format.\n- compare() — Compares two CalVer strings using a shared format.\n- increment() — Increments a CalVer string.\n- getNextVersions() — Returns the most likely next CalVer candidates.\n- validateChangelog() — Validates a changelog file for release readiness.\n- getLatestVersion() — Gets the most recent released version from a changelog.\n- addVersionEntry() — Inserts a new version entry beneath the `[Unreleased]` section.\n- isChangesetMangled() — Detects whether a changelog has been mangled by Changesets.\n- fixChangesetMangling() — Fixes a Changesets-mangled changelog into proper Keep a Changelog format.\n- createCkmEngine() — Creates a CKM engine from a parsed manifest.\n- parse() — Parses a semantic version string.\n- validate() — Validates that a string is a supported semantic version.\n- compare() — Compares two semantic version strings.\n- gt() — Checks whether one semantic version is greater than another.\n- lt() — Checks whether one semantic version is less than another.\n- eq() — Checks whether two semantic versions are equal in precedence.\n- increment() — Increments a semantic version string by release type.\n- format() — Formats a parsed semantic version object.\n- getVersionFeedback() — Generates actionable feedback for a version string.\n- getSyncFeedback() — Generates suggestions for version sync mismatches in a file.\n- getChangelogFeedback() — Generates suggestions for changelog-related validation issues.\n- getTagFeedback() — Generates suggestions for git tag mismatches.\n- getNestedValue() — Traverses a nested object using a dotted key path.\n- setNestedValue() — Sets a value at a dotted key path, throwing if intermediate segments are missing.\n- escapeRegExp() — Escapes special regex characters in a string for safe use in `new RegExp()`.\n- resolveVersionSource() — Resolves the version source provider for a project.\n- detectManifests() — Detects all manifest files present in a project directory.\n- getPackageJsonPath() — Gets the `package.json` path for a project directory.\n- readPackageJson() — Reads and parses a project's `package.json` file.\n- writePackageJson() — Writes a `package.json` document back to disk.\n- getPackageVersion() — Gets the version string from the project manifest.  When a `manifest` config is provided, uses the configured version source provider (auto-detection or explicit). Falls back to `package.json` for backwards compatibility when no config is provided.\n- setPackageVersion() — Sets the version field in the project manifest.  When a `manifest` config is provided, uses the configured version source provider. Falls back to `package.json` for backwards compatibility when no config is provided.\n- getVersionSource() — Resolves the version source provider for a project.\n- syncVersion() — Synchronizes configured files to a single version string.\n- syncFile() — Synchronizes a single file to a target version.\n- checkHardcodedVersions() — Checks configured files for hardcoded version mismatches.\n- scanRepoForVersions() — Scans the entire repository for hardcoded version literals.\n- fixPackageVersion() — Updates the `package.json` version field when needed.\n- fixSyncIssues() — Synchronizes configured files to the package version.\n- fixChangelog() — Ensures the changelog contains an entry for a version.\n- fixAll() — Runs all configured auto-fix operations.\n- suggestNextVersion() — Suggests candidate next versions for a release.\n- installHooks() — Installs VersionGuard-managed Git hooks in a repository.\n- uninstallHooks() — Removes VersionGuard-managed Git hooks from a repository.\n- findGitDir() — Finds the nearest `.git` directory by walking up from a starting directory.\n- areHooksInstalled() — Checks whether all VersionGuard-managed hooks are installed.\n- generateHookScript() — Generates the shell script content for a Git hook.\n- checkHooksPathOverride() — Checks whether git hooks have been redirected away from the repository.\n- checkHuskyBypass() — Checks whether the HUSKY environment variable is disabling hooks.\n- checkHookIntegrity() — Verifies that installed hook scripts match the expected content.\n- checkEnforceHooksPolicy() — Checks whether hooks are configured as required but not enforced.\n- runGuardChecks() — Runs all guard checks and returns a consolidated report.\n- generateDependabotConfig() — Generates Dependabot YAML configuration from detected manifests.\n- writeDependabotConfig() — Writes a Dependabot configuration file to `.github/dependabot.yml`.\n- dependabotConfigExists() — Checks whether `.github/dependabot.yml` exists in the project.\n- getDefaultConfig() — Returns a deep-cloned copy of the built-in VersionGuard configuration.\n- findConfig() — Finds the first supported VersionGuard config file in a directory.\n- loadConfig() — Loads a VersionGuard config file from disk.\n- getConfig() — Resolves the active VersionGuard configuration for a project.\n- initConfig() — Initializes a new VersionGuard config file in a project.\n- findProjectRoot() — Walks up from `startDir` to find the nearest project root.\n- formatNotProjectError() — Formats a helpful error message when a command can't find a project.\n- getLatestTag() — Returns the most recent reachable git tag for a repository.\n- getAllTags() — Lists all tags in a repository.\n- createTag() — Creates a release tag and optionally fixes version state first.\n- handlePostTag() — Runs post-tag validation and sync checks.\n- validateTagForPush() — Validates that a local tag is safe to push to the default remote.\n- suggestTagMessage() — Suggests an annotated tag message from changelog content.\n- validateVersion() — Validates a version string against the active versioning strategy.\n- validate() — Validates the current project state against the supplied configuration.\n- doctor() — Runs an extended readiness check for a project.\n- sync() — Synchronizes configured files to the current package version.\n- canBump() — Determines whether a project can move from one version to another.\n- runWizard() — Runs the interactive setup wizard.\n- runHeadless() — Initializes VersionGuard non-interactively using CLI flags.\n- createProgram() — Creates the VersionGuard CLI program definition.\n- runCli() — Parses CLI arguments and executes the matching command.\n- shouldRunCli() — Determines whether the current module is the invoked CLI entry point.\n- createTempProject() — Creates a temporary project directory with a minimal `package.json` fixture.\n- initGitRepo() — Initializes a git repository in a fixture directory with a first commit.\n- writeTextFile() — Writes a text fixture file relative to a temporary project directory.\n- createBareRemote() — Creates a bare git repository to use as a remote in integration tests.\n- addGitRemote() — Adds a local bare repository as the `origin` remote for a fixture repo.\n- commitAll() — Stages all changes and creates a commit in a fixture repository.\n\n- VersioningType — Supported versioning strategies.\n- ManifestSourceType — Supported manifest source types for version extraction.\n- ManifestConfig — Configures the version source manifest.\n- CalVerToken — Valid CalVer token names for building format strings.\n- CalVerFormat — A CalVer format string composed of dot-separated tokens.\n- SchemeRules — Configures scheme-level validation rules applied regardless of versioning type.\n- SemVerConfig — Configures SemVer validation rules.\n- CalVerConfig — Configures CalVer validation rules.\n- SyncPattern — Describes a search-and-replace pattern used during version synchronization.\n- SyncConfig — Configures files and patterns that should stay in sync with the canonical version.\n- ChangelogConfig — Controls changelog validation behavior.\n- GitHooksConfig — Toggles each supported git hook integration.\n- GitConfig — Configures git-related enforcement.\n- GitHubConfig — Configures GitHub-specific integration features.\n- VersioningConfig — Configures the active versioning mode.\n- ScanAllowlistEntry — An intentional version reference that should be excluded from scan results.\n- ScanConfig — Configures repo-wide scanning for hardcoded version literals.\n- VersionGuardConfig — Top-level configuration consumed by versionguard.\n- SemVer — Parsed semantic version components.\n- CalVer — Parsed calendar version components.\n- ParsedSemVer — Parsed semantic version result wrapper.\n- ParsedCalVer — Parsed calendar version result wrapper.\n- ParsedVersion — Union of supported parsed version payloads.\n- ValidationError — Describes a single validation problem.\n- ValidationResult — Result returned by version parsing and validation helpers.\n- SyncChange — Describes a single in-file version replacement.\n- SyncResult — Reports the result of synchronizing a single file.\n- VersionMismatch — Reports a discovered version mismatch.\n- FullValidationResult — Combined result from a full project validation run.\n- DoctorReport — Reports whether a project is ready to pass VersionGuard checks.\n- ParsedCalVerFormat — Parsed token layout for a supported CalVer format string.\n- ChangelogValidationResult — Describes the outcome of validating a changelog file.\n- ChangelogStructureOptions — Options for changelog structure enforcement.\n- CkmConcept — A domain concept extracted from an exported interface or type.\n- CkmProperty — A property within a concept.\n- CkmOperation — A user-facing operation extracted from an exported function.\n- CkmInput — A function parameter within an operation.\n- CkmConstraint — A constraint enforced by the tool.\n- CkmWorkflow — A multi-step workflow for a common goal.\n- CkmConfigEntry — A config schema entry with type, description, and default.\n- CkmManifest — The complete Codebase Knowledge Manifest.\n- CkmTopic — An auto-generated topic derived from CKM data.\n- CkmEngine — The CKM engine — provides topic derivation, filtering, and output formatting.\n- Suggestion — Feedback entry point exports for suggestion and guidance helpers.\n- FeedbackResult — Aggregates validation errors with suggested next steps.\n- VersionSourceProvider — Abstraction for reading and writing a version string from any manifest format.\n- PackageJsonValue — JSON-compatible scalar, array, or object value used by package metadata.\n- PackageJsonArray — Recursive array type used for arbitrary JSON-compatible package values.\n- PackageJsonObject — Recursive object type used for arbitrary JSON-compatible package values.\n- PackageJson — Minimal shape of a `package.json` document used by VersionGuard.\n- FixResult — Fix entry point exports for auto-remediation helpers.\n- GuardWarning — Describes a single guard finding.\n- GuardReport — Result of a full guard check pass.\n- ProjectRootResult — Result of project root detection.\n- TagInfo — Tag entry point exports for release-tag management helpers.\n- InitOptions — Options for headless (non-interactive) initialization.\n";
+//#endregion
+//#region src/init-wizard.ts
+/**
+* Interactive setup wizard and headless init for VersionGuard.
+*
+* @packageDocumentation
+*/
+/**
+* Runs the interactive setup wizard.
+*
+* @remarks
+* Walks the user through versioning type, CalVer format, manifest source,
+* git hooks, and changelog configuration. Writes `.versionguard.yml` when done.
+*
+* @param cwd - Project directory to initialize.
+* @returns The path to the created config file, or `null` if cancelled.
+*
+* @example
+* ```ts
+* const configPath = await runWizard(process.cwd());
+* ```
+*
+* @public
+* @since 0.3.0
+*/
 async function runWizard(cwd) {
-  p.intro("VersionGuard Setup");
-  const existingConfig = findExistingConfig(cwd);
-  if (existingConfig) {
-    p.log.warning(`Config already exists: ${path.relative(cwd, existingConfig)}`);
-    const overwrite = await p.confirm({ message: "Overwrite existing config?" });
-    if (p.isCancel(overwrite) || !overwrite) {
-      p.outro("Setup cancelled.");
-      return null;
-    }
-  }
-  const type = await p.select({
-    message: "Versioning strategy",
-    options: [
-      { value: "semver", label: "SemVer", hint: "MAJOR.MINOR.PATCH (e.g., 1.2.3)" },
-      { value: "calver", label: "CalVer", hint: "Calendar-based (e.g., 2026.3.0)" }
-    ]
-  });
-  if (p.isCancel(type)) {
-    p.outro("Setup cancelled.");
-    return null;
-  }
-  let format;
-  let allowVPrefix = false;
-  let allowBuildMetadata = true;
-  let requirePrerelease = false;
-  if (type === "calver") {
-    const selected = await selectCalVerFormat();
-    if (!selected) {
-      p.outro("Setup cancelled.");
-      return null;
-    }
-    format = selected;
-  } else {
-    const semverOptions = await selectSemVerOptions();
-    if (!semverOptions) {
-      p.outro("Setup cancelled.");
-      return null;
-    }
-    allowVPrefix = semverOptions.allowVPrefix;
-    allowBuildMetadata = semverOptions.allowBuildMetadata;
-    requirePrerelease = semverOptions.requirePrerelease;
-  }
-  const manifest = await selectManifest(cwd);
-  if (manifest === null) {
-    p.outro("Setup cancelled.");
-    return null;
-  }
-  const hooks = await p.confirm({
-    message: "Install git hooks? (pre-commit, pre-push, post-tag)",
-    initialValue: true
-  });
-  if (p.isCancel(hooks)) {
-    p.outro("Setup cancelled.");
-    return null;
-  }
-  const changelog = await p.confirm({
-    message: "Enable changelog validation?",
-    initialValue: true
-  });
-  if (p.isCancel(changelog)) {
-    p.outro("Setup cancelled.");
-    return null;
-  }
-  const config = buildConfig({
-    type,
-    format,
-    allowVPrefix,
-    allowBuildMetadata,
-    requirePrerelease,
-    manifest: manifest === "auto" ? void 0 : manifest,
-    hooks,
-    changelog
-  });
-  const configPath = writeConfig(cwd, config);
-  p.log.success(`Created ${path.relative(cwd, configPath)}`);
-  p.outro("Run `vg validate` to verify your setup.");
-  return configPath;
+	p.intro("VersionGuard Setup");
+	const existingConfig = findExistingConfig(cwd);
+	if (existingConfig) {
+		p.log.warning(`Config already exists: ${path.relative(cwd, existingConfig)}`);
+		const overwrite = await p.confirm({ message: "Overwrite existing config?" });
+		if (p.isCancel(overwrite) || !overwrite) {
+			p.outro("Setup cancelled.");
+			return null;
+		}
+	}
+	const type = await p.select({
+		message: "Versioning strategy",
+		options: [{
+			value: "semver",
+			label: "SemVer",
+			hint: "MAJOR.MINOR.PATCH (e.g., 1.2.3)"
+		}, {
+			value: "calver",
+			label: "CalVer",
+			hint: "Calendar-based (e.g., 2026.3.0)"
+		}]
+	});
+	if (p.isCancel(type)) {
+		p.outro("Setup cancelled.");
+		return null;
+	}
+	let format;
+	let allowVPrefix = false;
+	let allowBuildMetadata = true;
+	let requirePrerelease = false;
+	if (type === "calver") {
+		const selected = await selectCalVerFormat();
+		if (!selected) {
+			p.outro("Setup cancelled.");
+			return null;
+		}
+		format = selected;
+	} else {
+		const semverOptions = await selectSemVerOptions();
+		if (!semverOptions) {
+			p.outro("Setup cancelled.");
+			return null;
+		}
+		allowVPrefix = semverOptions.allowVPrefix;
+		allowBuildMetadata = semverOptions.allowBuildMetadata;
+		requirePrerelease = semverOptions.requirePrerelease;
+	}
+	const manifest = await selectManifest(cwd);
+	if (manifest === null) {
+		p.outro("Setup cancelled.");
+		return null;
+	}
+	const hooks = await p.confirm({
+		message: "Install git hooks? (pre-commit, pre-push, post-tag)",
+		initialValue: true
+	});
+	if (p.isCancel(hooks)) {
+		p.outro("Setup cancelled.");
+		return null;
+	}
+	const changelog = await p.confirm({
+		message: "Enable changelog validation?",
+		initialValue: true
+	});
+	if (p.isCancel(changelog)) {
+		p.outro("Setup cancelled.");
+		return null;
+	}
+	const github = await p.confirm({
+		message: "Generate .github/dependabot.yml for automated dependency updates?",
+		initialValue: true
+	});
+	if (p.isCancel(github)) {
+		p.outro("Setup cancelled.");
+		return null;
+	}
+	const configPath = writeConfig(cwd, buildConfig({
+		type,
+		format,
+		allowVPrefix,
+		allowBuildMetadata,
+		requirePrerelease,
+		manifest: manifest === "auto" ? void 0 : manifest,
+		github,
+		hooks,
+		changelog
+	}));
+	if (github) {
+		const dependabotPath = writeDependabotConfig(cwd, generateDependabotConfig(detectManifests(cwd)));
+		p.log.success(`Created ${path.relative(cwd, dependabotPath)}`);
+	}
+	p.log.success(`Created ${path.relative(cwd, configPath)}`);
+	p.outro("Run `vg validate` to verify your setup.");
+	return configPath;
 }
+/**
+* Initializes VersionGuard non-interactively using CLI flags.
+*
+* @remarks
+* When `--yes` is passed, all defaults are used without prompting.
+* Individual flags override specific defaults.
+*
+* @param options - Headless initialization options.
+* @returns The path to the created config file.
+*
+* @example
+* ```ts
+* const configPath = runHeadless({ cwd: process.cwd(), type: 'calver', format: 'YYYY.M.MICRO' });
+* ```
+*
+* @public
+* @since 0.3.0
+*/
 function runHeadless(options) {
-  const existingConfig = findExistingConfig(options.cwd);
-  if (existingConfig && !options.force && !options.yes) {
-    throw new Error(
-      `Config already exists: ${existingConfig}. Use --force to overwrite or --yes to accept defaults.`
-    );
-  }
-  const config = buildConfig({
-    type: options.type ?? "semver",
-    format: options.format,
-    allowVPrefix: options.allowVPrefix ?? false,
-    allowBuildMetadata: options.allowBuildMetadata ?? true,
-    requirePrerelease: options.requirePrerelease ?? false,
-    manifest: options.manifest,
-    hooks: options.hooks ?? true,
-    changelog: options.changelog ?? true
-  });
-  return writeConfig(options.cwd, config);
+	const existingConfig = findExistingConfig(options.cwd);
+	if (existingConfig && !options.force && !options.yes) throw new Error(`Config already exists: ${existingConfig}. Use --force to overwrite or --yes to accept defaults.`);
+	const config = buildConfig({
+		type: options.type ?? "semver",
+		format: options.format,
+		allowVPrefix: options.allowVPrefix ?? false,
+		allowBuildMetadata: options.allowBuildMetadata ?? true,
+		requirePrerelease: options.requirePrerelease ?? false,
+		manifest: options.manifest,
+		github: options.github ?? true,
+		hooks: options.hooks ?? true,
+		changelog: options.changelog ?? true
+	});
+	const configPath = writeConfig(options.cwd, config);
+	if (options.github !== false) {
+		const dependabotContent = generateDependabotConfig(detectManifests(options.cwd));
+		writeDependabotConfig(options.cwd, dependabotContent);
+	}
+	return configPath;
 }
 async function selectCalVerFormat() {
-  const preset = await p.select({
-    message: "CalVer format",
-    options: [
-      { value: "YYYY.M.MICRO", label: "YYYY.M.MICRO", hint: "calver.org standard — 2026.3.0" },
-      { value: "YYYY.MM.MICRO", label: "YYYY.MM.MICRO", hint: "padded month — 2026.03.0" },
-      { value: "YY.0M.MICRO", label: "YY.0M.MICRO", hint: "Twisted/pip style — 26.03.0" },
-      { value: "YYYY.0M.0D", label: "YYYY.0M.0D", hint: "date-based — 2026.03.25" },
-      {
-        value: "YYYY.0M.0D.MICRO",
-        label: "YYYY.0M.0D.MICRO",
-        hint: "youtube-dl style — 2026.03.25.0"
-      },
-      { value: "YY.0M", label: "YY.0M", hint: "Ubuntu style — 26.03" },
-      { value: "custom", label: "Custom...", hint: "enter your own token format" }
-    ]
-  });
-  if (p.isCancel(preset)) return null;
-  if (preset === "custom") {
-    const custom = await p.text({
-      message: "Enter CalVer format (dot-separated tokens)",
-      placeholder: "YYYY.MM.MICRO",
-      validate(value) {
-        if (!value || !isValidCalVerFormat(value)) {
-          return "Invalid format. Use tokens: YYYY|YY|0Y, MM|M|0M, WW|0W, DD|D|0D, MICRO|PATCH";
-        }
-      }
-    });
-    if (p.isCancel(custom)) return null;
-    return custom;
-  }
-  return preset;
+	const preset = await p.select({
+		message: "CalVer format",
+		options: [
+			{
+				value: "YYYY.M.MICRO",
+				label: "YYYY.M.MICRO",
+				hint: "calver.org standard — 2026.3.0"
+			},
+			{
+				value: "YYYY.MM.MICRO",
+				label: "YYYY.MM.MICRO",
+				hint: "padded month — 2026.03.0"
+			},
+			{
+				value: "YY.0M.MICRO",
+				label: "YY.0M.MICRO",
+				hint: "Twisted/pip style — 26.03.0"
+			},
+			{
+				value: "YYYY.0M.0D",
+				label: "YYYY.0M.0D",
+				hint: "date-based — 2026.03.25"
+			},
+			{
+				value: "YYYY.0M.0D.MICRO",
+				label: "YYYY.0M.0D.MICRO",
+				hint: "youtube-dl style — 2026.03.25.0"
+			},
+			{
+				value: "YY.0M",
+				label: "YY.0M",
+				hint: "Ubuntu style — 26.03"
+			},
+			{
+				value: "custom",
+				label: "Custom...",
+				hint: "enter your own token format"
+			}
+		]
+	});
+	if (p.isCancel(preset)) return null;
+	if (preset === "custom") {
+		const custom = await p.text({
+			message: "Enter CalVer format (dot-separated tokens)",
+			placeholder: "YYYY.MM.MICRO",
+			validate(value) {
+				if (!value || !isValidCalVerFormat(value)) return "Invalid format. Use tokens: YYYY|YY|0Y, MM|M|0M, WW|0W, DD|D|0D, MICRO|PATCH";
+			}
+		});
+		if (p.isCancel(custom)) return null;
+		return custom;
+	}
+	return preset;
 }
 async function selectSemVerOptions() {
-  const customize = await p.confirm({
-    message: "Customize SemVer rules? (defaults work for most projects)",
-    initialValue: false
-  });
-  if (p.isCancel(customize)) return null;
-  if (!customize) {
-    return { allowVPrefix: false, allowBuildMetadata: true, requirePrerelease: false };
-  }
-  const allowVPrefix = await p.confirm({
-    message: "Allow v-prefix? (e.g., v1.2.3)",
-    initialValue: false
-  });
-  if (p.isCancel(allowVPrefix)) return null;
-  const allowBuildMetadata = await p.confirm({
-    message: "Allow build metadata? (e.g., 1.2.3+build.123)",
-    initialValue: true
-  });
-  if (p.isCancel(allowBuildMetadata)) return null;
-  const requirePrerelease = await p.confirm({
-    message: "Require prerelease labels? (e.g., 1.2.3-alpha.1)",
-    initialValue: false
-  });
-  if (p.isCancel(requirePrerelease)) return null;
-  return { allowVPrefix, allowBuildMetadata, requirePrerelease };
+	const customize = await p.confirm({
+		message: "Customize SemVer rules? (defaults work for most projects)",
+		initialValue: false
+	});
+	if (p.isCancel(customize)) return null;
+	if (!customize) return {
+		allowVPrefix: false,
+		allowBuildMetadata: true,
+		requirePrerelease: false
+	};
+	const allowVPrefix = await p.confirm({
+		message: "Allow v-prefix? (e.g., v1.2.3)",
+		initialValue: false
+	});
+	if (p.isCancel(allowVPrefix)) return null;
+	const allowBuildMetadata = await p.confirm({
+		message: "Allow build metadata? (e.g., 1.2.3+build.123)",
+		initialValue: true
+	});
+	if (p.isCancel(allowBuildMetadata)) return null;
+	const requirePrerelease = await p.confirm({
+		message: "Require prerelease labels? (e.g., 1.2.3-alpha.1)",
+		initialValue: false
+	});
+	if (p.isCancel(requirePrerelease)) return null;
+	return {
+		allowVPrefix,
+		allowBuildMetadata,
+		requirePrerelease
+	};
 }
 async function selectManifest(cwd) {
-  const detected = [];
-  const checks = [
-    { file: "package.json", label: "package.json", hint: "Node.js / Bun" },
-    { file: "Cargo.toml", label: "Cargo.toml", hint: "Rust" },
-    { file: "pyproject.toml", label: "pyproject.toml", hint: "Python" },
-    { file: "pubspec.yaml", label: "pubspec.yaml", hint: "Dart / Flutter" },
-    { file: "composer.json", label: "composer.json", hint: "PHP" },
-    { file: "pom.xml", label: "pom.xml", hint: "Java / Maven" },
-    { file: "VERSION", label: "VERSION", hint: "Plain text file" }
-  ];
-  for (const check of checks) {
-    if (fs.existsSync(path.join(cwd, check.file))) {
-      detected.push({ value: check.file, label: `${check.label} (detected)`, hint: check.hint });
-    }
-  }
-  const options = [
-    { value: "auto", label: "Auto-detect", hint: "scan for known manifests at runtime" },
-    ...detected,
-    ...checks.filter((c) => !detected.some((d) => d.value === c.file)).map((c) => ({ value: c.file, label: c.label, hint: c.hint })),
-    { value: "git-tag", label: "Git tags", hint: "Go / Swift — version from tags" }
-  ];
-  const result = await p.select({
-    message: "Version source",
-    options,
-    initialValue: detected.length === 1 ? detected[0].value : "auto"
-  });
-  if (p.isCancel(result)) return null;
-  return result;
+	const detected = [];
+	const checks = [
+		{
+			file: "package.json",
+			label: "package.json",
+			hint: "Node.js / Bun"
+		},
+		{
+			file: "Cargo.toml",
+			label: "Cargo.toml",
+			hint: "Rust"
+		},
+		{
+			file: "pyproject.toml",
+			label: "pyproject.toml",
+			hint: "Python"
+		},
+		{
+			file: "pubspec.yaml",
+			label: "pubspec.yaml",
+			hint: "Dart / Flutter"
+		},
+		{
+			file: "composer.json",
+			label: "composer.json",
+			hint: "PHP"
+		},
+		{
+			file: "pom.xml",
+			label: "pom.xml",
+			hint: "Java / Maven"
+		},
+		{
+			file: "VERSION",
+			label: "VERSION",
+			hint: "Plain text file"
+		}
+	];
+	for (const check of checks) if (fs.existsSync(path.join(cwd, check.file))) detected.push({
+		value: check.file,
+		label: `${check.label} (detected)`,
+		hint: check.hint
+	});
+	const options = [
+		{
+			value: "auto",
+			label: "Auto-detect",
+			hint: "scan for known manifests at runtime"
+		},
+		...detected,
+		...checks.filter((c) => !detected.some((d) => d.value === c.file)).map((c) => ({
+			value: c.file,
+			label: c.label,
+			hint: c.hint
+		})),
+		{
+			value: "git-tag",
+			label: "Git tags",
+			hint: "Go / Swift — version from tags"
+		}
+	];
+	const result = await p.select({
+		message: "Version source",
+		options,
+		initialValue: detected.length === 1 ? detected[0].value : "auto"
+	});
+	if (p.isCancel(result)) return null;
+	return result;
 }
 function buildConfig(input) {
-  const versioning = {
-    type: input.type,
-    semver: {
-      allowVPrefix: input.allowVPrefix,
-      allowBuildMetadata: input.allowBuildMetadata,
-      requirePrerelease: input.requirePrerelease
-    },
-    calver: {
-      format: input.format ?? "YYYY.MM.PATCH",
-      preventFutureDates: true
-    }
-  };
-  const config = { versioning };
-  if (input.manifest) {
-    config.manifest = { source: input.manifest };
-  }
-  config.sync = {
-    files: ["README.md", "CHANGELOG.md"],
-    patterns: [
-      {
-        regex: `(version\\s*[=:]\\s*["'])(.+?)(["'])`,
-        template: "$1{{version}}$3"
-      },
-      {
-        regex: "(##\\s*\\[)(.+?)(\\])",
-        template: "$1{{version}}$3"
-      }
-    ]
-  };
-  config.changelog = {
-    enabled: input.changelog,
-    file: "CHANGELOG.md",
-    strict: true,
-    requireEntry: input.changelog
-  };
-  config.git = {
-    hooks: {
-      "pre-commit": input.hooks,
-      "pre-push": input.hooks,
-      "post-tag": input.hooks
-    },
-    enforceHooks: input.hooks
-  };
-  config.ignore = ["node_modules/**", "dist/**", ".git/**", "*.lock", ".changeset/**"];
-  return config;
+	const config = { versioning: {
+		type: input.type,
+		semver: {
+			allowVPrefix: input.allowVPrefix,
+			allowBuildMetadata: input.allowBuildMetadata,
+			requirePrerelease: input.requirePrerelease
+		},
+		calver: {
+			format: input.format ?? "YYYY.MM.PATCH",
+			preventFutureDates: true
+		}
+	} };
+	if (input.manifest) config.manifest = { source: input.manifest };
+	config.sync = {
+		files: ["README.md", "CHANGELOG.md"],
+		patterns: [{
+			regex: "(version\\s*[=:]\\s*[\"'])(.+?)([\"'])",
+			template: "$1{{version}}$3"
+		}, {
+			regex: "(##\\s*\\[)(.+?)(\\])",
+			template: "$1{{version}}$3"
+		}]
+	};
+	config.changelog = {
+		enabled: input.changelog,
+		file: "CHANGELOG.md",
+		strict: true,
+		requireEntry: input.changelog
+	};
+	config.github = { dependabot: input.github };
+	config.git = {
+		hooks: {
+			"pre-commit": input.hooks,
+			"pre-push": input.hooks,
+			"post-tag": input.hooks
+		},
+		enforceHooks: input.hooks
+	};
+	config.ignore = [
+		"node_modules/**",
+		"dist/**",
+		".git/**",
+		"*.lock",
+		".changeset/**"
+	];
+	return config;
 }
 function writeConfig(cwd, config) {
-  const configPath = path.join(cwd, ".versionguard.yml");
-  const content = yaml.dump(config, {
-    indent: 2,
-    lineWidth: 120,
-    noRefs: true,
-    quotingType: '"',
-    forceQuotes: false
-  });
-  fs.writeFileSync(configPath, content, "utf-8");
-  return configPath;
+	const configPath = path.join(cwd, ".versionguard.yml");
+	const content = yaml.dump(config, {
+		indent: 2,
+		lineWidth: 120,
+		noRefs: true,
+		quotingType: "\"",
+		forceQuotes: false
+	});
+	fs.writeFileSync(configPath, content, "utf-8");
+	return configPath;
 }
 function findExistingConfig(cwd) {
-  for (const name of [
-    ".versionguard.yml",
-    ".versionguard.yaml",
-    "versionguard.yml",
-    "versionguard.yaml"
-  ]) {
-    const full = path.join(cwd, name);
-    if (fs.existsSync(full)) return full;
-  }
-  return null;
+	for (const name of [
+		".versionguard.yml",
+		".versionguard.yaml",
+		"versionguard.yml",
+		"versionguard.yaml"
+	]) {
+		const full = path.join(cwd, name);
+		if (fs.existsSync(full)) return full;
+	}
+	return null;
 }
-const CLI_DIR = path.dirname(fileURLToPath(import.meta.url));
-const CLI_VERSION = JSON.parse(fs.readFileSync(path.join(CLI_DIR, "..", "package.json"), "utf-8")).version;
-const ckmEngine = createCkmEngine(JSON.parse(ckmRaw));
-const styles = {
-  error: chalk.red,
-  warning: chalk.yellow,
-  success: chalk.green,
-  info: chalk.blue,
-  dim: chalk.gray,
-  bold: chalk.bold
+//#endregion
+//#region src/cli.ts
+var CLI_DIR = path.dirname(fileURLToPath(import.meta.url));
+var CLI_VERSION = JSON.parse(fs.readFileSync(path.join(CLI_DIR, "..", "package.json"), "utf-8")).version;
+var ckmEngine = createCkmEngine(JSON.parse(ckm_default));
+var styles = {
+	error: chalk.red,
+	warning: chalk.yellow,
+	success: chalk.green,
+	info: chalk.blue,
+	dim: chalk.gray,
+	bold: chalk.bold
 };
+/**
+* Resolves the effective project root, checking for project markers.
+* Exits with helpful guidance if not in a project directory.
+*/
 function requireProject(cwd, command) {
-  const result = findProjectRoot(cwd);
-  if (!result.found) {
-    console.error(styles.error(formatNotProjectError(cwd, command)));
-    process.exit(1);
-  }
-  return result.root;
+	const result = findProjectRoot(cwd);
+	if (!result.found) {
+		console.error(styles.error(formatNotProjectError(cwd, command)));
+		process.exit(1);
+	}
+	return result.root;
 }
+/**
+* Creates the VersionGuard CLI program definition.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This function wires all commands, options, and handlers onto a fresh Commander
+* program instance without parsing arguments yet.
+*
+* @returns A configured Commander program for the VersionGuard CLI.
+*
+* @example
+* ```typescript
+* const program = createProgram();
+* console.log(program.name());
+* ```
+*/
 function createProgram() {
-  const program = new Command();
-  program.name("vg").description("Strict versioning enforcement for SemVer and CalVer (alias: versionguard)").version(CLI_VERSION);
-  program.command("init").description("Initialize VersionGuard configuration (interactive wizard or headless)").option("-c, --cwd <path>", "Working directory", process.cwd()).option("-t, --type <type>", "Versioning type: semver or calver").option("-f, --format <format>", "CalVer format tokens (e.g., YYYY.M.MICRO)").option("--allow-v-prefix", "SemVer: allow v-prefix (e.g., v1.2.3)").option("--no-build-metadata", "SemVer: disallow +build metadata").option("--require-prerelease", "SemVer: require prerelease labels").option("--manifest <source>", "Manifest source (e.g., Cargo.toml, pyproject.toml, auto)").option("--hooks", "Install git hooks (default: true)").option("--no-hooks", "Skip git hooks").option("--changelog", "Enable changelog validation (default: true)").option("--no-changelog", "Disable changelog validation").option("-y, --yes", "Accept all defaults, no prompts").option("--force", "Overwrite existing config file").action(
-    async (options) => {
-      try {
-        const isHeadless = options.yes || options.type || options.format || options.manifest || options.allowVPrefix || options.buildMetadata === false || options.requirePrerelease;
-        let configPath;
-        if (isHeadless) {
-          configPath = runHeadless({
-            cwd: options.cwd,
-            type: options.type,
-            format: options.format,
-            allowVPrefix: options.allowVPrefix,
-            allowBuildMetadata: options.buildMetadata,
-            requirePrerelease: options.requirePrerelease,
-            manifest: options.manifest,
-            hooks: options.hooks,
-            changelog: options.changelog,
-            yes: options.yes,
-            force: options.force
-          });
-          console.log(styles.success(`✓ Created ${path.relative(options.cwd, configPath)}`));
-        } else {
-          configPath = await runWizard(options.cwd);
-          if (!configPath) {
-            process.exit(0);
-            return;
-          }
-        }
-        try {
-          const config = getConfig(options.cwd);
-          if (config.git.enforceHooks) {
-            installHooks(config.git, options.cwd);
-            console.log(styles.success("✓ Git hooks installed"));
-          }
-        } catch {
-          console.log(styles.info("ℹ Skipped hooks install (not a git repository)"));
-        }
-      } catch (error) {
-        console.error(styles.error(`✗ ${error.message}`));
-        process.exit(1);
-      }
-    }
-  );
-  program.command("check").description("Check the current version with actionable feedback").option("-c, --cwd <path>", "Working directory", process.cwd()).option("--prev <version>", "Previous version for comparison").option("--json", "Print machine-readable JSON output").action((options) => {
-    try {
-      options.cwd = requireProject(options.cwd, "check");
-      const config = getConfig(options.cwd);
-      const version = getPackageVersion(options.cwd, config.manifest);
-      const result = getVersionFeedback(version, config, options.prev);
-      if (options.json) {
-        console.log(
-          JSON.stringify(
-            {
-              version,
-              versioningType: config.versioning.type,
-              valid: result.valid,
-              errors: result.errors,
-              suggestions: result.suggestions
-            },
-            null,
-            2
-          )
-        );
-        if (!result.valid) {
-          process.exit(1);
-        }
-        return;
-      }
-      console.log(styles.bold(`Current version: ${version}`));
-      console.log(styles.dim(`Versioning type: ${config.versioning.type}`));
-      console.log("");
-      if (result.valid) {
-        console.log(styles.success("✓ Version is valid"));
-        return;
-      }
-      console.log(styles.error("✗ Version has issues:"));
-      console.log("");
-      for (const error of result.errors) {
-        console.log(styles.error(`  ✗ ${error.message}`));
-      }
-      if (result.suggestions.length > 0) {
-        console.log("");
-        console.log(styles.info("How to fix:"));
-        for (const suggestion of result.suggestions) {
-          console.log(`  → ${suggestion.message}`);
-          if (suggestion.fix) {
-            console.log(styles.dim(`    Run: ${suggestion.fix}`));
-          }
-        }
-      }
-      process.exit(1);
-    } catch (error) {
-      console.error(styles.error(`✗ ${error.message}`));
-      process.exit(1);
-    }
-  });
-  program.command("validate").description("Run full validation with smart feedback").option("-c, --cwd <path>", "Working directory", process.cwd()).option("--hook <name>", "Running as git hook").option("--json", "Print machine-readable JSON output").option("--strict", "Run guard checks and fail on any policy gap or bypass").option("--scan", "Run repo-wide scan for stale version literals").action(
-    (options) => {
-      try {
-        options.cwd = requireProject(options.cwd, "validate");
-        const config = getConfig(options.cwd);
-        if (options.scan && config.scan) {
-          config.scan.enabled = true;
-        }
-        const version = getPackageVersion(options.cwd, config.manifest);
-        const result = validate(config, options.cwd);
-        let postTagResult;
-        let guardReport;
-        if (options.hook === "post-tag") {
-          postTagResult = handlePostTag(config, options.cwd);
-        }
-        if (options.strict) {
-          guardReport = runGuardChecks(config, options.cwd);
-        }
-        if (options.json) {
-          console.log(
-            JSON.stringify(
-              {
-                ...result,
-                hook: options.hook ?? null,
-                postTag: postTagResult ?? null,
-                guard: guardReport ?? null
-              },
-              null,
-              2
-            )
-          );
-          if (!result.valid || postTagResult && !postTagResult.success || guardReport && !guardReport.safe) {
-            process.exit(1);
-          }
-          return;
-        }
-        console.log(styles.bold(`Validating version ${version}...`));
-        console.log("");
-        if (!result.syncValid) {
-          console.log(styles.error("Sync Issues:"));
-          for (const error of result.errors.filter((item) => item.includes("mismatch"))) {
-            const parts = error.match(
-              /Version mismatch in (.+):(\d+) - found "(.+?)" but expected "(.+?)"/
-            );
-            if (!parts) {
-              continue;
-            }
-            const suggestions = getSyncFeedback(parts[1], parts[3], parts[4]);
-            console.log(styles.error(`  ✗ ${parts[1]} has wrong version`));
-            console.log(styles.dim(`    Found: "${parts[3]}" Expected: "${parts[4]}"`));
-            if (suggestions[0]?.fix) {
-              console.log(styles.info(`    Fix: ${suggestions[0].fix}`));
-            }
-          }
-          console.log("");
-        }
-        const scanErrors = result.errors.filter((item) => item.startsWith("Stale version"));
-        if (scanErrors.length > 0) {
-          console.log(styles.error("Scan Findings:"));
-          for (const error of scanErrors) {
-            const parts = error.match(
-              /Stale version in (.+):(\d+) - found "(.+?)" but expected "(.+?)"/
-            );
-            if (parts) {
-              console.log(styles.error(`  ✗ ${parts[1]}:${parts[2]} has "${parts[3]}"`));
-            }
-          }
-          console.log(
-            styles.dim("  Hint: add entries to scan.allowlist to exclude intentional references")
-          );
-          console.log("");
-        }
-        if (config.changelog.enabled && !result.changelogValid) {
-          console.log(styles.error("Changelog Issues:"));
-          for (const error of result.errors.filter(
-            (item) => item.toLowerCase().includes("changelog")
-          )) {
-            console.log(styles.error(`  ✗ ${error}`));
-          }
-          const suggestions = getChangelogFeedback(false, version);
-          if (suggestions[0]?.fix) {
-            console.log(styles.info(`Fix: ${suggestions[0].fix}`));
-          }
-          console.log("");
-        }
-        if (postTagResult) {
-          if (!postTagResult.success) {
-            console.log(styles.error(`✗ ${postTagResult.message}`));
-            process.exit(1);
-          }
-        }
-        if (guardReport && guardReport.warnings.length > 0) {
-          console.log(styles.bold("Guard Checks:"));
-          for (const warning of guardReport.warnings) {
-            const icon = warning.severity === "error" ? styles.error("✗") : styles.warning("⚠");
-            console.log(`  ${icon} [${warning.code}] ${warning.message}`);
-            if (warning.fix) {
-              console.log(styles.dim(`    Fix: ${warning.fix}`));
-            }
-          }
-          console.log("");
-        }
-        if (!result.valid || guardReport && !guardReport.safe) {
-          console.log(styles.error("✗ Validation failed"));
-          process.exit(1);
-        }
-        console.log(styles.success("✓ All validations passed"));
-      } catch (error) {
-        console.error(styles.error(`✗ ${error.message}`));
-        process.exit(1);
-      }
-    }
-  );
-  program.command("doctor").description("Report repository readiness in one pass").option("-c, --cwd <path>", "Working directory", process.cwd()).option("--json", "Print machine-readable JSON output").option("--strict", "Include guard checks for bypass detection").action((options) => {
-    try {
-      options.cwd = requireProject(options.cwd, "doctor");
-      const config = getConfig(options.cwd);
-      const report = doctor(config, options.cwd);
-      const guardReport = options.strict ? runGuardChecks(config, options.cwd) : void 0;
-      if (options.json) {
-        console.log(JSON.stringify({ ...report, guard: guardReport ?? null }, null, 2));
-        if (!report.ready || guardReport && !guardReport.safe) {
-          process.exit(1);
-        }
-        return;
-      }
-      console.log(styles.bold("VersionGuard Doctor"));
-      console.log(`  Version: ${report.version || "(missing)"}`);
-      console.log(`  Version valid: ${report.versionValid ? "yes" : "no"}`);
-      console.log(`  Files in sync: ${report.syncValid ? "yes" : "no"}`);
-      console.log(`  Changelog ready: ${report.changelogValid ? "yes" : "no"}`);
-      console.log(`  Git repository: ${report.gitRepository ? "yes" : "no"}`);
-      console.log(
-        `  Hooks installed: ${report.gitRepository ? report.hooksInstalled ? "yes" : "no" : "n/a"}`
-      );
-      console.log(
-        `  Worktree clean: ${report.gitRepository ? report.worktreeClean ? "yes" : "no" : "n/a"}`
-      );
-      if (guardReport) {
-        console.log(`  Guard safe: ${guardReport.safe ? "yes" : "no"}`);
-      }
-      if (!report.ready || guardReport && !guardReport.safe) {
-        console.log("");
-        console.log(styles.error("Issues:"));
-        for (const error of report.errors) {
-          console.log(styles.error(`  ✗ ${error}`));
-        }
-        if (guardReport) {
-          for (const warning of guardReport.warnings) {
-            const icon = warning.severity === "error" ? "✗" : "⚠";
-            console.log(styles.error(`  ${icon} [${warning.code}] ${warning.message}`));
-            if (warning.fix) {
-              console.log(styles.dim(`    Fix: ${warning.fix}`));
-            }
-          }
-        }
-        process.exit(1);
-      }
-      console.log("");
-      console.log(styles.success("✓ Repository is ready"));
-    } catch (error) {
-      console.error(styles.error(`✗ ${error.message}`));
-      process.exit(1);
-    }
-  });
-  program.command("fix").description("Auto-fix detected issues").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
-    try {
-      options.cwd = requireProject(options.cwd, "fix");
-      const config = getConfig(options.cwd);
-      const version = getPackageVersion(options.cwd, config.manifest);
-      const results = fixAll(config, version, options.cwd);
-      console.log(styles.bold(`Fixing issues for version ${version}...`));
-      console.log("");
-      for (const result of results) {
-        const printer = result.fixed ? styles.success : styles.dim;
-        console.log(printer(`${result.fixed ? "✓" : "•"} ${result.message}`));
-      }
-    } catch (error) {
-      console.error(styles.error(`✗ ${error.message}`));
-      process.exit(1);
-    }
-  });
-  program.command("fix-changelog").description("Fix Changesets-mangled changelog into Keep a Changelog format").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
-    try {
-      options.cwd = requireProject(options.cwd, "fix-changelog");
-      const config = getConfig(options.cwd);
-      const changelogPath = path.join(options.cwd, config.changelog.file);
-      if (!isChangesetMangled(changelogPath)) {
-        console.log(styles.dim("• Changelog is not mangled — no fix needed"));
-        return;
-      }
-      const fixed = fixChangesetMangling(changelogPath);
-      if (fixed) {
-        console.log(
-          styles.success(`✓ Restructured ${config.changelog.file} to Keep a Changelog format`)
-        );
-      } else {
-        console.log(styles.dim("• Could not auto-fix changelog structure"));
-      }
-    } catch (error) {
-      console.error(styles.error(`✗ ${error.message}`));
-      process.exit(1);
-    }
-  });
-  program.command("sync").description("Sync version to all configured files").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
-    try {
-      options.cwd = requireProject(options.cwd, "sync");
-      const config = getConfig(options.cwd);
-      const version = getPackageVersion(options.cwd, config.manifest);
-      const results = fixSyncIssues(config, options.cwd);
-      console.log(styles.bold(`Syncing version ${version}...`));
-      for (const result of results) {
-        const printer = result.fixed ? styles.success : styles.dim;
-        console.log(printer(`${result.fixed ? "✓" : "•"} ${result.message}`));
-      }
-    } catch (error) {
-      console.error(styles.error(`✗ ${error.message}`));
-      process.exit(1);
-    }
-  });
-  program.command("bump").description("Suggest and optionally apply the next version").option("-c, --cwd <path>", "Working directory", process.cwd()).option("-t, --type <type>", "Bump type (major, minor, patch, auto)").option("--apply", "Apply the first suggested version").action(
-    (options) => {
-      try {
-        options.cwd = requireProject(options.cwd, "bump");
-        const config = getConfig(options.cwd);
-        const currentVersion = getPackageVersion(options.cwd, config.manifest);
-        const suggestions = suggestNextVersion(currentVersion, config, options.type);
-        console.log(styles.bold(`Current version: ${currentVersion}`));
-        console.log("");
-        for (const [index, suggestion] of suggestions.entries()) {
-          console.log(`  ${index + 1}. ${styles.bold(suggestion.version)}`);
-          console.log(`     ${styles.dim(suggestion.reason)}`);
-        }
-        if (options.apply) {
-          const nextVersion = suggestions[0]?.version;
-          if (!nextVersion) {
-            throw new Error("No version suggestion available");
-          }
-          setPackageVersion(nextVersion, options.cwd, config.manifest);
-          fixAll(config, nextVersion, options.cwd);
-          console.log(styles.success(`✓ Updated to ${nextVersion}`));
-        }
-      } catch (error) {
-        console.error(styles.error(`✗ ${error.message}`));
-        process.exit(1);
-      }
-    }
-  );
-  program.command("tag").description("Create a git tag with automation").argument("[version]", "Version to tag (defaults to manifest version)").option("-c, --cwd <path>", "Working directory", process.cwd()).option("-m, --message <msg>", "Tag message").option("--no-fix", "Skip auto-fixing files before tagging").action(
-    (version, options) => {
-      try {
-        options.cwd = requireProject(options.cwd, "tag");
-        const config = getConfig(options.cwd);
-        const tagVersion = version || getPackageVersion(options.cwd, config.manifest);
-        const result = createTag(
-          tagVersion,
-          options.message,
-          options.fix !== false,
-          config,
-          options.cwd
-        );
-        if (!result.success) {
-          console.log(styles.error(`✗ ${result.message}`));
-          process.exit(1);
-        }
-        console.log(styles.success(`✓ ${result.message}`));
-        for (const action of result.actions) {
-          console.log(`  • ${action}`);
-        }
-      } catch (error) {
-        console.error(styles.error(`✗ ${error.message}`));
-        process.exit(1);
-      }
-    }
-  );
-  program.command("ckm [topic]").description("Codebase Knowledge Manifest — auto-generated docs and help").option("--json", "Machine-readable CKM output for LLM agents").option("--llm", "Full API context (forge-ts llms.txt)").action((topic, options) => {
-    if (options.llm) {
-      console.log(llmsRaw);
-      return;
-    }
-    if (options.json) {
-      console.log(JSON.stringify(ckmEngine.getTopicJson(topic), null, 2));
-      return;
-    }
-    if (topic) {
-      const content = ckmEngine.getTopicContent(topic);
-      if (!content) {
-        console.error(styles.error(`Unknown topic: ${topic}`));
-        console.log("");
-        console.log(ckmEngine.getTopicIndex("vg"));
-        process.exit(1);
-      }
-      console.log(content);
-    } else {
-      console.log(ckmEngine.getTopicIndex("vg"));
-    }
-  });
-  const hooksCommand = program.command("hooks").description("Manage git hooks");
-  hooksCommand.command("install").description("Install git hooks").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
-    try {
-      options.cwd = requireProject(options.cwd, "hooks install");
-      const config = getConfig(options.cwd);
-      installHooks(config.git, options.cwd);
-      console.log(styles.success("✓ Git hooks installed"));
-    } catch (error) {
-      console.error(styles.error(`✗ ${error.message}`));
-      process.exit(1);
-    }
-  });
-  hooksCommand.command("uninstall").description("Uninstall git hooks").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
-    try {
-      options.cwd = requireProject(options.cwd, "hooks uninstall");
-      uninstallHooks(options.cwd);
-      console.log(styles.success("✓ Git hooks uninstalled"));
-    } catch (error) {
-      console.error(styles.error(`✗ ${error.message}`));
-      process.exit(1);
-    }
-  });
-  hooksCommand.command("status").description("Check if hooks are installed").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
-    try {
-      options.cwd = requireProject(options.cwd, "hooks status");
-      if (areHooksInstalled(options.cwd)) {
-        console.log(styles.success("✓ VersionGuard hooks are installed"));
-        return;
-      }
-      console.log(styles.warning("✗ VersionGuard hooks are not installed"));
-      process.exit(1);
-    } catch (error) {
-      console.error(styles.error(`✗ ${error.message}`));
-      process.exit(1);
-    }
-  });
-  return program;
+	const program = new Command();
+	program.name("vg").description("Strict versioning enforcement for SemVer and CalVer (alias: versionguard)").version(CLI_VERSION);
+	program.command("init").description("Initialize VersionGuard configuration (interactive wizard or headless)").option("-c, --cwd <path>", "Working directory", process.cwd()).option("-t, --type <type>", "Versioning type: semver or calver").option("-f, --format <format>", "CalVer format tokens (e.g., YYYY.M.MICRO)").option("--allow-v-prefix", "SemVer: allow v-prefix (e.g., v1.2.3)").option("--no-build-metadata", "SemVer: disallow +build metadata").option("--require-prerelease", "SemVer: require prerelease labels").option("--manifest <source>", "Manifest source (e.g., Cargo.toml, pyproject.toml, auto)").option("--hooks", "Install git hooks (default: true)").option("--no-hooks", "Skip git hooks").option("--changelog", "Enable changelog validation (default: true)").option("--no-changelog", "Disable changelog validation").option("--github", "Generate GitHub integration files (default: true)").option("--no-github", "Skip GitHub integration (dependabot.yml)").option("-y, --yes", "Accept all defaults, no prompts").option("--force", "Overwrite existing config file").action(async (options) => {
+		try {
+			const isHeadless = options.yes || options.type || options.format || options.manifest || options.allowVPrefix || options.buildMetadata === false || options.requirePrerelease;
+			let configPath;
+			if (isHeadless) {
+				configPath = runHeadless({
+					cwd: options.cwd,
+					type: options.type,
+					format: options.format,
+					allowVPrefix: options.allowVPrefix,
+					allowBuildMetadata: options.buildMetadata,
+					requirePrerelease: options.requirePrerelease,
+					manifest: options.manifest,
+					github: options.github,
+					hooks: options.hooks,
+					changelog: options.changelog,
+					yes: options.yes,
+					force: options.force
+				});
+				console.log(styles.success(`✓ Created ${path.relative(options.cwd, configPath)}`));
+			} else {
+				configPath = await runWizard(options.cwd);
+				if (!configPath) {
+					process.exit(0);
+					return;
+				}
+			}
+			try {
+				const config = getConfig(options.cwd);
+				if (config.git.enforceHooks) {
+					installHooks(config.git, options.cwd);
+					console.log(styles.success("✓ Git hooks installed"));
+				}
+			} catch {
+				console.log(styles.info("ℹ Skipped hooks install (not a git repository)"));
+			}
+		} catch (error) {
+			console.error(styles.error(`✗ ${error.message}`));
+			process.exit(1);
+		}
+	});
+	program.command("check").description("Check the current version with actionable feedback").option("-c, --cwd <path>", "Working directory", process.cwd()).option("--prev <version>", "Previous version for comparison").option("--json", "Print machine-readable JSON output").action((options) => {
+		try {
+			options.cwd = requireProject(options.cwd, "check");
+			const config = getConfig(options.cwd);
+			const version = getPackageVersion(options.cwd, config.manifest);
+			const result = getVersionFeedback(version, config, options.prev);
+			if (options.json) {
+				console.log(JSON.stringify({
+					version,
+					versioningType: config.versioning.type,
+					valid: result.valid,
+					errors: result.errors,
+					suggestions: result.suggestions
+				}, null, 2));
+				if (!result.valid) process.exit(1);
+				return;
+			}
+			console.log(styles.bold(`Current version: ${version}`));
+			console.log(styles.dim(`Versioning type: ${config.versioning.type}`));
+			console.log("");
+			if (result.valid) {
+				console.log(styles.success("✓ Version is valid"));
+				return;
+			}
+			console.log(styles.error("✗ Version has issues:"));
+			console.log("");
+			for (const error of result.errors) console.log(styles.error(`  ✗ ${error.message}`));
+			if (result.suggestions.length > 0) {
+				console.log("");
+				console.log(styles.info("How to fix:"));
+				for (const suggestion of result.suggestions) {
+					console.log(`  → ${suggestion.message}`);
+					if (suggestion.fix) console.log(styles.dim(`    Run: ${suggestion.fix}`));
+				}
+			}
+			process.exit(1);
+		} catch (error) {
+			console.error(styles.error(`✗ ${error.message}`));
+			process.exit(1);
+		}
+	});
+	program.command("validate").description("Run full validation with smart feedback").option("-c, --cwd <path>", "Working directory", process.cwd()).option("--hook <name>", "Running as git hook").option("--json", "Print machine-readable JSON output").option("--strict", "Run guard checks and fail on any policy gap or bypass").option("--scan", "Run repo-wide scan for stale version literals").action((options) => {
+		try {
+			options.cwd = requireProject(options.cwd, "validate");
+			const config = getConfig(options.cwd);
+			if (options.scan && config.scan) config.scan.enabled = true;
+			const version = getPackageVersion(options.cwd, config.manifest);
+			const result = validate(config, options.cwd);
+			let postTagResult;
+			let guardReport;
+			if (options.hook === "post-tag") postTagResult = handlePostTag(config, options.cwd);
+			if (options.strict) guardReport = runGuardChecks(config, options.cwd);
+			if (options.json) {
+				console.log(JSON.stringify({
+					...result,
+					hook: options.hook ?? null,
+					postTag: postTagResult ?? null,
+					guard: guardReport ?? null
+				}, null, 2));
+				if (!result.valid || postTagResult && !postTagResult.success || guardReport && !guardReport.safe) process.exit(1);
+				return;
+			}
+			console.log(styles.bold(`Validating version ${version}...`));
+			console.log("");
+			if (!result.syncValid) {
+				console.log(styles.error("Sync Issues:"));
+				for (const error of result.errors.filter((item) => item.includes("mismatch"))) {
+					const parts = error.match(/Version mismatch in (.+):(\d+) - found "(.+?)" but expected "(.+?)"/);
+					if (!parts) continue;
+					const suggestions = getSyncFeedback(parts[1], parts[3], parts[4]);
+					console.log(styles.error(`  ✗ ${parts[1]} has wrong version`));
+					console.log(styles.dim(`    Found: "${parts[3]}" Expected: "${parts[4]}"`));
+					if (suggestions[0]?.fix) console.log(styles.info(`    Fix: ${suggestions[0].fix}`));
+				}
+				console.log("");
+			}
+			const scanErrors = result.errors.filter((item) => item.startsWith("Stale version"));
+			if (scanErrors.length > 0) {
+				console.log(styles.error("Scan Findings:"));
+				for (const error of scanErrors) {
+					const parts = error.match(/Stale version in (.+):(\d+) - found "(.+?)" but expected "(.+?)"/);
+					if (parts) console.log(styles.error(`  ✗ ${parts[1]}:${parts[2]} has "${parts[3]}"`));
+				}
+				console.log(styles.dim("  Hint: add entries to scan.allowlist to exclude intentional references"));
+				console.log("");
+			}
+			if (config.changelog.enabled && !result.changelogValid) {
+				console.log(styles.error("Changelog Issues:"));
+				for (const error of result.errors.filter((item) => item.toLowerCase().includes("changelog"))) console.log(styles.error(`  ✗ ${error}`));
+				const suggestions = getChangelogFeedback(false, version);
+				if (suggestions[0]?.fix) console.log(styles.info(`Fix: ${suggestions[0].fix}`));
+				console.log("");
+			}
+			if (postTagResult) {
+				if (!postTagResult.success) {
+					console.log(styles.error(`✗ ${postTagResult.message}`));
+					process.exit(1);
+				}
+			}
+			if (guardReport && guardReport.warnings.length > 0) {
+				console.log(styles.bold("Guard Checks:"));
+				for (const warning of guardReport.warnings) {
+					const icon = warning.severity === "error" ? styles.error("✗") : styles.warning("⚠");
+					console.log(`  ${icon} [${warning.code}] ${warning.message}`);
+					if (warning.fix) console.log(styles.dim(`    Fix: ${warning.fix}`));
+				}
+				console.log("");
+			}
+			if (!result.valid || guardReport && !guardReport.safe) {
+				console.log(styles.error("✗ Validation failed"));
+				process.exit(1);
+			}
+			console.log(styles.success("✓ All validations passed"));
+		} catch (error) {
+			console.error(styles.error(`✗ ${error.message}`));
+			process.exit(1);
+		}
+	});
+	program.command("doctor").description("Report repository readiness in one pass").option("-c, --cwd <path>", "Working directory", process.cwd()).option("--json", "Print machine-readable JSON output").option("--strict", "Include guard checks for bypass detection").action((options) => {
+		try {
+			options.cwd = requireProject(options.cwd, "doctor");
+			const config = getConfig(options.cwd);
+			const report = doctor(config, options.cwd);
+			const guardReport = options.strict ? runGuardChecks(config, options.cwd) : void 0;
+			if (options.json) {
+				console.log(JSON.stringify({
+					...report,
+					guard: guardReport ?? null
+				}, null, 2));
+				if (!report.ready || guardReport && !guardReport.safe) process.exit(1);
+				return;
+			}
+			console.log(styles.bold("VersionGuard Doctor"));
+			console.log(`  Version: ${report.version || "(missing)"}`);
+			console.log(`  Version valid: ${report.versionValid ? "yes" : "no"}`);
+			console.log(`  Files in sync: ${report.syncValid ? "yes" : "no"}`);
+			console.log(`  Changelog ready: ${report.changelogValid ? "yes" : "no"}`);
+			console.log(`  Git repository: ${report.gitRepository ? "yes" : "no"}`);
+			console.log(`  Hooks installed: ${report.gitRepository ? report.hooksInstalled ? "yes" : "no" : "n/a"}`);
+			console.log(`  Worktree clean: ${report.gitRepository ? report.worktreeClean ? "yes" : "no" : "n/a"}`);
+			if (guardReport) console.log(`  Guard safe: ${guardReport.safe ? "yes" : "no"}`);
+			if (!report.ready || guardReport && !guardReport.safe) {
+				console.log("");
+				console.log(styles.error("Issues:"));
+				for (const error of report.errors) console.log(styles.error(`  ✗ ${error}`));
+				if (guardReport) for (const warning of guardReport.warnings) {
+					const icon = warning.severity === "error" ? "✗" : "⚠";
+					console.log(styles.error(`  ${icon} [${warning.code}] ${warning.message}`));
+					if (warning.fix) console.log(styles.dim(`    Fix: ${warning.fix}`));
+				}
+				process.exit(1);
+			}
+			console.log("");
+			console.log(styles.success("✓ Repository is ready"));
+		} catch (error) {
+			console.error(styles.error(`✗ ${error.message}`));
+			process.exit(1);
+		}
+	});
+	program.command("fix").description("Auto-fix detected issues").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
+		try {
+			options.cwd = requireProject(options.cwd, "fix");
+			const config = getConfig(options.cwd);
+			const version = getPackageVersion(options.cwd, config.manifest);
+			const results = fixAll(config, version, options.cwd);
+			console.log(styles.bold(`Fixing issues for version ${version}...`));
+			console.log("");
+			for (const result of results) {
+				const printer = result.fixed ? styles.success : styles.dim;
+				console.log(printer(`${result.fixed ? "✓" : "•"} ${result.message}`));
+			}
+		} catch (error) {
+			console.error(styles.error(`✗ ${error.message}`));
+			process.exit(1);
+		}
+	});
+	program.command("fix-changelog").description("Fix Changesets-mangled changelog into Keep a Changelog format").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
+		try {
+			options.cwd = requireProject(options.cwd, "fix-changelog");
+			const config = getConfig(options.cwd);
+			const changelogPath = path.join(options.cwd, config.changelog.file);
+			if (!isChangesetMangled(changelogPath)) {
+				console.log(styles.dim("• Changelog is not mangled — no fix needed"));
+				return;
+			}
+			if (fixChangesetMangling(changelogPath)) console.log(styles.success(`✓ Restructured ${config.changelog.file} to Keep a Changelog format`));
+			else console.log(styles.dim("• Could not auto-fix changelog structure"));
+		} catch (error) {
+			console.error(styles.error(`✗ ${error.message}`));
+			process.exit(1);
+		}
+	});
+	program.command("sync").description("Sync version to all configured files").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
+		try {
+			options.cwd = requireProject(options.cwd, "sync");
+			const config = getConfig(options.cwd);
+			const version = getPackageVersion(options.cwd, config.manifest);
+			const results = fixSyncIssues(config, options.cwd);
+			console.log(styles.bold(`Syncing version ${version}...`));
+			for (const result of results) {
+				const printer = result.fixed ? styles.success : styles.dim;
+				console.log(printer(`${result.fixed ? "✓" : "•"} ${result.message}`));
+			}
+		} catch (error) {
+			console.error(styles.error(`✗ ${error.message}`));
+			process.exit(1);
+		}
+	});
+	program.command("bump").description("Suggest and optionally apply the next version").option("-c, --cwd <path>", "Working directory", process.cwd()).option("-t, --type <type>", "Bump type (major, minor, patch, auto)").option("--apply", "Apply the first suggested version").action((options) => {
+		try {
+			options.cwd = requireProject(options.cwd, "bump");
+			const config = getConfig(options.cwd);
+			const currentVersion = getPackageVersion(options.cwd, config.manifest);
+			const suggestions = suggestNextVersion(currentVersion, config, options.type);
+			console.log(styles.bold(`Current version: ${currentVersion}`));
+			console.log("");
+			for (const [index, suggestion] of suggestions.entries()) {
+				console.log(`  ${index + 1}. ${styles.bold(suggestion.version)}`);
+				console.log(`     ${styles.dim(suggestion.reason)}`);
+			}
+			if (options.apply) {
+				const nextVersion = suggestions[0]?.version;
+				if (!nextVersion) throw new Error("No version suggestion available");
+				setPackageVersion(nextVersion, options.cwd, config.manifest);
+				fixAll(config, nextVersion, options.cwd);
+				console.log(styles.success(`✓ Updated to ${nextVersion}`));
+			}
+		} catch (error) {
+			console.error(styles.error(`✗ ${error.message}`));
+			process.exit(1);
+		}
+	});
+	program.command("tag").description("Create a git tag with automation").argument("[version]", "Version to tag (defaults to manifest version)").option("-c, --cwd <path>", "Working directory", process.cwd()).option("-m, --message <msg>", "Tag message").option("--no-fix", "Skip auto-fixing files before tagging").action((version, options) => {
+		try {
+			options.cwd = requireProject(options.cwd, "tag");
+			const config = getConfig(options.cwd);
+			const result = createTag(version || getPackageVersion(options.cwd, config.manifest), options.message, options.fix !== false, config, options.cwd);
+			if (!result.success) {
+				console.log(styles.error(`✗ ${result.message}`));
+				process.exit(1);
+			}
+			console.log(styles.success(`✓ ${result.message}`));
+			for (const action of result.actions) console.log(`  • ${action}`);
+		} catch (error) {
+			console.error(styles.error(`✗ ${error.message}`));
+			process.exit(1);
+		}
+	});
+	program.command("ckm [topic]").description("Codebase Knowledge Manifest — auto-generated docs and help").option("--json", "Machine-readable CKM output for LLM agents").option("--llm", "Full API context (forge-ts llms.txt)").action((topic, options) => {
+		if (options.llm) {
+			console.log(llms_default);
+			return;
+		}
+		if (options.json) {
+			console.log(JSON.stringify(ckmEngine.getTopicJson(topic), null, 2));
+			return;
+		}
+		if (topic) {
+			const content = ckmEngine.getTopicContent(topic);
+			if (!content) {
+				console.error(styles.error(`Unknown topic: ${topic}`));
+				console.log("");
+				console.log(ckmEngine.getTopicIndex("vg"));
+				process.exit(1);
+			}
+			console.log(content);
+		} else console.log(ckmEngine.getTopicIndex("vg"));
+	});
+	const hooksCommand = program.command("hooks").description("Manage git hooks");
+	hooksCommand.command("install").description("Install git hooks").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
+		try {
+			options.cwd = requireProject(options.cwd, "hooks install");
+			installHooks(getConfig(options.cwd).git, options.cwd);
+			console.log(styles.success("✓ Git hooks installed"));
+		} catch (error) {
+			console.error(styles.error(`✗ ${error.message}`));
+			process.exit(1);
+		}
+	});
+	hooksCommand.command("uninstall").description("Uninstall git hooks").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
+		try {
+			options.cwd = requireProject(options.cwd, "hooks uninstall");
+			uninstallHooks(options.cwd);
+			console.log(styles.success("✓ Git hooks uninstalled"));
+		} catch (error) {
+			console.error(styles.error(`✗ ${error.message}`));
+			process.exit(1);
+		}
+	});
+	hooksCommand.command("status").description("Check if hooks are installed").option("-c, --cwd <path>", "Working directory", process.cwd()).action((options) => {
+		try {
+			options.cwd = requireProject(options.cwd, "hooks status");
+			if (areHooksInstalled(options.cwd)) {
+				console.log(styles.success("✓ VersionGuard hooks are installed"));
+				return;
+			}
+			console.log(styles.warning("✗ VersionGuard hooks are not installed"));
+			process.exit(1);
+		} catch (error) {
+			console.error(styles.error(`✗ ${error.message}`));
+			process.exit(1);
+		}
+	});
+	return program;
 }
+/**
+* Parses CLI arguments and executes the matching command.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This helper delegates argument parsing to the Commander program created by
+* {@link createProgram}. It resolves when the selected command finishes.
+*
+* @param argv - Full argument vector to parse.
+* @see {@link createProgram}
+*
+* @example
+* ```typescript
+* const argv = ['node', 'versionguard', 'check'];
+* await runCli(argv);
+* ```
+*/
 async function runCli(argv = process.argv) {
-  await createProgram().parseAsync(argv);
+	await createProgram().parseAsync(argv);
 }
+/**
+* Determines whether the current module is the invoked CLI entry point.
+*
+* @public
+* @since 0.1.0
+* @remarks
+* This helper compares the resolved script path from `argv` with the current
+* module URL so the CLI runs only during direct execution.
+*
+* @param argv - Full process argument vector.
+* @param metaUrl - Module URL to compare against the invoked entry path.
+* @returns `true` when the current module should launch the CLI.
+*
+* @example
+* ```typescript
+* const shouldRun = shouldRunCli(process.argv, import.meta.url);
+* console.log(shouldRun);
+* ```
+*/
 function shouldRunCli(argv = process.argv, metaUrl = import.meta.url) {
-  if (!argv[1]) return false;
-  const metaPath = fileURLToPath(metaUrl);
-  const resolved = path.resolve(argv[1]);
-  try {
-    return fs.realpathSync(resolved) === metaPath;
-  } catch {
-    return resolved === metaPath;
-  }
-}
-if (shouldRunCli()) {
-  void runCli();
+	if (!argv[1]) return false;
+	const metaPath = fileURLToPath(metaUrl);
+	const resolved = path.resolve(argv[1]);
+	try {
+		return fs.realpathSync(resolved) === metaPath;
+	} catch {
+		return resolved === metaPath;
+	}
 }
-export {
-  createProgram,
-  runCli,
-  shouldRunCli
-};
-//# sourceMappingURL=cli.js.map
+/* v8 ignore start -- exercised only by direct CLI execution */
+if (shouldRunCli()) runCli();
+/* v8 ignore stop */
+//#endregion
+export { createProgram, runCli, shouldRunCli };
+
+//# sourceMappingURL=cli.js.map