@gspothq/cli 0.1.1 → 0.2.0

package/configurations/framework/vue/rules/VUE.md

@@ -1,6 +1,6 @@
 # Vue
 
-These rules cover Vue 3 single-file components, reactivity, props and events, templates, and stores.
+Read this rule when you change Vue components, composables, or stores.
 
 ## Components
 
@@ -18,23 +18,23 @@ These rules cover Vue 3 single-file components, reactivity, props and events, te
 
 <!-- level: all -->
 
-Name an event for what happened, in the past tense or as a noun: `saved`, `update:modelValue`.
+Name an event for what happened, in the past tense or as a noun, such as `saved` or `update:modelValue`.
 
 ## Reactivity
 
 - Use `ref` for a value and `reactive` for an object that keeps the same identity. Do not destructure a reactive object.
 - Derive with `computed`.
-- Use `watch` for an effect outside Vue: a request, a timer, storage. Do not use it to derive state.
-- Clean up in `onUnmounted`, or in the cleanup callback of the watcher, whatever a component started.
+- Use `watch` for an effect outside Vue: a request, a timer, or storage. Do not use it to derive state.
+- Stop whatever a component started in `onUnmounted` or in the cleanup callback of the watcher.
 
 ## State and data
 
 <!-- level: all -->
 
-- Local state stays in the component. Shared state goes in a store, one store for each domain.
+- Local state stays in the component. Shared state goes in a store, one per domain.
 - A store exposes actions that say what happened. Components do not assign to store state.
 - Fetch data in a composable or a store action, never inline in a template event.
-- Name a composable `use` and its subject, such as `useCart`, and returns reactive values when callers need reactivity.
+- Name a composable `use` and its subject, such as `useCart`. Return reactive values when callers need reactivity.
 
 ## Tests
 

package/configurations/general/commits/manifest.toml

@@ -1,111 +1,47 @@
 [configuration]
-title = "Commits"
 always_selected = true
-when = { git = true }
 description = "Checks commit messages for a conventional type, an optional project scope, a first line of 72 characters or fewer, and a wrapped body."
+title = "Commits"
+when = { git = true }
 
 [files]
 paths = ["**"]
 
 [[tool]]
+mise = "npm:@commitlint/cli"
 name = "commitlint"
-version = "21.2.2"
 npm = "@commitlint/cli"
-mise = "npm:@commitlint/cli"
-[[tool.replace]]
-file = ".commitlintrc"
-shared = false
-
-[[tool.replace]]
-file = ".commitlintrc.json"
-shared = false
-
-[[tool.replace]]
-file = ".commitlintrc.yml"
-shared = false
-
-[[tool.replace]]
-file = ".commitlintrc.yaml"
-shared = false
-
-[[tool.replace]]
-file = ".commitlintrc.js"
-shared = false
-
-[[tool.replace]]
-file = ".commitlintrc.cjs"
-shared = false
-
-[[tool.replace]]
-file = ".commitlintrc.mjs"
-shared = false
-
-[[tool.replace]]
-file = ".commitlintrc.ts"
-shared = false
-
-[[tool.replace]]
-file = ".commitlintrc.cts"
-shared = false
-
-[[tool.replace]]
-file = ".commitlintrc.mts"
-shared = false
-
-[[tool.replace]]
-file = "commitlint.config.js"
-shared = false
-
-[[tool.replace]]
-file = "commitlint.config.cjs"
-shared = false
-
-[[tool.replace]]
-file = "commitlint.config.mjs"
-shared = false
-
-[[tool.replace]]
-file = "commitlint.config.ts"
-shared = false
-
-[[tool.replace]]
-file = "commitlint.config.cts"
-shared = false
-
-[[tool.replace]]
-file = "commitlint.config.mts"
-shared = false
+replace = [".commitlintrc", ".commitlintrc.json", ".commitlintrc.yml", ".commitlintrc.yaml", ".commitlintrc.js", ".commitlintrc.cjs", ".commitlintrc.mjs", ".commitlintrc.ts", ".commitlintrc.cts", ".commitlintrc.mts", "commitlint.config.js", "commitlint.config.cjs", "commitlint.config.mjs", "commitlint.config.ts", "commitlint.config.cts", "commitlint.config.mts"]
+version = "21.2.2"
 
-[[tool.replace]]
+[[tool.replace_key]]
 file = "package.json"
 key = "commitlint"
 redirect = true
