Update config, migrate to Kover

.agents/_TOC.md

@@ -21,3 +21,5 @@
 19. [Pre-PR checklist](skills/pre-pr/SKILL.md)
 20. [Kotlin code review](skills/kotlin-review/SKILL.md)
 21. [Dependency audit](skills/dependency-audit/SKILL.md)
+22. [Gradle review](skills/gradle-review/SKILL.md)
+23. [Raise test coverage](skills/raise-coverage/SKILL.md)

.agents/documentation-guidelines.md

@@ -6,6 +6,27 @@
 - When using TODO comments, follow the format on the [dedicated page][todo-comments].
 - File and directory names should be formatted as code.
 
+## API documentation scope
+
+KDoc and Javadoc describe the API as it appears to a consumer of the published
+artifact. Keep them focused on behaviour, parameters, return values, and usage
+examples.
+
+Do **not** reference repository-internal locations from API docs:
+
+- Build infrastructure paths such as `buildSrc/` or `config/` (the `config`
+  repository, `config/buildSrc/`, and similar).
+- Agent-facing material under `.agents/` — task plans, skill rules, review
+  notes, conventions, or any other file rooted there.
+- Branch names, commit SHAs, issue numbers, or other repo workflow artefacts.
+
+These details are invisible to a consumer who only sees the artifact's
+sources/Javadoc/KDoc and rot quickly as the repository evolves. If the rationale
+for an API decision lives in such a file, summarise the *outcome* in the
+KDoc instead of linking to the source. Cross-repository parity notes and
+work-in-progress justifications belong in the task plan under
+`.agents/tasks/`, not in the published API documentation.
+
 ## Protobuf file headers
 - In `.proto` files, a multi-paragraph documentation header must end with a
   trailing empty comment line (`//`).

.agents/skills/api-discovery/SKILL.md

@@ -2,17 +2,18 @@
 name: api-discovery
 description: >
   Resolve the on-disk location of a Maven artifact's source code,
-  so you can `Grep`/`Read` it directly instead of running `unzip`
-  against JARs in the Gradle cache. Use this whenever you need to
-  inspect a library's API or implementation — definitions of public
+  so you can inspect it directly instead of running `unzip` against JARs
+  in the Gradle cache. Use this whenever you need to inspect a library's
+  API or implementation — definitions of public
   types, method signatures, KDoc, internal helpers, etc.
 ---
 
 # API discovery
 
 Before reading library source code, run the `discover` script in
 `.agents/scripts/api-discovery/`. It returns a path you can hand
-straight to `Grep`, `Read`, or `Glob`.
+straight to normal search and file-reading tools such as `rg`, `sed`,
+or the active agent's file viewer.
 
 Do **not** run `find ~/.gradle/caches` or `unzip` against cache JARs.
 Each `unzip` decompresses the archive afresh — slow and token-heavy.
@@ -42,7 +43,7 @@ the user should know about.
 
 | Code | Meaning | What you do |
 |---|---|---|
-| `0` | Path on stdout is usable. | Pass it to `Grep`/`Read`/`Glob`. If stderr is non-empty, surface the warning to the user before relying on the path. |
+| `0` | Path on stdout is usable. | Search or read files under that path directly. If stderr is non-empty, surface the warning to the user before relying on the path. |
 | `1` | Unresolvable (no sibling AND no JAR). | Report the failure. **Do not** fall back to `unzip ~/.gradle/caches/...`. |
 | `10` | Cache directory not initialized. | Run the **bootstrap flow** below. |
 
@@ -86,7 +87,7 @@ paths entirely.
 ## Workflow
 
 1. **Always** call `discover` before reading library source.
-2. Use the returned path with `Grep`/`Read`/`Glob` directly. Do **not**
+2. Use the returned path with search or file-reading tools directly. Do **not**
    `cd` into the directory — that adds path-prefix noise to tool calls
    and makes line citations harder to read.
 3. If stderr contains `STALE: ...`, the sibling on disk does not match
