skillwiki 0.8.5-beta.4 → 0.8.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.5-beta.4",
+  "version": "0.8.5",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.5-beta.4",
+  "version": "0.8.5",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 18 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.5-beta.4",
+  "version": "0.8.5",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 18 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",

package/skills/agents/wiki-lint.md

@@ -6,7 +6,7 @@ color: blue
 tools: ["Read", "Bash", "Grep", "Glob"]
 ---
 
-You are a vault health inspector specializing in running `skillwiki lint` and reasoning over the results. You operate autonomously during maintenance cycles — no user interaction expected.
+You are a vault health inspector specializing in running `skillwiki health` and `skillwiki lint --summary`, then reasoning over the results. You operate autonomously during maintenance cycles — no user interaction expected.
 
 ## When to invoke
 
@@ -15,33 +15,37 @@ You are a vault health inspector specializing in running `skillwiki lint` and re
 - **Pre-merge gate.** Verify vault health before allowing a sync/push.
 
 **Your Core Responsibilities:**
-1. Run `skillwiki lint` on the target vault
-2. Parse and group findings by severity (error > warning > info)
-3. Present actionable recommendations per finding kind
-4. Append a summary entry to `log.md`
+1. Run `skillwiki health` for whole-system coverage when the task asks for vault health
+2. Run `skillwiki lint --summary` for lint-only maintenance
+3. Parse bounded buckets and risk flags by severity (error > warning > info)
+4. Present actionable recommendations per finding kind
+5. Append a summary entry to `log.md` only when the task explicitly asks for a persisted maintenance note
 
 **Execution Process:**
 
 1. **Resolve vault.** Run `skillwiki path`. If NO_VAULT_CONFIGURED, report failure and STOP.
-2. **Run lint.** Execute `skillwiki lint <vault>`. Read the JSON output.
-3. **Reason over findings.** Group by severity. For each kind of finding, suggest concrete next actions. If the CLI was recently updated, new checks may flag pre-existing pages — treat these as legitimate findings, not false positives.
-4. **Log rotation.** If `log_rotate_needed` is present, note that user consent is required — do NOT auto-rotate.
-5. **Post-migration check.** If content was recently migrated, note whether broken_wikilinks count decreased. Remaining broken links for migrated content indicate pages still referencing moved files.
-6. **Write summary.** Append one entry to `{vault}/log.md` with the lint counts (errors/warnings/info) and a timestamp.
+2. **Run health or lint summary.** For whole-system health, execute `skillwiki health <vault> --out /tmp/skillwiki-health.json --no-fail`. For lint-only maintenance, execute `skillwiki lint <vault> --summary`. Read the JSON envelope. Treat `skillwiki doctor` as setup/runtime diagnostics only.
+3. **Drill into details only when needed.** If capped examples are insufficient, run the bucket's `details_command` or `skillwiki lint <vault> --only <bucket>`.
+4. **Reason over findings.** Group by severity. For each kind of finding, suggest concrete next actions. If the CLI was recently updated, new checks may flag pre-existing pages — treat these as legitimate findings, not false positives.
+5. **Log rotation.** If `log_rotate_needed` is present, note that user consent is required — do NOT auto-rotate.
+6. **Post-migration check.** If content was recently migrated, note whether broken_wikilinks count decreased after re-running `skillwiki lint <vault> --summary`. Remaining broken links for migrated content indicate pages still referencing moved files.
+7. **Optional summary.** Append one entry to `{vault}/log.md` with the lint counts (errors/warnings/info) and a timestamp only when explicitly requested.
 
 **Output Format:**
 Return a structured summary:
 - Vault path
 - Lint counts: errors N, warnings N, info N
 - Findings grouped by severity with suggested actions
+- Health risk flags and coverage state when `skillwiki health` was run
 - Whether log rotation is needed
-- The log.md entry that was appended
+- The log.md entry that was appended, if any
 
 **Stop Conditions:**
 - `skillwiki path` returns NO_VAULT_CONFIGURED
-- `skillwiki lint` fails with non-zero exit (report the error)
+- `skillwiki health` returns malformed JSON or self_check.status is error
+- `skillwiki lint --summary` returns malformed JSON
 
 **Forbidden:**
 - Auto-rotating logs without user consent
 - Auto-updating sha256 fields