-shared = true
 
 [[tool_file]]
 target = ".gspot/config/commitlint.config.cjs"
 tool = "commitlint"
-rule_keys = ["rules"]
 
 [[check]]
-name = "commitlint"
-example = "The proposed message `changed stuff` lacks the configured conventional-commit structure. A message such as `fix(cli): report missing configuration` supplies a type, scope, and subject. Use a type and scope accepted by the repository policy."
-level = "all"
-stage = "message"
 command = ["commitlint", "--config", "{tool_file:commitlint}", "--edit", "{message_file}"]
+example = "The message `changed stuff` has no type or scope. Write `fix(cli): report missing configuration` instead."
+help = "Write `<type>`: `<subject>` or `<type>`(`<scope>`): `<subject>` in a first line of 72 characters or fewer. Change the accepted types with `gspot set tools.commitlint.types`."
+level = "all"
+name = "commitlint"
 output = { format = "regex", pattern = "^\\s*[✖⚠]\\s+(?<message>.*?)\\s+\\[(?<rule>[a-z-]+)\\]\\s*$" }
-summary = "Checks the commit message being written: a conventional type, an optional known scope, a first line of 72 characters or fewer, and a wrapped body."
-why = "A history of typed, scoped subjects is what release notes, blame and bisect are read from; a free-form message hides the change."
-help = "Write `<type>`: `<subject>` or `<type>`(`<scope>`): `<subject>`, with an accepted type and optional scope. Keep the whole first line at 72 characters or fewer. Change accepted types with gspot set tools.commitlint.types."
+stage = "message"
+summary = "Checks a new commit message for a conventional type, an optional known scope, a first line of 72 characters or fewer, and a wrapped body."
+why = "Release notes, blame, and bisect depend on typed, scoped subjects, and a free-form message hides the change."
 
 [[check]]
-name = "commitlint-pushed"
-example = "A new commit with message `changed stuff` causes the checked range to fail its message rules. Reword that commit to an accepted message such as `fix(cli): report missing configuration`. Rewriting commits changes their IDs; coordinate before rewriting shared history."
+example = "A commit with the message `changed stuff` in the push fails. Reword it as `fix(cli): report missing configuration`, and coordinate first when others share that history."
+help = "Reword the commits that fail with `git rebase -i`, or change the rule with `gspot set tools.commitlint.rules`."
 level = "all"
-stage = "push"
+name = "commitlint-pushed"
+output = { format = "regex", pattern = "^\\s*[✖⚠]\\s+(?<message>.*?)\\s+\\[(?<rule>[a-z-]+)\\]\\s*$" }
 runs = "history"
+stage = "push"
+summary = "Checks the message of each commit in a push. A manual run covers every commit from the upstream merge base to HEAD."
 tool = "commitlint"
-output = { format = "regex", pattern = "^\\s*[✖⚠]\\s+(?<message>.*?)\\s+\\[(?<rule>[a-z-]+)\\]\\s*$" }
-summary = "Checks the message of every commit the push sends. Run by hand, it checks every commit from the upstream merge base to HEAD."
-why = "A message written past the hook (--no-verify, a rebase, a merge) still reaches the shared branch unless the push checks it."
-help = "Reword the commits that fail with git rebase -i, or change the rule with gspot set tools.commitlint.rules."
+why = "A message written past the hook (--no-verify, a rebase, or a merge) still reaches the shared branch unless the push checks it."

package/configurations/general/commits/rules/GIT.md

@@ -1,31 +1,42 @@
 # Git
 
+Read this rule before you commit, push, tag, or open a pull request.
+
 ## Working with uncommitted changes
 
-Changes you did not make may belong to another agent or contributor working in parallel. Do not
-revert, stash, clean, or overwrite them. Keep working beside them, and ask the user only when your
-change overwrites or contradicts one.
+Changes you did not make may belong to another agent or contributor working in parallel. Do not revert, stash,
+clean, or overwrite them. Keep working beside them, and ask the user only when your change overwrites or contradicts
+one.
 
 ## Commits
 
 - Commit only when the user asks.
 - One change per commit. Put a rename and a behavior change in two commits.
 - The body says what changed and why.
-- Footers reference issues with `Refs: #123` or `Closes: #123`, and breaking changes with `BREAKING CHANGE: ...`.
+- Footers reference issues with `Refs: #123` or `Closes: #123`, and breaking changes with `BREAKING CHANGE:...`.
 - Never bypass hooks with `--no-verify`.