@@ -197,11 +198,10 @@ $ echo $?
 0
 ```
 
-Tool calls then look like:
+Follow-up searches then look like:
 
-- `Glob` pattern `**/*.kt`, path
-  `/Users/<you>/Projects/Spine/base-libraries/base`.
-- `Grep` pattern `class Identifier`, path the same.
+- `rg --files /Users/<you>/Projects/Spine/base-libraries/base`.
+- `rg -n 'class Identifier' /Users/<you>/Projects/Spine/base-libraries/base`.
 
 **Spine artifact, stale sibling:**
 

.agents/skills/api-discovery/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "API Discovery"
+  short_description: "Resolve Maven artifact source paths"
+  default_prompt: "Use $api-discovery to resolve a Maven artifact's source path before inspecting library APIs or implementations."

.agents/skills/bump-gradle/SKILL.md

@@ -143,6 +143,6 @@ empty commits, and do not bundle unrelated changes into either commit.
 
    Before this branch can be built or published locally, the project
    version must be strictly greater than the version on the base ref.
-   Invoke `/version-bumped` — it is a no-op if a bump has already
-   happened earlier on the branch, and otherwise calls `/bump-version`
-   to perform the increment.
+   Run the `version-bumped` skill — it is a no-op if a bump has already
+   happened earlier on the branch, and otherwise uses the `bump-version`
+   skill to perform the increment.

.agents/skills/bump-version/SKILL.md

@@ -24,7 +24,9 @@ under these constraints:
 - Stage only `version.gradle.kts`. Any other modified files are out of scope
   for this skill's commit and must remain unstaged.
 - Use the exact subject `` Bump version -> `<new>` `` (see step 4 of the
-  Checklist) with the actual new version value substituted.
+  Checklist) with the actual new version value substituted. Keep the
+  backticks around the version literal (for example, ``... -> `2.0.0``` ) and
+  do not escape them as ``\````.
 - No `git push`, `git tag`, `git rebase`, `git commit --amend`, or any other
   history-writing operation. Those require a separate authorization
   (`.agents/safety-rules.md` → *Commits and history-writing*).
@@ -81,6 +83,12 @@ create the commit.
    Bump version -> `2.0.0-SNAPSHOT.183`
    ```
 
+   Shell-safe example (no escaped backticks in the commit subject):
+
+   ```bash
+   git commit -m 'Bump version -> `2.0.0-SNAPSHOT.183`' -- version.gradle.kts
+   ```
+
    Use the actual new version in the subject. Do not include unrelated files in
    this commit.
 

.agents/skills/check-links/SKILL.md

@@ -6,8 +6,10 @@ description: >
   the rendered HTML using the repo's `lychee.toml`, and reports any broken URLs
   grouped by source Markdown page. Use locally before pushing changes that
   touch `docs/**` or `site/**`, when CI's `Check Links` job fails, or whenever
-  the user asks to "check doc links". Read-only with respect to the project
-  sources. Does **not** cover Javadoc/KDoc (out of scope for this skill).
+  the user asks to "check doc links". If no Hugo site exists under `docs/` or
+  `site/`, report the check as not applicable instead of failing. Read-only
+  with respect to the project sources. Does **not** cover Javadoc/KDoc (out of
+  scope for this skill).
 ---
 
 # Check links in the Hugo docs (repo-specific)
@@ -48,11 +50,15 @@ both the skill and CI).
   `embed-code` blocks, sidenav YAML files, content under `<SITE_DIR>/content/`).
 - A change touches `lychee.toml` itself.
 - CI reported broken links and you want a fast local repro.
-- The user asks to "check the doc links" or invokes `/check-links`.
+- The user asks to "check the doc links" or invokes the `check-links` skill.
 
 If none of the above is true, decline with a one-line note rather than
 running the (~30 s) build+check.
 
+If the repository has no Hugo config under `docs/` or `site/`, return
+`APPROVE — no Hugo documentation site found under docs/ or site/.` and stop.
+Do not write a `FAIL` sentinel for this not-applicable case.
+
 ## Tooling
 
 The skill needs four binaries:
@@ -96,8 +102,8 @@ for dir in docs site; do
   done
 done
 if [ -z "$SITE_DIR" ]; then
-  echo "ERROR: No Hugo config found under docs/ or site/." >&2
-  exit 1
+  echo "APPROVE — no Hugo documentation site found under docs/ or site/."
+  exit 0
 fi
 
 if [ -f "${SITE_DIR}/_preview/package-lock.json" ]; then
@@ -194,7 +200,7 @@ lock-step with CI.)
 
 ### 5. Start the Hugo server in the background
 
-The server must survive across multiple `Bash` tool calls (steps 5 → 6 → 8
+The server must survive across multiple shell/tool calls (steps 5 → 6 → 8
 typically run in separate shells), so we rely on `nohup` alone — a `trap …
 EXIT` would fire when *this* shell exits and kill the server before Lychee
 can query it. Teardown happens explicitly in step 8.

.agents/skills/check-links/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Check Links"
+  short_description: "Validate rendered Hugo documentation links"
+  default_prompt: "Use $check-links to build the Hugo docs site, run Lychee against the rendered HTML, and report broken links."

.agents/skills/dependency-audit/SKILL.md

@@ -47,12 +47,12 @@ Each file declares a Kotlin `object` extending `Dependency` or `DependencyWithBo
    first and then re-read each file. If the diff is empty, ask the user
    which files to audit.
 
-2. **Lean on the diff; `Read` on demand.** Version, BOM, copyright, and
-   deprecation deltas are all visible in the unified diff. Only `Read` a
+2. **Lean on the diff; read files on demand.** Version, BOM, copyright, and
+   deprecation deltas are all visible in the unified diff. Only read a
    file when (a) it is newly added, or (b) a hunk references a
    `version`/`group` constant defined outside the hunk and you need
    surrounding context. **Budget:** if more than 5 files changed, do not
-   `Read` individual files — work from the diff and use targeted `Grep`
+   read individual files — work from the diff and use targeted `rg`
    for cross-cutting questions.
 
 3. **Batch independent work into one turn.** Issue the version-sanity (A),
@@ -75,7 +75,7 @@ Each file declares a Kotlin `object` extending `Dependency` or `DependencyWithBo
 5. **Fast path for pure version bumps.** If every hunk only modifies an
    existing `version` (or `bom`) string literal — no added/removed
    `const val`, no new files, no renames — run only Checks A and D.
-   Skip B, C, and E entirely. This is the dominant `/dependency-update`
+   Skip B, C, and E entirely. This is the dominant `dependency-update`
    shape; do not waste tool calls re-validating naming or deprecation
    discipline when nothing structural changed.
 
@@ -116,7 +116,7 @@ When an artifact is **renamed or removed**:
 ### D. Convention drift
 - **Copyright header year.** Every changed file should have a current-year
   copyright line. If a file was edited but its copyright says `2024`, flag it
-  (the user can run `/update-copyright` to fix).
+  (the user can run the `update-copyright` skill to fix).
 - **GitHub URL comment.** New `lib/` and `kotlinx/` files conventionally
   start with `// https://github.com/<owner>/<repo>` above the object.
   Recommend it if missing.

.agents/skills/dependency-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Dependency Audit"
+  short_description: "Review dependency declaration diffs"
+  default_prompt: "Use $dependency-audit to review dependency declaration changes for version sanity, BOM consistency, deprecations, and convention drift."

.agents/skills/dependency-update/SKILL.md

@@ -242,11 +242,11 @@ When the run completes, emit a Markdown report with these sections:
 End with the suggested next steps:
 
 1. Review the diff (`git diff buildSrc/src/main/kotlin/io/spine/dependency/`).
-2. Invoke `/version-bumped`. Every feature branch must advance
+2. Run the `version-bumped` skill. Every feature branch must advance
    `version.gradle.kts` strictly above the base before any
    `./gradlew build` (which may transitively `publishToMavenLocal`). The
    skill is a no-op when a bump already happened earlier on the branch
-   and otherwise calls `/bump-version` to perform the increment.
+   and otherwise uses the `bump-version` skill to perform the increment.
 3. Run `./gradlew build` (or `./gradlew clean build` if `.proto` files
    participate).
 4. Commit. Match the shape of the actual change: