@codluv/versionguard 0.5.0 → 0.7.0

package/dist/cli.js

@@ -4,1020 +4,11 @@ import * as path from "node:path";
 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-CwOyEn5L.js";
+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-DWiw8Nps.js";
 import * as p from "@clack/prompts";
 import * as yaml from "js-yaml";
-const ckmRaw = `{
-  "$schema": "https://forge-ts.dev/schemas/ckm/v1.json",
-  "version": "1.0.0",
-  "project": "@codluv/versionguard",
-  "generated": "2026-03-26T15:45:30.788Z",
-  "concepts": [
-    {
-      "id": "concept-ManifestConfig",
-      "name": "ManifestConfig",
-      "what": "Configures the version source manifest.",
-      "properties": [
-        {
-          "name": "source",
-          "type": "ManifestSourceType",
-          "description": "Manifest file to read the version from.  Use \`'auto'\` for file-existence detection or a specific filename."
-        },
-        {
-          "name": "path",
-          "type": "string | undefined",
-          "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."
-        },
-        {
-          "name": "regex",
-          "type": "string | undefined",
-          "description": "Regex pattern to extract the version from source-code manifests.  Capture group 1 must contain the version string."
-        }
-      ]
-    },
-    {
-      "id": "concept-CalVerConfig",
-      "name": "CalVerConfig",
-      "what": "Configures CalVer validation rules.",
-      "properties": [
-        {
-          "name": "format",
-          "type": "CalVerFormat",
-          "description": "Calendar format used when parsing and validating versions."
-        },
-        {
-          "name": "preventFutureDates",
-          "type": "boolean",
-          "description": "Rejects versions that point to a future date."
-        },
-        {
-          "name": "strictMutualExclusion",
-          "type": "boolean | undefined",
-          "description": "Enforces that week tokens (WW/0W) cannot be mixed with month/day tokens."
-        }
-      ]
-    },
-    {
-      "id": "concept-SyncConfig",
-      "name": "SyncConfig",
-      "what": "Configures files and patterns that should stay in sync with the canonical version.",
-      "properties": [
-        {
-          "name": "files",
-          "type": "string[]",
-          "description": "File globs or paths that should be scanned for version updates."
-        },
-        {
-          "name": "patterns",
-          "type": "SyncPattern[]",
-          "description": "Replacement patterns applied to matching files."
-        }
-      ]
-    },
-    {
-      "id": "concept-ChangelogConfig",
-      "name": "ChangelogConfig",
-      "what": "Controls changelog validation behavior.",
-      "properties": [
-        {
-          "name": "enabled",
-          "type": "boolean",
-          "description": "Enables changelog validation."
-        },
-        {
-          "name": "file",
-          "type": "string",
-          "description": "Path to the changelog file to inspect."
-        },
-        {
-          "name": "strict",
-          "type": "boolean",
-          "description": "Treats changelog problems as hard failures."
-        },
-        {
-          "name": "requireEntry",
-          "type": "boolean",
-          "description": "Requires an entry for the current version."
-        }
-      ]
-    },
-    {
-      "id": "concept-GitHooksConfig",
-      "name": "GitHooksConfig",
-      "what": "Toggles each supported git hook integration.",
-      "properties": [
-        {
-          "name": "'pre-commit'",
-          "type": "boolean",
-          "description": "Enables validation during the \`pre-commit\` hook."
-        },
-        {
-          "name": "'pre-push'",
-          "type": "boolean",
-          "description": "Enables validation during the \`pre-push\` hook."
-        },
-        {
-          "name": "'post-tag'",
-          "type": "boolean",
-          "description": "Enables follow-up tasks after a tag is created."
-        }
-      ]
-    },
-    {
-      "id": "concept-GitConfig",
-      "name": "GitConfig",
-      "what": "Configures git-related enforcement.",
-      "properties": [
-        {
-          "name": "hooks",
-          "type": "GitHooksConfig",
-          "description": "Hook toggles used by the CLI and validation workflow."
-        },
-        {
-          "name": "enforceHooks",
-          "type": "boolean",
-          "description": "Fails validation when required hooks are missing."
-        }
-      ]
-    },
-    {
-      "id": "concept-VersioningConfig",
-      "name": "VersioningConfig",
-      "what": "Configures the active versioning mode.",
-      "properties": [
-        {
-          "name": "type",
-          "type": "VersioningType",
-          "description": "Versioning strategy used for the project."
-        },
-        {
-          "name": "schemeRules",
-          "type": "SchemeRules | undefined",
-          "description": "Scheme-level validation rules applied regardless of versioning type."
-        },
-        {
-          "name": "calver",
-          "type": "CalVerConfig | undefined",
-          "description": "CalVer-specific settings when \`type\` is \`'calver'\`."
-        }
-      ]
-    },
-    {
-      "id": "concept-VersionGuardConfig",
-      "name": "VersionGuardConfig",
-      "what": "Top-level configuration consumed by versionguard.",
-      "properties": [
-        {
-          "name": "versioning",
-          "type": "VersioningConfig",
-          "description": "Active versioning settings."
-        },
-        {
-          "name": "manifest",
-          "type": "ManifestConfig",
-          "description": "Version source manifest settings."
-        },
-        {
-          "name": "sync",
-          "type": "SyncConfig",
-          "description": "Synchronization settings for mirrored version strings."
-        },
-        {
-          "name": "changelog",
-          "type": "ChangelogConfig",
-          "description": "Changelog validation settings."
-        },
-        {
-          "name": "git",
-          "type": "GitConfig",
-          "description": "Git enforcement settings."
-        },
-        {
-          "name": "ignore",
-          "type": "string[]",
-          "description": "Files or patterns excluded from validation."
-        }
-      ]
-    },
-    {
-      "id": "concept-ValidationResult",
-      "name": "ValidationResult",
-      "what": "Result returned by version parsing and validation helpers.",
-      "properties": [
-        {
-          "name": "valid",
-          "type": "boolean",
-          "description": "Indicates whether validation completed without errors."
-        },
-        {
-          "name": "errors",
-          "type": "ValidationError[]",
-          "description": "Collected validation issues."
-        },
-        {
-          "name": "version",
-          "type": "ParsedVersion | undefined",
-          "description": "Parsed version details when validation succeeds."
-        }
-      ]
-    },
-    {
-      "id": "concept-SyncResult",
-      "name": "SyncResult",
-      "what": "Reports the result of synchronizing a single file.",
-      "properties": [
-        {
-          "name": "file",
-          "type": "string",
-          "description": "File that was inspected or updated."
-        },
-        {
-          "name": "updated",
-          "type": "boolean",
-          "description": "Indicates whether the file content changed."
-        },
-        {
-          "name": "changes",
-          "type": "SyncChange[]",
-          "description": "Detailed replacements applied within the file."
-        }
-      ]
-    },
-    {
-      "id": "concept-FullValidationResult",
-      "name": "FullValidationResult",
-      "what": "Combined result from a full project validation run.",
-      "properties": [
-        {
-          "name": "valid",
-          "type": "boolean",
-          "description": "Indicates whether all checks passed."
-        },
-        {
-          "name": "version",
-          "type": "string",
-          "description": "Canonical version string used for validation."
-        },
-        {
-          "name": "versionValid",
-          "type": "boolean",
-          "description": "Indicates whether the root version string is valid."
-        },
-        {
-          "name": "syncValid",
-          "type": "boolean",
-          "description": "Indicates whether synchronized files are in sync."
-        },
-        {
-          "name": "changelogValid",
-          "type": "boolean",
-          "description": "Indicates whether changelog checks passed."
-        },
-        {
-          "name": "errors",
-          "type": "string[]",
-          "description": "Human-readable validation failures collected during the run."
-        }
-      ]
-    },
-    {
-      "id": "concept-ChangelogValidationResult",
-      "name": "ChangelogValidationResult",
-      "what": "Describes the outcome of validating a changelog file.",
-      "properties": [
-        {
-          "name": "valid",
-          "type": "boolean",
-          "description": "Indicates whether the changelog satisfies all requested checks."
-        },
-        {
-          "name": "errors",
-          "type": "string[]",
-          "description": "Human-readable validation errors."
-        },
-        {
-          "name": "hasEntryForVersion",
-          "type": "boolean",
-          "description": "Indicates whether the changelog contains an entry for the requested version."
-        }
-      ]
-    },
-    {
-      "id": "concept-FeedbackResult",
-      "name": "FeedbackResult",
-      "what": "Aggregates validation errors with suggested next steps.",
-      "properties": [
-        {
-          "name": "valid",
-          "type": "boolean",
-          "description": "Indicates whether the inspected version state is valid."
-        },
-        {
-          "name": "errors",
-          "type": "ValidationError[]",
-          "description": "Validation errors collected during the check."
-        },
-        {
-          "name": "suggestions",
-          "type": "Suggestion[]",
-          "description": "Suggested next steps for resolving the reported issues."
-        },
-        {
-          "name": "canAutoFix",
-          "type": "boolean",
-          "description": "Indicates whether at least one suggestion can be auto-applied."
-        }
-      ]
-    },
-    {
-      "id": "concept-FixResult",
-      "name": "FixResult",
-      "what": "Fix entry point exports for auto-remediation helpers.",
-      "properties": [
-        {
-          "name": "fixed",
-          "type": "boolean",
-          "description": "Indicates whether the operation changed repository state."
-        },
-        {
-          "name": "message",
-          "type": "string",
-          "description": "Human-readable description of the fix attempt."
-        },
-        {
-          "name": "file",
-          "type": "string | undefined",
-          "description": "Absolute path to the file that was updated, when applicable."
-        }
-      ]
-    },
-    {
-      "id": "concept-ProjectRootResult",
-      "name": "ProjectRootResult",
-      "what": "Result of project root detection.",
-      "properties": [
-        {
-          "name": "found",
-          "type": "boolean",
-          "description": "Whether a project root was found."
-        },
-        {
-          "name": "root",
-          "type": "string",
-          "description": "The resolved project root directory, or the original cwd if not found."
-        },
-        {
-          "name": "marker",
-          "type": "string | undefined",
-          "description": "Which marker file was found."
-        },
-        {
-          "name": "hasConfig",
-          "type": "boolean",
-          "description": "Whether the directory has a VersionGuard config."
-        },
-        {
-          "name": "hasGit",
-          "type": "boolean",
-          "description": "Whether the directory is inside a git repository."
-        },
-        {
-          "name": "hasManifest",
-          "type": "boolean",
-          "description": "Whether a version manifest file exists."
-        }
-      ]
-    },
-    {
-      "id": "concept-InitOptions",
-      "name": "InitOptions",
-      "what": "Options for headless (non-interactive) initialization.",
-      "properties": [
-        {
-          "name": "cwd",
-          "type": "string",
-          "description": "Working directory path."
-        },
-        {
-          "name": "type",
-          "type": "\\"semver\\" | \\"calver\\" | undefined",
-          "description": "Versioning type (semver or calver)."
-        },
-        {
-          "name": "format",
-          "type": "string | undefined",
-          "description": "CalVer format string."
-        },
-        {
-          "name": "manifest",
-          "type": "string | undefined",
-          "description": "Manifest source type."
-        },
-        {
-          "name": "hooks",
-          "type": "boolean | undefined",
-          "description": "Whether to install git hooks."
-        },
-        {
-          "name": "changelog",
-          "type": "boolean | undefined",
-          "description": "Whether to enable changelog validation."
-        },
-        {
-          "name": "yes",
-          "type": "boolean | undefined",
-          "description": "Accept defaults without prompting."
-        },
-        {
-          "name": "force",
-          "type": "boolean | undefined",
-          "description": "Overwrite existing config."
-        }
-      ]
-    }
-  ],
-  "operations": [
-    {
-      "id": "op-validate",
-      "name": "validate",
-      "what": "Validates a CalVer string against formatting and date rules.",
-      "inputs": [
-        {
-          "name": "version",
-          "type": "unknown",
-          "required": true,
-          "description": "Version string to validate."
-        },
-        {
-          "name": "calverFormat",
-          "type": "unknown",
-          "required": true,
-          "description": "Format expected for the version string."
-        },
-        {
-          "name": "preventFutureDates",
-          "type": "unknown",
-          "required": true,
-          "description": "Whether future dates should be reported as errors."
-        },
-        {
-          "name": "schemeRules",
-          "type": "unknown",
-          "required": true,
-          "description": "Optional scheme rules for modifier validation and segment count warnings."
-        }
-      ],
-      "outputs": {
-        "text": "A validation result containing any discovered errors and the parsed version on success."
-      }
-    },
-    {
-      "id": "op-validateChangelog",
-      "name": "validateChangelog",
-      "what": "Validates a changelog file for release readiness.",
-      "inputs": [
-        {
-          "name": "changelogPath",
-          "type": "unknown",
-          "required": true,
-          "description": "Path to the changelog file."
-        },
-        {
-          "name": "version",
-          "type": "unknown",
-          "required": true,
-          "description": "Version that must be present in the changelog."
-        },
-        {
-          "name": "strict",
-          "type": "unknown",
-          "required": true,
-          "description": "Whether to require compare links and dated release headings."
-        },
-        {
-          "name": "requireEntry",
-          "type": "unknown",
-          "required": true,
-          "description": "Whether the requested version must already have an entry."
-        }
-      ],
-      "outputs": {
-        "text": "The result of validating the changelog file."
-      }
-    },
-    {
-      "id": "op-checkHardcodedVersions",
-      "name": "checkHardcodedVersions",
-      "what": "Checks configured files for hardcoded version mismatches.",
-      "inputs": [
-        {
-          "name": "expectedVersion",
-          "type": "unknown",
-          "required": true,
-          "description": "Version all matching entries should use."
-        },
-        {
-          "name": "config",
-          "type": "unknown",
-          "required": true,
-          "description": "Sync configuration describing files and replacement patterns."
-        },
-        {
-          "name": "ignorePatterns",
-          "type": "unknown",
-          "required": true,
-          "description": "Glob patterns to exclude while scanning."
-        },
-        {
-          "name": "cwd",
-          "type": "unknown",
-          "required": true,
-          "description": "Project directory used to resolve file globs."
-        }
-      ],
-      "outputs": {
-        "text": "A list of detected version mismatches."
-      }
-    },
-    {
-      "id": "op-generateHookScript",
-      "name": "generateHookScript",
-      "what": "Generates the shell script content for a Git hook.",
-      "inputs": [
-        {
-          "name": "hookName",
-          "type": "unknown",
-          "required": true,
-          "description": "Name of the Git hook to generate."
-        }
-      ],
-      "outputs": {
-        "text": "Executable shell script contents for the hook."
-      }
-    },
-    {
-      "id": "op-checkHooksPathOverride",
-      "name": "checkHooksPathOverride",
-      "what": "Checks whether git hooks have been redirected away from the repository.",
-      "inputs": [
-        {
-          "name": "cwd",
-          "type": "unknown",
-          "required": true,
-          "description": "Repository directory to inspect."
-        }
-      ],
-      "outputs": {
-        "text": "A guard warning when a hooksPath override is detected."
-      }
-    },
-    {
-      "id": "op-checkHuskyBypass",
-      "name": "checkHuskyBypass",
-      "what": "Checks whether the HUSKY environment variable is disabling hooks.",
-      "inputs": [],
-      "outputs": {
-        "text": "A guard warning when the HUSKY bypass is detected."
-      }
-    },
-    {
-      "id": "op-checkHookIntegrity",
-      "name": "checkHookIntegrity",
-      "what": "Verifies that installed hook scripts match the expected content.",
-      "inputs": [
-        {
-          "name": "config",
-          "type": "unknown",
-          "required": true,
-          "description": "VersionGuard configuration that defines which hooks should exist."
-        },
-        {
-          "name": "cwd",
-          "type": "unknown",
-          "required": true,
-          "description": "Repository directory to inspect."
-        }
-      ],
-      "outputs": {
-        "text": "Guard warnings for each hook that has been tampered with."
-      }
-    },
-    {
-      "id": "op-checkEnforceHooksPolicy",
-      "name": "checkEnforceHooksPolicy",
-      "what": "Checks whether hooks are configured as required but not enforced.",
-      "inputs": [
-        {
-          "name": "config",
-          "type": "unknown",
-          "required": true,
-          "description": "VersionGuard configuration to inspect."
-        }
-      ],
-      "outputs": {
-        "text": "A guard warning when hooks are enabled but not enforced."
-      }
-    },
-    {
-      "id": "op-runGuardChecks",
-      "name": "runGuardChecks",
-      "what": "Runs all guard checks and returns a consolidated report.",
-      "inputs": [
-        {
-          "name": "config",
-          "type": "unknown",
-          "required": true,
-          "description": "VersionGuard configuration."
-        },
-        {
-          "name": "cwd",
-          "type": "unknown",
-          "required": true,
-          "description": "Repository directory to inspect."
-        }
-      ],
-      "outputs": {
-        "text": "A guard report with all findings."
-      }
-    },
-    {
-      "id": "op-initConfig",
-      "name": "initConfig",
-      "what": "Initializes a new VersionGuard config file in a project.",
-      "inputs": [
-        {
-          "name": "cwd",
-          "type": "unknown",
-          "required": true,
-          "description": "Project directory where the config should be created."
-        }
-      ],
-      "outputs": {
-        "text": "The path to the created config file."
-      }
-    },
-    {
-      "id": "op-createTag",
-      "name": "createTag",
-      "what": "Creates a release tag and optionally fixes version state first.",
-      "inputs": [
-        {
-          "name": "version",
-          "type": "unknown",
-          "required": true,
-          "description": "Version to embed in the new tag name."
-        },
-        {
-          "name": "message",
-          "type": "unknown",
-          "required": true,
-          "description": "Custom annotated tag message."
-        },
-        {
-          "name": "autoFix",
-          "type": "unknown",
-          "required": true,
-          "description": "Whether to auto-fix version mismatches before tagging."
-        },
-        {
-          "name": "config",
-          "type": "unknown",
-          "required": true,
-          "description": "Loaded VersionGuard configuration used for validation and fixes."
-        },
-        {
-          "name": "cwd",
-          "type": "unknown",
-          "required": true,
-          "description": "Repository directory where git commands should run."
-        }
-      ],
-      "outputs": {
-        "text": "The tagging outcome and any actions performed along the way."
-      }
-    },
-    {
-      "id": "op-validateTagForPush",
-      "name": "validateTagForPush",
-      "what": "Validates that a local tag is safe to push to the default remote.",
-      "inputs": [
-        {
-          "name": "tagName",
-          "type": "unknown",
-          "required": true,
-          "description": "Name of the tag to validate."
-        },
-        {
-          "name": "cwd",
-          "type": "unknown",
-          "required": true,
-          "description": "Repository directory where git commands should run."
-        }
-      ],
-      "outputs": {
-        "text": "A validation result with an optional suggested fix command."
-      }
-    },
-    {
-      "id": "op-validateVersion",
-      "name": "validateVersion",
-      "what": "Validates a version string against the active versioning strategy.",
-      "inputs": [
-        {
-          "name": "version",
-          "type": "unknown",
-          "required": true,
-          "description": "Version string to validate."
-        },
-        {
-          "name": "config",
-          "type": "unknown",
-          "required": true,
-          "description": "VersionGuard configuration that selects the validation rules."
-        }
-      ],
-      "outputs": {
-        "text": "The validation result for the provided version."
-      }
-    },
-    {
-      "id": "op-runWizard",
-      "name": "runWizard",
-      "what": "Runs the interactive setup wizard.",
-      "inputs": [
-        {
-          "name": "cwd",
-          "type": "unknown",
-          "required": true,
-          "description": "Project directory to initialize."
-        }
-      ],
-      "outputs": {
-        "text": "The path to the created config file, or \`null\` if cancelled."
-      }
-    },
-    {
-      "id": "op-runHeadless",
-      "name": "runHeadless",
-      "what": "Initializes VersionGuard non-interactively using CLI flags.",
-      "inputs": [
-        {
-          "name": "options",
-          "type": "unknown",
-          "required": true,
-          "description": "Headless initialization options."
-        }
-      ],
-      "outputs": {
-        "text": "The path to the created config file."
-      }
-    },
-    {
-      "id": "op-createProgram",
-      "name": "createProgram",
-      "what": "Creates the VersionGuard CLI program definition.",
-      "inputs": [],
-      "outputs": {
-        "text": "A configured Commander program for the VersionGuard CLI."
-      }
-    },
-    {
-      "id": "op-runCli",
-      "name": "runCli",
-      "what": "Parses CLI arguments and executes the matching command.",
-      "inputs": [
-        {
-          "name": "argv",
-          "type": "unknown",
-          "required": true,
-          "description": "Full argument vector to parse."
-        }
-      ]
-    },
-    {
-      "id": "op-createTempProject",
-      "name": "createTempProject",
-      "what": "Creates a temporary project directory with a minimal \`package.json\` fixture.",
-      "inputs": [],
-      "outputs": {
-        "text": "The absolute path to the temporary project directory."
-      }
-    },
-    {
-      "id": "op-initGitRepo",
-      "name": "initGitRepo",
-      "what": "Initializes a git repository in a fixture directory with a first commit.",
-      "inputs": [
-        {
-          "name": "cwd",
-          "type": "unknown",
-          "required": true,
-          "description": "Absolute path to the fixture repository."
-        }
-      ]
-    },
-    {
-      "id": "op-createBareRemote",
-      "name": "createBareRemote",
-      "what": "Creates a bare git repository to use as a remote in integration tests.",
-      "inputs": [],
-      "outputs": {
-        "text": "The absolute path to the new bare repository."
-      }
-    }
-  ],
-  "constraints": [],
-  "workflows": [],
-  "configSchema": [
-    {
-      "key": "ManifestConfig.source",
-      "type": "ManifestSourceType",
-      "description": "Manifest file to read the version from.  Use \`'auto'\` for file-existence detection or a specific filename.",
-      "default": "'auto'"
-    },
-    {
-      "key": "ManifestConfig.path",
-      "type": "string | undefined",
-      "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.",
-      "default": "undefined (uses the provider's built-in default)"
-    },
-    {
-      "key": "ManifestConfig.regex",
-      "type": "string | undefined",
-      "description": "Regex pattern to extract the version from source-code manifests.  Capture group 1 must contain the version string.",
-      "default": "undefined"
-    },
-    {
-      "key": "CalVerConfig.format",
-      "type": "CalVerFormat",
-      "description": "Calendar format used when parsing and validating versions."
-    },
-    {
-      "key": "CalVerConfig.preventFutureDates",
-      "type": "boolean",
-      "description": "Rejects versions that point to a future date.",
-      "default": "true"
-    },
-    {
-      "key": "CalVerConfig.strictMutualExclusion",
-      "type": "boolean | undefined",
-      "description": "Enforces that week tokens (WW/0W) cannot be mixed with month/day tokens.",
-      "default": "true"
-    },
-    {
-      "key": "SyncConfig.files",
-      "type": "string[]",
-      "description": "File globs or paths that should be scanned for version updates."
-    },
-    {
-      "key": "SyncConfig.patterns",
-      "type": "SyncPattern[]",
-      "description": "Replacement patterns applied to matching files."
-    },
-    {
-      "key": "ChangelogConfig.enabled",
-      "type": "boolean",
-      "description": "Enables changelog validation.",
-      "default": "false"
-    },
-    {
-      "key": "ChangelogConfig.file",
-      "type": "string",
-      "description": "Path to the changelog file to inspect."
-    },
-    {
-      "key": "ChangelogConfig.strict",
-      "type": "boolean",
-      "description": "Treats changelog problems as hard failures.",
-      "default": "false"
-    },
-    {
-      "key": "ChangelogConfig.requireEntry",
-      "type": "boolean",
-      "description": "Requires an entry for the current version.",
-      "default": "false"
-    },
-    {
-      "key": "GitHooksConfig.'pre-commit'",
-      "type": "boolean",
-      "description": "Enables validation during the \`pre-commit\` hook.",
-      "default": "false"
-    },
-    {
-      "key": "GitHooksConfig.'pre-push'",
-      "type": "boolean",
-      "description": "Enables validation during the \`pre-push\` hook.",
-      "default": "false"
-    },
-    {
-      "key": "GitHooksConfig.'post-tag'",
-      "type": "boolean",
-      "description": "Enables follow-up tasks after a tag is created.",
-      "default": "false"
-    },
-    {
-      "key": "GitConfig.hooks",
-      "type": "GitHooksConfig",
-      "description": "Hook toggles used by the CLI and validation workflow."
-    },
-    {
-      "key": "GitConfig.enforceHooks",
-      "type": "boolean",
-      "description": "Fails validation when required hooks are missing.",
-      "default": "false"
-    },
-    {
-      "key": "VersioningConfig.type",
-      "type": "VersioningType",
-      "description": "Versioning strategy used for the project."
-    },
-    {
-      "key": "VersioningConfig.schemeRules",
-      "type": "SchemeRules | undefined",
-      "description": "Scheme-level validation rules applied regardless of versioning type.",
-      "default": "\`{ maxNumericSegments: 3, allowedModifiers: ['dev', 'alpha', 'beta', 'rc'] }\`"
-    },
-    {
-      "key": "VersioningConfig.calver",
-      "type": "CalVerConfig | undefined",
-      "description": "CalVer-specific settings when \`type\` is \`'calver'\`.",
-      "default": "undefined"
-    },
-    {
-      "key": "VersionGuardConfig.versioning",
-      "type": "VersioningConfig",
-      "description": "Active versioning settings."
-    },
-    {
-      "key": "VersionGuardConfig.manifest",
-      "type": "ManifestConfig",
-      "description": "Version source manifest settings.",
-      "default": "\`{ source: 'auto' }\`"
-    },
-    {
-      "key": "VersionGuardConfig.sync",
-      "type": "SyncConfig",
-      "description": "Synchronization settings for mirrored version strings."
-    },
-    {
-      "key": "VersionGuardConfig.changelog",
-      "type": "ChangelogConfig",
-      "description": "Changelog validation settings."
-    },
-    {
-      "key": "VersionGuardConfig.git",
-      "type": "GitConfig",
-      "description": "Git enforcement settings."
-    },
-    {
-      "key": "VersionGuardConfig.ignore",
-      "type": "string[]",
-      "description": "Files or patterns excluded from validation."
-    },
-    {
-      "key": "InitOptions.cwd",
-      "type": "string",
-      "description": "Working directory path."
-    },
-    {
-      "key": "InitOptions.type",
-      "type": "\\"semver\\" | \\"calver\\" | undefined",
-      "description": "Versioning type (semver or calver)."
-    },
-    {
-      "key": "InitOptions.format",
-      "type": "string | undefined",
-      "description": "CalVer format string."
-    },
-    {
-      "key": "InitOptions.manifest",
-      "type": "string | undefined",
-      "description": "Manifest source type."
-    },
-    {
-      "key": "InitOptions.hooks",
-      "type": "boolean | undefined",
-      "description": "Whether to install git hooks."
-    },
-    {
-      "key": "InitOptions.changelog",
-      "type": "boolean | undefined",
-      "description": "Whether to enable changelog validation."
-    },
-    {
-      "key": "InitOptions.yes",
-      "type": "boolean | undefined",
-      "description": "Accept defaults without prompting."
-    },
-    {
-      "key": "InitOptions.force",
-      "type": "boolean | undefined",
-      "description": "Overwrite existing config."
-    }
-  ]
-}
-`;
-const llmsRaw = "# @codluv/versionguard\n> Strict versioning enforcement for SemVer and CalVer with git hooks, changelog validation, and file sync from package.json\n> Version: 0.4.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, 42 types\n\n- getCalVerConfig() — Extracts the CalVer config from a VersionGuard config, throwing if missing.\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- 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- 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- getTopicIndex() — Returns the topic index listing.\n- getTopicContent() — Returns help content for a specific topic.\n- getLlmContext() — Returns the full API context for LLM consumption.\n- getHelpJson() — Returns the topic index as a JSON structure for machine parsing.\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- 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- 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- 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- HelpTopic — Embedded help topics for the CLI help system.\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";
+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:07:33.077Z",\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-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": "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": "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.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.6.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\n89 functions, 53 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- 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- 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";
 async function runWizard(cwd) {
   p.intro("VersionGuard Setup");
   const existingConfig = findExistingConfig(cwd);
@@ -1041,6 +32,9 @@ async function runWizard(cwd) {
     return null;
   }
   let format;
+  let allowVPrefix = false;
+  let allowBuildMetadata = true;
+  let requirePrerelease = false;
   if (type === "calver") {
     const selected = await selectCalVerFormat();
     if (!selected) {
@@ -1048,6 +42,15 @@ async function runWizard(cwd) {
       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) {
@@ -1073,13 +76,16 @@ async function runWizard(cwd) {
   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 `versionguard validate` to verify your setup.");
+  p.outro("Run `vg validate` to verify your setup.");
   return configPath;
 }
 function runHeadless(options) {
@@ -1092,6 +98,9 @@ function runHeadless(options) {
   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
@@ -1131,6 +140,32 @@ async function selectCalVerFormat() {
   }
   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 };
+}
 async function selectManifest(cwd) {
   const detected = [];
   const checks = [
@@ -1162,17 +197,19 @@ async function selectManifest(cwd) {
   return result;
 }
 function buildConfig(input) {
-  const config = {
-    versioning: {
-      type: input.type,
-      ...input.type === "calver" && input.format ? {
-        calver: {
-          format: input.format,
-          preventFutureDates: true
-        }
-      } : {}
+  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 };
   }
@@ -1251,17 +288,20 @@ function requireProject(cwd, command) {
 }
 function createProgram() {
   const program = new Command();
-  program.name("versionguard").description("Strict versioning enforcement for SemVer and CalVer").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("--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(
+  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;
+        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,
@@ -1612,12 +652,12 @@ function createProgram() {
       if (!content) {
         console.error(styles.error(`Unknown topic: ${topic}`));
         console.log("");
-        console.log(ckmEngine.getTopicIndex("versionguard"));
+        console.log(ckmEngine.getTopicIndex("vg"));
         process.exit(1);
       }
       console.log(content);
     } else {
-      console.log(ckmEngine.getTopicIndex("versionguard"));
+      console.log(ckmEngine.getTopicIndex("vg"));
     }
   });
   const hooksCommand = program.command("hooks").description("Manage git hooks");