+- Never add `[skip ci]`, `[ci skip]`, `[no ci]`, or another marker that stops CI.
+- Never force-push the default branch or a protected branch.
+
+## Branches and pull requests
 
-## Branches
+When the repository uses branches and pull requests, follow these steps. Skip them when changes go straight to
+the default branch.
 
 - Name branches `<type>/<kebab-summary>`, such as `feat/order-export` or `fix/session-expiry`.
-- Never force-push a protected branch. Force-push your own branch only after a rebase you performed.
-- Rebase onto the default branch before opening a pull request; do not merge the default branch into a feature branch.
+- Force-push your own branch only after a rebase you performed.
+- Rebase onto the default branch before you open a pull request. Do not merge it into a feature branch.
+- Use the commit subject as the title for a single-commit branch. Otherwise, write one sentence for the whole
+  change.
+- The description states what changed, why, and which checks verified it. It links the issue.
+- A pull request does one thing. Put unrelated fixes in a separate branch.
 
-## Files to keep out of commits
+## Releases
 
-- Editor state such as `.vscode/`, `.idea/`, or `xcuserdata/`, except settings the team commits on purpose.
+- Publish a package only through the release task or workflow, from a commit that CI tested.
+- Tag every published version. The tag names the commit you published.
+- After you publish a version, change its code only under a new version number.
 
-## Pull requests
+## Files to keep out of commits
 
-- Use the commit subject as the title when the branch has one commit. Otherwise, write a sentence for the whole change.
-- The description states what changed, why, and which checks verified it. It links the issue.
-- A pull request does one thing. Unrelated fixes found on the way go in a separate branch.
+- Editor state such as `.vscode/`, `.idea/`, or `xcuserdata/`, except settings the team commits on purpose.

package/configurations/general/coverage/manifest.toml

@@ -1,3 +1,3 @@
 [configuration]
-title = "Coverage"
 description = "Coverage floors shared by test runners."
+title = "Coverage"

package/configurations/general/dependencies/manifest.toml

@@ -1,159 +1,99 @@
-prefix_collisions = { prefixes = ["package", "pnpm"] }
-
 [configuration]
-title = "Dependencies"
 always_selected = true
-description = "Dependency health: known advisories, one version for each dependency, exact pins, one package manager, and a lockfile that matches its manifest."
+description = "Checks for known advisories, one version per package, exact pins, one package manager, and a lockfile that matches its dependency file."
+title = "Dependencies"
 
 [files]
 filenames = ["package.json", "bun.lock", "bun.lockb", "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bunfig.toml", ".npmrc", "pnpm-workspace.yaml", "pyproject.toml", "uv.lock", "requirements*.txt", "Package.swift", "Package.resolved", "Cargo.toml", "Cargo.lock", "go.mod", "go.sum", "Gemfile.lock"]
 kinds = ["source", "generated"]
 
+[shared_prefixes]
+prefixes = ["package", "pnpm"]
+
 [[tool]]
-name = "osv-scanner"
-version = "2.6.0"
-min_version = "2.0.0"
-mise = "osv-scanner"
 brew = "osv-scanner"
 github = { name = "google/osv-scanner", version = "v2.6.0" }
-winget = "Google.OSVScanner"
+min_version = "2.0.0"
+mise = "osv-scanner"
+name = "osv-scanner"
+replace = ["osv-scanner.toml"]
 scoop = "osv-scanner"
-[[tool.replace]]
-file = "osv-scanner.toml"
-shared = false
+version = "2.6.0"
+winget = "Google.OSVScanner"
 
 [[tool]]
+mise = "npm:syncpack"
 name = "syncpack"
-version = "15.3.3"
 npm = "syncpack"