-- Modifying any page beyond the lint summary entry in `log.md`
+- Modifying any page beyond an explicitly requested lint summary entry in `log.md`

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.8.5-beta.4",
+  "version": "0.8.5",
   "private": true,
   "files": [
     "wiki-*",

package/skills/skills/using-skillwiki/SKILL.md

@@ -68,7 +68,7 @@ sha256:          # computed by skillwiki hash over body bytes after closing ---
 | `wiki-init` | Bootstrap a new vault — SCHEMA.md, index.md, log.md, ~/.skillwiki/.env |
 | `wiki-ingest` | Convert URLs, files, or pasted text into typed-knowledge pages |
 | `wiki-query` | Search the vault and synthesize an answer with ranked results |
-| `wiki-lint` | Vault health check (stale pages, oversized pages, log rotation) |
+| `wiki-lint` | Vault health and lint checks; use `health` for whole-system reports and `lint --summary` for bounded lint buckets |
 | `wiki-crystallize` | Distill the current working session into a typed-knowledge page |
 | `wiki-audit` | Verify raw provenance references and source frontmatter integrity |
 | `wiki-archive` | Archive a typed-knowledge page — move to `_archive/`, remove from index |
@@ -106,9 +106,9 @@ Use `prd_layer` + `prd_pipeline` from `.claude/dev-loop.config.md` as source of
 - `manual` / `none`: no forced PRD skills; preserve skillwiki logging and provenance discipline.
 
 ## CLI Backbone
-All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, and linting. Skills invoke it via Bash for the mechanical parts and use Claude for the creative parts.
-Key CLI subcommands: `init`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `graph build`, `archive`, `drift`, `compound`, `tag-sync`, `sync status`, `seed`, `stale`, `observe`, `canvas generate`.
-Run `skillwiki doctor` to diagnose setup issues. Run `skillwiki config list` to see current configuration.
+All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, health reporting, and linting. Skills invoke it via Bash for the mechanical parts and use Claude for the creative parts.
+Key CLI subcommands: `init`, `health`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `graph build`, `archive`, `drift`, `compound`, `tag-sync`, `sync status`, `seed`, `stale`, `observe`, `canvas generate`.
+Run `skillwiki health <vault> --out /tmp/skillwiki-health.json --no-fail` for a bounded whole-system report that includes doctor, lint, vault-sync, query-readiness, source-freshness, risk flags, and self-check coverage. Run `skillwiki lint <vault> --summary` for lint-only bucket counts with capped examples and details commands. Run `skillwiki doctor` to diagnose setup/runtime issues only. Run `skillwiki config list` to see current configuration.
 
 ## Typical Workflow
 1. **Init** (`wiki-init`) — create vault, set domain and taxonomy

package/skills/skills/wiki-lint/SKILL.md

@@ -11,14 +11,16 @@ Standard four reads.
 ## Steps
 0. Resolve vault: `skillwiki path` (record source for context).
 - **CRITICAL**: Verify the correct vault when the user has multiple wiki instances (e.g., ~/wiki vs ~/wiki-fin). User may explicitly specify which vault to target — confirm before destructive operations.
-1. Run `skillwiki lint <vault>`. Read the JSON.
-2. Reason over findings; present grouped by severity with concrete suggested actions per kind. If the CLI was recently updated with new lint checks, re-running lint on the full vault may flag pre-existing pages that predate the new rule — treat these as legitimate findings, not false positives.
-3. If `log_rotate_needed` is present and the user consents, run `skillwiki log-rotate <vault> --apply`. Otherwise leave alone.
-4. **Post-migration verification**: If the user recently migrated content (e.g., moved entity/concept pages to another vault), re-run lint and verify that broken_wikilinks count decreased. Remaining broken links for migrated content indicate pages still referencing the moved files — these should be cleaned up (remove citations or migrate the referencing pages too).
-5. Append one `log.md` entry summarizing the lint counts (errors/warnings/info).
+1. For a whole-system health report, run `skillwiki health <vault> --out /tmp/skillwiki-health.json --no-fail`. Read the JSON envelope from stdout or the report file. Treat `skillwiki doctor` as setup/runtime diagnostics only, not a vault-content health report.
+2. For lint-only maintenance, run `skillwiki lint <vault> --summary`. This returns bounded bucket counts, capped examples, and `details_command` hints without full item arrays.
+3. Drill into important buckets with `skillwiki lint <vault> --only <bucket>` when examples are insufficient for remediation.
+4. Reason over findings; present grouped by severity with concrete suggested actions per kind. If the CLI was recently updated with new lint checks, re-running lint on the full vault may flag pre-existing pages that predate the new rule — treat these as legitimate findings, not false positives.
+5. If `log_rotate_needed` is present and the user consents, run `skillwiki log-rotate <vault> --apply`. Otherwise leave alone.
+6. **Post-migration verification**: If the user recently migrated content (e.g., moved entity/concept pages to another vault), re-run `skillwiki lint <vault> --summary` and verify that broken_wikilinks count decreased. Remaining broken links for migrated content indicate pages still referencing the moved files — these should be cleaned up (remove citations or migrate the referencing pages too).
+7. Append a `log.md` entry summarizing lint counts only when the user asked to record the maintenance result. Do not log routine `health` reports by default.
 ## Stop conditions
 None — lint reports all findings even on per-page errors.
 ## Forbidden
 - Auto-rotating logs.
 - Auto-updating sha256 fields.
-- Modifying any page beyond the lint summary entry in `log.md`.
+- Modifying any page beyond a user-approved lint summary entry in `log.md`.

package/skills/using-skillwiki/SKILL.md

@@ -68,7 +68,7 @@ sha256:          # computed by skillwiki hash over body bytes after closing ---
 | `wiki-init` | Bootstrap a new vault — SCHEMA.md, index.md, log.md, ~/.skillwiki/.env |
 | `wiki-ingest` | Convert URLs, files, or pasted text into typed-knowledge pages |
 | `wiki-query` | Search the vault and synthesize an answer with ranked results |
-| `wiki-lint` | Vault health check (stale pages, oversized pages, log rotation) |
+| `wiki-lint` | Vault health and lint checks; use `health` for whole-system reports and `lint --summary` for bounded lint buckets |
 | `wiki-crystallize` | Distill the current working session into a typed-knowledge page |
 | `wiki-audit` | Verify raw provenance references and source frontmatter integrity |
 | `wiki-archive` | Archive a typed-knowledge page — move to `_archive/`, remove from index |
@@ -106,9 +106,9 @@ Use `prd_layer` + `prd_pipeline` from `.claude/dev-loop.config.md` as source of
 - `manual` / `none`: no forced PRD skills; preserve skillwiki logging and provenance discipline.
 
 ## CLI Backbone
-All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, and linting. Skills invoke it via Bash for the mechanical parts and use Claude for the creative parts.
-Key CLI subcommands: `init`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `graph build`, `archive`, `drift`, `compound`, `tag-sync`, `sync status`, `seed`, `stale`, `observe`, `canvas generate`.
-Run `skillwiki doctor` to diagnose setup issues. Run `skillwiki config list` to see current configuration.
+All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, health reporting, and linting. Skills invoke it via Bash for the mechanical parts and use Claude for the creative parts.
+Key CLI subcommands: `init`, `health`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `graph build`, `archive`, `drift`, `compound`, `tag-sync`, `sync status`, `seed`, `stale`, `observe`, `canvas generate`.
+Run `skillwiki health <vault> --out /tmp/skillwiki-health.json --no-fail` for a bounded whole-system report that includes doctor, lint, vault-sync, query-readiness, source-freshness, risk flags, and self-check coverage. Run `skillwiki lint <vault> --summary` for lint-only bucket counts with capped examples and details commands. Run `skillwiki doctor` to diagnose setup/runtime issues only. Run `skillwiki config list` to see current configuration.
 
 ## Typical Workflow
 1. **Init** (`wiki-init`) — create vault, set domain and taxonomy

package/skills/wiki-lint/SKILL.md

@@ -11,14 +11,16 @@ Standard four reads.
 ## Steps
 0. Resolve vault: `skillwiki path` (record source for context).
 - **CRITICAL**: Verify the correct vault when the user has multiple wiki instances (e.g., ~/wiki vs ~/wiki-fin). User may explicitly specify which vault to target — confirm before destructive operations.
-1. Run `skillwiki lint <vault>`. Read the JSON.
-2. Reason over findings; present grouped by severity with concrete suggested actions per kind. If the CLI was recently updated with new lint checks, re-running lint on the full vault may flag pre-existing pages that predate the new rule — treat these as legitimate findings, not false positives.
-3. If `log_rotate_needed` is present and the user consents, run `skillwiki log-rotate <vault> --apply`. Otherwise leave alone.
-4. **Post-migration verification**: If the user recently migrated content (e.g., moved entity/concept pages to another vault), re-run lint and verify that broken_wikilinks count decreased. Remaining broken links for migrated content indicate pages still referencing the moved files — these should be cleaned up (remove citations or migrate the referencing pages too).
-5. Append one `log.md` entry summarizing the lint counts (errors/warnings/info).
+1. For a whole-system health report, run `skillwiki health <vault> --out /tmp/skillwiki-health.json --no-fail`. Read the JSON envelope from stdout or the report file. Treat `skillwiki doctor` as setup/runtime diagnostics only, not a vault-content health report.
+2. For lint-only maintenance, run `skillwiki lint <vault> --summary`. This returns bounded bucket counts, capped examples, and `details_command` hints without full item arrays.
+3. Drill into important buckets with `skillwiki lint <vault> --only <bucket>` when examples are insufficient for remediation.
+4. Reason over findings; present grouped by severity with concrete suggested actions per kind. If the CLI was recently updated with new lint checks, re-running lint on the full vault may flag pre-existing pages that predate the new rule — treat these as legitimate findings, not false positives.
+5. If `log_rotate_needed` is present and the user consents, run `skillwiki log-rotate <vault> --apply`. Otherwise leave alone.
+6. **Post-migration verification**: If the user recently migrated content (e.g., moved entity/concept pages to another vault), re-run `skillwiki lint <vault> --summary` and verify that broken_wikilinks count decreased. Remaining broken links for migrated content indicate pages still referencing the moved files — these should be cleaned up (remove citations or migrate the referencing pages too).
+7. Append a `log.md` entry summarizing lint counts only when the user asked to record the maintenance result. Do not log routine `health` reports by default.
 ## Stop conditions
 None — lint reports all findings even on per-page errors.
 ## Forbidden
 - Auto-rotating logs.
 - Auto-updating sha256 fields.
-- Modifying any page beyond the lint summary entry in `log.md`.
+- Modifying any page beyond a user-approved lint summary entry in `log.md`.