-mise = "npm:syncpack"
-[[tool.replace]]
-file = ".syncpackrc"
-shared = false
-
-[[tool.replace]]
-file = ".syncpackrc.json"
-shared = false
-
-[[tool.replace]]
-file = ".syncpackrc.yaml"
-shared = false
-
-[[tool.replace]]
-file = ".syncpackrc.yml"
-shared = false
-
-[[tool.replace]]
-file = ".syncpackrc.ts"
-shared = false
-
-[[tool.replace]]
-file = ".syncpackrc.mjs"
-shared = false
-
-[[tool.replace]]
-file = ".syncpackrc.js"
-shared = false
-
-[[tool.replace]]
-file = ".syncpackrc.cjs"
-shared = false
-
-[[tool.replace]]
-file = "syncpack.config.js"
-shared = false
-
-[[tool.replace]]
-file = "syncpack.config.cjs"
-shared = false
-
-[[tool.replace]]
-file = "syncpack.config.mjs"
-shared = false
-
-[[tool.replace]]
-file = "syncpack.config.ts"
-shared = false
+replace = [".syncpackrc", ".syncpackrc.json", ".syncpackrc.yaml", ".syncpackrc.yml", ".syncpackrc.ts", ".syncpackrc.mjs", ".syncpackrc.js", ".syncpackrc.cjs", "syncpack.config.js", "syncpack.config.cjs", "syncpack.config.mjs", "syncpack.config.ts"]
+version = "15.3.3"
 
 [[tool_file]]
 target = ".gspot/config/osv-scanner.toml"
 tool = "osv-scanner"
 
 [[tool_file]]
-source = "syncpack.json"
 target = ".gspot/config/syncpack.json"
 tool = "syncpack"
 
 [[check]]
-name = "osv"
-example = "A locked dependency version affected by a published OSV advisory reports the package and advisory. Upgrade to a reviewed fixed version and update the lockfile, then rescan."
+example = "A locked package version named in an OSV advisory reports a finding. Upgrade to a fixed version, and update the lockfile."
+files = { filenames = ["bun.lock", "package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "go.mod", "Cargo.lock", "Gemfile.lock", "gems.locked", "requirements.txt", "Pipfile.lock", "poetry.lock", "pdm.lock", "pylock.toml", "uv.lock", "pom.xml", "gradle.lockfile", "buildscript-gradle.lockfile", "conan.lock", "pubspec.lock", "mix.lock", "cabal.project.freeze", "stack.yaml.lock", "composer.lock", "renv.lock", "packages.config", "packages.lock.json", "*.deps.json"], paths = ["**/gradle/verification-metadata.xml", "gradle/verification-metadata.xml"], kinds = ["source", "generated"] }
 level = "recommended"
-stage = "push"
-runs = "once"
+name = "osv-scanner"
 needs = ["network"]
-files = { filenames = ["bun.lock", "package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "go.mod", "Cargo.lock", "Gemfile.lock", "gems.locked", "requirements.txt", "Pipfile.lock", "poetry.lock", "pdm.lock", "pylock.toml", "uv.lock", "pom.xml", "gradle.lockfile", "buildscript-gradle.lockfile", "conan.lock", "pubspec.lock", "mix.lock", "cabal.project.freeze", "stack.yaml.lock", "composer.lock", "renv.lock", "packages.config", "packages.lock.json", "*.deps.json"], paths = ["**/gradle/verification-metadata.xml", "gradle/verification-metadata.xml"], kinds = ["source", "generated"] }
+runs = "once"
+stage = "push"
 # The tool project lockfiles under .gspot stay out: a repository cannot upgrade a package that a gspot tool pins.
 command = ["osv-scanner", "scan", "source", "--config", "{tool_file:osv-scanner}", "--format", "json", "--allow-no-lockfiles", "--recursive", "--experimental-exclude", ".gspot", "{root}"]
+help = "Upgrade the package the finding names. When no fix exists, accept the advisory until a recheck date with `gspot ignore dependencies/osv-scanner --rule <advisory-id> --reason \"<why>\" --until <YYYY-MM-DD>`."
 output = { format = "json", items = "results", children = "packages.vulnerabilities", fields = { file = "source.path", rule = "id", message = "package.name package.version summary" } }
 summary = "Looks up every locked dependency in the Open Source Vulnerabilities (OSV) advisory database."
 why = "An advisory identifies a vulnerability in a dependency version."
-help = "Upgrade the package the finding names. When no fix exists, accept the advisory with `gspot ignore dependencies/osv --rule <advisory-id> --reason \"<why>\" --until <YYYY-MM-DD>`. Recheck it before that date."
 
 [[check]]
-name = "syncpack"
-example = "Two workspace manifests declaring different versions of a dependency governed by the same version group report a mismatch. Align both declarations to the reviewed version and update the lockfile."
-level = "all"
-stage = "push"
-runs = "once"
 command = ["syncpack", "lint", "--config", "{tool_file:syncpack}"]
-tool = "syncpack"
+example = "Two package.json files that pin different versions of one dependency report a mismatch. Set both to the same version, and update the lockfile."
 files = { filenames = ["package.json"] }
+help = "Run `syncpack fix --config .gspot/config/syncpack.json`, or align the versions by hand."
+level = "all"
+name = "syncpack"
 output = { format = "lines" }
+runs = "once"
+stage = "push"
 summary = "Checks that every workspace package resolves each dependency to one version."
-why = "Two versions of one dependency in a workspace mean two behaviors, and a bug that appears in one package only."
-help = "Run syncpack fix --config .gspot/config/syncpack.json, or align the versions by hand."
+tool = "syncpack"
+why = "Two versions of a dependency in one workspace behave differently, so a bug shows in only one package."
 
 [[check]]
-name = "package-json"
-example = "A repository with both `bun.lock` and `package-lock.json` reports a second lockfile. Delete the lockfile of the package manager the repository does not use."
-level = "all"
-stage = "commit"
-runs = "once"
+example = "npm 10.9.2 in packageManager reports a finding, because it ignores min-release-age. Declare npm 11.17.0 or newer."
 files = { filenames = ["package.json"] }
-summary = "Checks every package.json: the root names a packageManager, every package names the same one, a workspace root is private, and only one kind of lockfile exists."
-why = "Two package managers install two different trees."
-help = "Name one packageManager in the root package.json, use it in every package, mark a workspace root private, and delete the other lockfile."
-
-[[check]]
-name = "stale-lockfile"
-example = "Adding a dependency to a package manifest without updating its lockfile reports an outdated lockfile. Run the owning package manager installation, inspect its manifest and lockfile changes, and retain both together."
+help = "Upgrade the package manager that the root package.json names to the version the finding gives."
 level = "recommended"
-stage = "push"
+name = "release-age"
 runs = "once"
-needs = ["network"]
-files = { filenames = ["package.json", "bun.lock", "package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "pyproject.toml", "uv.lock"] }
-summary = "Runs each package manager's frozen install in a temporary copy."
-why = "A lockfile that lags its manifest installs versions nobody reviewed the moment someone runs a plain install."
-help = "Run the install of the package manager once and commit the lockfile it writes."
+stage = "commit"
+summary = "Checks that the package manager in the root package.json holds back releases newer than dependencies.min_release_age_days."
+why = "gspot writes a release hold for each package manager. An older version ignores it and installs a new release the day it appears."
 
 [[check]]
-name = "bun-release-age"
-example = "A Bun project without the required `[install] minimumReleaseAge` reports a missing installation safeguard. Set it to the seconds named in the finding and configure the required scanner under `[install.security]`."
+example = "A root package.json without packageManager reports a finding. Declare the package manager and its exact version."
+files = { filenames = ["package.json"] }
+help = "Name one packageManager in the root package.json."
 level = "all"
+name = "package-json"
+runs = "once"
 stage = "commit"
-runs = "scope"
-files = { filenames = ["bunfig.toml", "bun.lock", "bun.lockb"], kinds = ["source", "generated"] }
-summary = "Checks each Bun project's bunfig.toml for the required minimum release age and security scanner."
-why = "Most malicious releases are pulled within days, so a package nobody installs in its first week rarely harms anybody."
-help = "Set [install] minimumReleaseAge in bunfig.toml to the seconds the message names, and the scanner under [install.security]."
+summary = "Checks that the root package.json names a packageManager."
+why = "A declared package manager keeps installs and the lockfile format consistent."
 
 [[check]]
-name = "lockfile-hosts"
-example = "A locked package URL pointing to a host outside `dependencies.allowed_registries` reports that host. Resolve the package again from the approved registry, or review and explicitly allow the required host."
+example = "A lockfile URL outside `dependencies.allowed_registries` reports its host. Install the package again from an allowed registry, or add that host to the list."
+files = { filenames = ["package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"], kinds = ["source", "generated"] }
+help = "Install the package from the registry again, or add the host to dependencies.allowed_registries."
 level = "recommended"
-stage = "commit"
+name = "lockfiles"
 runs = "scope"
-files = { filenames = ["package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock"], kinds = ["source", "generated"] }
+stage = "commit"
 summary = "Checks that npm, pnpm, Yarn, and text Bun lockfile downloads in each project scope use HTTPS and allowed registry hosts."
-why = "A lockfile line that resolves from another host installs code nobody chose, and a review rarely reads lockfiles."
-help = "Install the package from the registry again, or add the host to dependencies.allowed_registries."
+why = "A lockfile line from another host installs code nobody chose, and reviewers rarely read those files."

package/configurations/general/dependencies/rules/DEPENDENCIES.md

@@ -1,30 +1,36 @@
 # Dependencies
 
+Read this rule before you add, upgrade, or remove a dependency.
+
 ## Adding one
 
-- Do not add a dependency for a one-line native API, a small local helper, or an array, object, or
+- Do not add a dependency for a one-line standard API, a small local helper, or an array, object, or
   string utility. Use the platform first, then what the repository already depends on.
 - A new dependency needs a reason in the commit: what it does that the platform and existing
   dependencies do not.
 - Prefer a package that does one thing, receives maintenance, publishes types, and has no install scripts.
 - Each project uses one package manager and commits its lockfile. CI and Docker builds install
-  from the lockfile without changing it such as `npm ci`, `uv sync --frozen`.
+  from the lockfile without changing it, such as `npm ci` or `uv sync --frozen`.
 
 ## Versions
 
 - Pin exact versions in an application. A published library keeps ranges for its dependencies and peers.
 - Pin the runtime version once for Node, Python, Bun, or the Swift toolchain. Every file that
   states it agrees.
-- If the package manager refuses a release as too new, pick an older one or ask the user.
-- Upgrade one dependency per commit with the reason. Never upgrade broadly to satisfy a scanner
+- If the package manager rejects a release as too new, pick an older one or ask the user.
+- Upgrade one dependency per commit with the reason. Never upgrade broadly to pass a scanner
   without reading what changed.
+- Write each tool version once. Other files read that pin, or a check compares them with it.
 
 ## Policy
 
+- Delete an override when it matches no package in the lockfile, or when every caller already accepts the fixed
+  version.
+- Keep third-party license notices in a tracked file, not in a string in code.
 - Ask the user before you add a dependency whose license falls outside the allowed list.
-- Record a known advisory that has no fix in `[[ignore]]`, with the check, advisory ID, reason,
-  and expiry. Never ignore advisories in bulk.
+- For a known advisory that has no fix, follow the suppression rules: ask the user, then run
+  `gspot ignore` with the advisory ID, a reason, and an expiry date. Never ignore advisories in bulk.
 - Declare vendored code and record its upstream version and license. Change it only by updating
   it from upstream.
-- Remove dependencies when no runtime, build, tooling, or public peer dependency needs them.
+- Remove a package when no runtime, build, tool, or public peer dependency needs it.
   Before you remove a package that a check calls unused, search configuration and scripts for it.

package/configurations/general/docs/manifest.toml

@@ -1,79 +1,64 @@
 [configuration]
-title = "Docs"
 always_selected = true
-description = "Documentation integrity: links and anchors, banned headings, stale paths, the README of every scope, and its shape."
+description = "Checks documentation for broken links and anchors, banned headings, stale paths, and a well-formed README in every scope."
+title = "Docs"
 
 [files]
 extensions = [".md", ".mdx"]
 filenames = ["CLAUDE.md", "AGENTS.md", "README.md"]
 
 [[tool]]
-name = "lychee"
-version = "0.24.2"
-mise = "lychee"
 brew = "lychee"
 cargo = "lychee"
 github = { name = "lycheeverse/lychee", version = "lychee-v0.24.2" }
-[[tool.replace]]
-file = "lychee.toml"
-shared = false
-
-[[tool.replace]]
-file = ".lycheeignore"
-shared = false
+mise = "lychee"
+name = "lychee"
+replace = ["lychee.toml", ".lycheeignore"]
+version = "0.24.2"
 
 [[tool_file]]
+per_scope = true
 target = ".gspot/config/lychee.toml"
 tool = "lychee"
-per_scope = true
 
 [[check]]
-name = "lychee"
-example = "The Markdown link `[Setup](missing.md)` reports a missing local target when `missing.md` does not exist. Point it at the actual setup guide or add the intended document."
-level = "recommended"
-stage = "commit"
 command = ["lychee", "--config", "{tool_file:lychee}", "--offline", "--include-fragments=full", "--format", "detailed", "--no-progress", "{files}"]
+example = "The link `[Setup](missing.md)` reports a broken target when no `missing.md` exists. Point it at the setup guide, or add that file."
+help = "Point the link at the file or heading that exists, or delete it."
+level = "recommended"
+name = "lychee"
 output = { format = "grouped", file_pattern = "^Errors in (?<file>.+)$", pattern = "^\\[(?<rule>[A-Z0-9]+)\\] (?<message>\\S+(?: \\(at (?<line>\\d+):(?<column>\\d+)\\))? \\| .*)$" }
+stage = "commit"
 summary = "Checks that local documentation links reach existing files and valid anchor or text fragments."
-why = "A dead link inside the repository is a promise the docs broke without anyone noticing."
-help = "Point the link at the file or heading that exists, or delete it."
+why = "A dead link inside the repository breaks silently, and readers hit it first."
 
 [[check]]
-name = "lychee-external"
-example = "A documentation link returning HTTP 404 reports a broken external destination. Replace it with a verified current URL or remove the obsolete link, then rerun with network access."
+command = ["lychee", "--config", "{tool_file:lychee}", "--root-dir", "{root}", "--scheme", "http", "--scheme", "https", "--include-fragments=full", "--format", "detailed", "--no-progress", "{files}"]
+example = "A link that returns HTTP 404 reports a broken destination. Replace the URL with a current one, or remove the link."
+help = "Update or remove the link, or exclude the URL pattern with a reason under docs.allowed_urls."
 level = "recommended"
-stage = "manual"
+name = "lychee-external"
 needs = ["network"]
-command = ["lychee", "--config", "{tool_file:lychee}", "--root-dir", "{root}", "--scheme", "http", "--scheme", "https", "--include-fragments=full", "--format", "detailed", "--no-progress", "{files}"]
 output = { format = "grouped", file_pattern = "^Errors in (?<file>.+)$", pattern = "^\\[(?<rule>[A-Z0-9]+)\\] (?<message>\\S+(?: \\(at (?<line>\\d+):(?<column>\\d+)\\))? \\| .*)$" }
+stage = "manual"
 summary = "Checks every external link over the network."
-why = "An external link rots on its own schedule; this run says which ones did."
-help = "Update or remove the link, or exclude the URL pattern with a reason under docs.allowed_urls."
+why = "External links break over time; this check reports which ones did."
 
 [[check]]
+example = "A path in the docs that points to a deleted file reports a stale reference. Update the path and any command that uses it."
+help = "Fix the path or the task name. Give an example code block a `title=` attribute."
+level = "recommended"
 name = "missing-paths"
-example = "A documented repository path that no longer exists reports a stale reference. Update the path and any associated command to the current owner, then verify the procedure from its stated working directory."
 runs = "once"
-level = "recommended"
 stage = "commit"
-summary = "Checks that documented paths name tracked files and mise, npm, pnpm, yarn, and bun run commands name tasks or scripts in their project."
-why = "A path in the docs that nothing tracks sends the reader to a file that is gone."
-help = "Fix the path or the task name. Give an example code block a title= attribute."
+summary = "Checks that documented paths point to tracked files, and that mise, npm, pnpm, yarn, and bun run commands name a task or script of their project."
+why = "A stale path in the docs sends the reader to a deleted file."
 
 [[check]]
-name = "required-files"
-example = "A configured scope without `README.md` reports the missing README. Add one that explains its purpose and setup. The repository root also needs a license when license presence is required."
-level = "all"
-stage = "commit"
-summary = "Checks that every scope has a README.md and the root has a LICENSE."
-why = "A scope with no README is a door with no sign."
+example = "A scope without `README.md` reports the missing file. Add one that explains what the scope does and how to start."
 help = "Write the README; the docs rule files say what goes in it."
-
-[[check]]
-name = "readme-shape"
-example = "A README with more H2 headings than limits.docs.headings_before_contents reports a missing Contents section. Add the section. A scope-root README also needs an opening paragraph and a section named install, setup, start, or requirements."
 level = "all"
+name = "required-files"
 stage = "commit"
-summary = "Checks the shape of every README: an opening paragraph, a Contents list when long, a section on getting started."
-why = "A README with the right shape answers what this is and how to start before the reader scrolls."
-help = "Add the missing section or paragraph. For an accepted exception, run gspot ignore docs/readme-shape --paths `<glob>` --reason \"`<why>`\"."
+summary = "Checks that every scope has a README.md and the root has a LICENSE."
+why = "A scope with no README leaves readers to guess what it does."