@skill-graph/cli 0.5.7 → 0.5.8

package/CHANGELOG.md

@@ -8,23 +8,47 @@ Skill Graph versions describe the contract at each checkpoint in the git history
 
 ## [Unreleased]
 
+## [0.5.8] — 2026-05-19
+
+The "Karpathy-loop Phase 2" release. Ships the Phase 2 deterministic-drift sentinels, mirror-freeze linter, generated status doc, `doctor` subcommand, first hermetic test fixtures, and positioning + onboarding rework. Also absorbs the accumulated `[Unreleased]` backlog from 0.5.0 → 0.5.7 (publication-classification ledger, npm publish pipeline, stability-promotion lint check, schema_version 4 → 5 → 6 migrations, cross-repo version reconciliation, and the skill audit loop re-grounding reframe). The 33 Phase 1 truth-repair commits landed under 0.5.7 and are not re-listed here.
+
 ### Added
+
+- **`scripts/check-doc-drift.js`** — schema_version drift sentinel that scans active docs for stale `schema_version: N` references and refuses to teach an old contract as current. Reads the active version from `schemas/skill.schema.json`; allowlists `_archived/`, `docs/migrations/`, `examples/`, `CHANGELOG.md`, and `vN → vM` migration sections. Flags: `--json`, `--quiet`, `--include-warn`.
+- **`scripts/check-mirror-freeze.js`** — fails on active-source / active-package claims in the two docs-only deprecation mirrors (`skill-metadata-protocol`, `skill-audit-loop`). Detects `@skill-graph/protocol`, `@skill-graph/audit`, `src/`, `lib/schemas/`, `schemas/skill.v*.schema.json`, and `evals/` references that contradict the post-ADR-0009 docs-only status. File-level banner detection skips files explicitly stamped as historical / frozen / deprecation-mirror snapshots.
+- **`scripts/build-status-doc.js` + `docs/status.generated.md`** — single-source-of-truth status snapshot that pulls live values from `package.json`, the schema, the manifest, and the four deterministic check scripts. Replaces hand-maintained "Latest release" lines and ad-hoc skill-count claims. Flags: `--check`, `--stdout`, `--no-checks`.
+- **`skill-graph doctor`** — new CLI subcommand grouping all six deterministic checks (links, protocol, drift, mirror-freeze, lint, manifest) into one pass with a single summary table. Recommended first command for bug reports. Flags: `--json`, `--bail`, `--skip <name>`.
+- **`examples/fixture-skills/`** — hermetic test fixtures for `@skill-graph/cli` package tests. Ships `minimal-capability` (bare-minimum v6 frontmatter), `with-grounding` (4-sub-field `grounding` object for `scope: codebase`), `with-relations` (all four `relations.*` edges), and `comprehension-full` (flat Understanding fields + Health Block). Each demonstrates a different fixture archetype; `minimal-capability`, `with-grounding`, and `comprehension-full` lint clean against the active schema.
+- **`docs/positioning.md`** — explicit positioning of Skill Graph in the agent-skills ecosystem. Names what Skill Graph is **not** (a runtime, a marketplace, a tool platform) before naming what it **is** (an authoring + audit-time contract with a Karpathy keep-or-revert loop). Compares against Anthropic Skills, the Agent Skills spec, MCP, A2A, Smithery, Composio, and AGENTS.md. Includes the "60-second pitch", the "what this is not" matrix, the "when to reach for Skill Graph" gate, and the layered ecosystem map.
+- **README hero rework** — three new sections above the ecosystem diagram: "Is this for me?" (yes-if / no-if qualifying signals for a 30-second visitor), "What makes this different" (Karpathy keep-or-revert loop applied to skill libraries, with explicit citation), and a surfacing of `docs/quality-doctrine.md` as the codified quality bar.
+- **README two-onboarding-paths framing** — explicit routing of authors to `docs/QUICKSTART-30MIN.md` for hands-on first-skill authoring and to `docs/PRIMER.md` for the conceptual model first. Synthesis Item 48 resolved as "link, do not merge" because they serve different reader genres.
 - **`data/publication-classification.json`** — hand-edited ledger of per-skill marketplace publication classification (`publishable` / `sales-hub-bound` / `personal-infra`) plus market-state attributes (`tier`, `pop_score`, `source`, `needs_sanitization`, `demand_signal`, `rename_to`, `notes`). Seeds the `publicationQueue` in the unified `.opencode/progress/skill-audit-worklist.json` (consumed by `skill-audit-loop@0.3.0`). 218 skills classified at seed (136 publishable, 55 sales-hub-bound, 27 personal-infra). Seeded by `scripts/seed-publication-classification.js` from the now-archived 2026-05-18 priority doc; hand-edited going forward.
 - **`scripts/seed-publication-classification.js`** — one-off seeder script that parses the priority doc tables into the ledger. Re-runnable; preserves first-classification-wins semantics.
 - **`docs/marketplace-publication-queue.generated.md`** — auto-generated by `skill-audit-loop@0.3.0` from the ledger. Tier-grouped publication queue with conflict and orphan tracking. Replaces the hand-curated priority doc as the living source of marketplace publication priority.
 - **npm publish pipeline (SH-6111).** Added `.github/workflows/publish.yml` — CI publishes `@skill-graph/cli` to npm on `v*.*.*` tag push after `npm test` passes. Uses `NPM_TOKEN` secret and npm provenance attestation (`--provenance`). Manual prereqs before first publish: (1) create the `@skill-graph` npm org at https://www.npmjs.com/org/create (the npm CLI does NOT support org creation; the org must be created via the website), (2) add `NPM_TOKEN` as a GitHub repo secret. First publish is pending Jacob's `npm version patch && git push --tags`. See [README.md § Releasing](README.md#releasing-maintainers).
 - **Lint check 14 — stability promotion gate (SH-6109).** `scripts/skill-lint.js` now includes a WARN-level check that fires when a skill declares `stability: stable` without meeting five promotion criteria: (1) `eval_state` is `passing` or `monitored`, (2) `eval_score` ≥ 4.0 on the 0.0–5.0 scale, (3) `routing_eval: present`, (4) `drift_check.last_verified` within the last 90 days, (5) `grounding.truth_sources` is populated for `scope: codebase` and `scope: reference` skills (`scope: portable` is exempt). All five criteria are evaluated independently — all failures are reported, never short-circuited. WARN level only (never ERROR), so the 140 currently-experimental skills are unaffected. Implemented in `scripts/lint/check-stability-promotion.js`; 8 tests in `scripts/__tests__/test-stability-promotion.js` (6 required cases + 2 edge cases). Promotion criteria documented in `docs/skill-metadata-protocol.md § Stability Promotion Criteria`. Status: 0/140 library skills currently declare `stability: stable`.
 
-### Removed
-- **`docs/marketplace-publication-priority-2026-05-18.md`** — archived to `docs/_archived/marketplace-publication-priority-2026-05-18.md` and superseded by `docs/marketplace-publication-queue.generated.md`. The hand-curated priority doc lived for one day before being merged into the auto-generated queue (via `skill-graph/data/publication-classification.json` + `skill-audit-loop@0.3.0`). Reasoning preserved in the archived copy for audit-trail grep.
-
 ### Changed
+
+- **`scripts/check-markdown-links.js`** — broken links in `_archived/` paths now emit warnings instead of failing the build. Active docs remain strict. New `--strict-archived` flag elevates archived warnings to errors (useful when migrating an archive batch). Synthesis Item 49.
+- **README "External Context"** — replaced 5-bullet list of tangential references with a "Where Skill Graph fits" section that links directly to `docs/positioning.md` and surfaces the unique angle in one line.
+- **`bin/skill-graph.js`** — `evolve` subcommand labeled `[PREVIEW · monorepo-only]` in both the README quickstart and the CLI `--help`. Aligns the discoverability surface with the dispatcher's existing not-standalone-compatible error message.
 - **Cross-repo version reconciliation (SH-6124).** README and CHANGELOG references to `schema_version: 4` updated to `schema_version: 6` (the actual current contract owned by `skill-metadata-protocol`). Repository Map updated to mention v6 in `schemas/`. The local `schemas/` directory still pins v4 and v5 alongside v6 for tooling that consumes the schemas directly; the unversioned mirror tracks v6.
 - **schema_version 6 — flat fields + Health Block.** Promotes the seven nested `concept.*` sub-fields to flat top-level fields (`mental_model`, `purpose`, `boundary`, `analogy`, `misconception`; `definition` collapses into `description`; `taxonomy` collapses into `category` + `relations.broader`) and introduces the seven-field flat Health Block (`last_audited`, `last_changed`, `audit_verdict`, `eval_score`, `eval_failed_ids`, `lint_verdict`, `drift_status`). Added `schemas/skill.v6.schema.json` + the v5→v6 migration codemod at `scripts/migrate-skill-v5-to-v6.js`. Full author-facing procedure lives in [`skill-metadata-protocol/docs/migrations/v5-to-v6.md`](https://github.com/jacob-balslev/skill-metadata-protocol/blob/main/docs/migrations/v5-to-v6.md).
 - **schema_version 5 — closed `category` enum.** Closed the `category` field to a 6-value enum (`foundations | engineering | design | quality | agent | product`) and removed 7 deprecated values. Promoted `quality` from facet to 6th category. Added `schemas/skill.v5.schema.json` and `scripts/migrate-skill-v4-to-v5.js`.
 - **schema_version 4 naming cleanup.** Renamed `browse_category` to `category`, hierarchical `category` / `category_path` to `domain`, `project_tags` to `workspace_tags`, and `routing_groups` to `routing_bundles`. Added active and pinned v4 skill/manifest schemas, migrated shipped skills, regenerated manifests/exports/marketplace artifacts, and added `scripts/migrate-skill-v3-to-v4.js`.
 - **Skill Audit Loop reframed as a re-grounding mechanism (docs only, no `schema_version` impact).** The loop was documented mechanics-first — its cadence and outputs without its purpose. `README.md` and `SKILL_AUDIT_LOOP.md` now open with the conceptual frame: a skill is a contract about a subject, and the loop is what re-grounds it against its two moving targets — the codebase it is grounded in and the subject it describes. `README.md` closing line changed "maintenance loop" to "re-grounding loop"; `SKILL_GRAPH.md` gains a three-layer relationship paragraph (protocol declares grounding, graph operates across the library, loop re-grounds each skill on a cadence). Rationale recorded in new `docs/proposals/skill-audit-loop-positioning.md`. Stated entirely in existing protocol vocabulary — no new fields, scripts, or CLI verbs.
 
+### Removed
+
+- **`docs/marketplace-publication-priority-2026-05-18.md`** — archived to `docs/_archived/marketplace-publication-priority-2026-05-18.md` and superseded by `docs/marketplace-publication-queue.generated.md`. The hand-curated priority doc lived for one day before being merged into the auto-generated queue (via `skill-graph/data/publication-classification.json` + `skill-audit-loop@0.3.0`). Reasoning preserved in the archived copy for audit-trail grep.
+
+### Documented
+
+- **`docs/_archived/marketplace-publication-priority-2026-05-18.md`** — the archived plan's broken `./adr/...` link was fixed to `../adr/...` (Phase 1 Item 1).
+- **Mirror governance** — five mirror docs banner-stamped as frozen deprecation snapshots: `skill-metadata-protocol/docs/{concept-map, field-reference, field-reference.generated, skill-metadata-protocol}.md` and `skill-metadata-protocol/CONTRIBUTING.md` + `skill-audit-loop/{CONTRIBUTING, SKILL_AUDIT_LOOP, SKILL_AUDIT_CHECKLIST}.md` (Phase 1 Items 30, 25 + Phase 2 Item 36 follow-ups).
+- **`docs/plans/skill-graph-oss-docs-refresh.md`** (lives in the Development workspace, not this repo) — banner-stamped as superseded by ADR 0009 (Phase 2 Item 41).
+
 ## [0.5.0] — 2026-05-13
 
 The "package-ready CLI + contract honesty" release. It keeps the existing zero-dependency scripts as the implementation surface, exposes them through one npm-ready `skill-graph` binary, closes the v3.1 alias pass-through gap, and tightens router/path behavior that made the contract look stronger than the implementation.

package/README.md

@@ -6,6 +6,24 @@
 
 A plain `SKILL.md` gives an agent a procedure to load. The Skill Metadata Protocol adds the structured frontmatter contract. Skill Graph turns those declarations into a compiled manifest, routing map, drift sentinel, overlap detector, audit loop, and export path back to the plain `SKILL.md` format.
 
+## Is this for me?
+
+**Yes, if** you have **more than ~5 skills** that have started to depend on, verify, or exclude one another; you want **deterministic checks** for skill correctness (schema, paths, eval health) rather than only LLM-as-grader; you want a **single audit loop** that produces a per-skill fingerprint (`audit_verdict`, `eval_score`, `drift_status`) you ship in the skill's own frontmatter; or you want **graph queries** over the library ("what depends on this?", "what's the boundary between X and Y?", "which skills verify this one?").
+
+**No, if** you have 1–3 skills and a plain folder is enough; you want a hosted skill marketplace ([Smithery](https://smithery.ai), [agentskills.io](https://agentskills.io)); you want an agent runtime (Claude Code, Cursor, Codex); or you want a tool-execution platform ([Composio](https://docs.composio.dev), your runtime's tool layer).
+
+Full positioning vs. MCP, A2A, Anthropic Skills, Smithery, and Composio: [`docs/positioning.md`](docs/positioning.md).
+
+## What makes this different
+
+The mechanism is a **Karpathy-style keep-or-revert audit loop** ([autoresearch](https://github.com/karpathy/autoresearch)) applied to skill libraries instead of training scripts:
+
+- **One field, one commit, one keep-or-revert decision.**
+- Every change has a hard pass/fail gate — a deterministic check script that turns red or green.
+- Failed changes auto-revert. The lesson is recorded; the field's truth is preserved.
+
+The protocol's typed fields are the substrate that makes deterministic gates possible. The audit loop ([`docs/SKILL_AUDIT_LOOP.md`](docs/SKILL_AUDIT_LOOP.md)) is the mechanism. The quality bar that governs every change — what "improve" means, when it's safe to remove, how to enrich without dropping coverage — is codified in [`docs/quality-doctrine.md`](docs/quality-doctrine.md). Together they produce a library that drifts less, even as it grows.
+
 ## The ecosystem
 
 <p align="center">
@@ -41,18 +59,26 @@ graph TD
 
 ### Pick the right doc
 
+Two onboarding paths, by need:
+
+- **"I want to author my first skill in 30 minutes."** → [`docs/QUICKSTART-30MIN.md`](docs/QUICKSTART-30MIN.md) — literal terminal walkthrough: clone, install, fill in the template, lint, route a query, record the drift baseline. Use this when you'd rather try the tooling than read about it.
+- **"I want to understand the model before I commit."** → [`docs/PRIMER.md`](docs/PRIMER.md) — conceptual primer: what the protocol is, when to adopt it, the four orthogonal classification axes, the routing model, and what Skill Graph is *not*. Use this when you'd rather build the mental model first.
+
+The QUICKSTART points at the PRIMER for the "why"; the PRIMER points at the QUICKSTART for the "how". Read either first, then loop back.
+
+For everything else:
+
 | If you want to… | Start here |
 |---|---|
 | **Install the CLI** | [Quick Start](#quick-start) below — `npm install -g @skill-graph/cli` |
 | **Install the public skill library** | [`jacob-balslev/skills`](https://github.com/jacob-balslev/skills) — `npx skills add jacob-balslev/skills` |
 | **Understand the `SKILL.md` frontmatter contract** | [`docs/SKILL_METADATA_PROTOCOL.md`](docs/SKILL_METADATA_PROTOCOL.md) — the normative spec |
-| **Author a new skill** | [`docs/PRIMER.md`](docs/PRIMER.md) and [`examples/skill-metadata-template.md`](examples/skill-metadata-template.md) |
 | **Audit an existing skill library** | [`docs/SKILL_AUDIT_LOOP.md`](docs/SKILL_AUDIT_LOOP.md) — the audit procedure |
 | **Look up a specific field** | [`docs/field-reference.md`](docs/field-reference.md) |
 | **Plan adoption in a new repo** | [`docs/ADOPTION.md`](docs/ADOPTION.md) and [`docs/CONFORMANCE.md`](docs/CONFORMANCE.md) |
 | **Migrate from an older `schema_version`** | [`docs/migrations/`](docs/migrations/) |
 
-> **Surface scope:** The OSS-portable canonical library lives at `skills/skills/` (141 v6-compliant skills). A separate personal/Sales Hub surface at `skills/` (263 pre-v6) is frozen — new skills are curated into the OSS surface only when non-PII, non-Sales-Hub, and generalizable. See [ADR 0008](docs/adr/0008-skill-surface-split-and-curation-policy.md).
+> **Surface scope:** The OSS-portable canonical library lives at `skills/skills/` (145 v6-compliant skills). A separate personal/Sales Hub surface at `skills/` (263 pre-v6) is frozen — new skills are curated into the OSS surface only when non-PII, non-Sales-Hub, and generalizable. See [ADR 0008](docs/adr/0008-skill-surface-split-and-curation-policy.md).
 
 ## How SKILL.md, Skill Metadata Protocol, and Skill Graph Differ
 
@@ -270,7 +296,7 @@ The public, ready-to-install skill library lives at [`jacob-balslev/skills`](htt
 npx skills add jacob-balslev/skills
 ```
 
-That repo holds 141+ canonical skills in plain Agent-Skills shape, indexed on `skills.sh`. You do not need to clone this `skill-graph` tooling repo to consume the skills.
+That repo holds 145+ canonical skills in plain Agent-Skills shape, indexed on `skills.sh`. You do not need to clone this `skill-graph` tooling repo to consume the skills.
 
 ### Running the tooling (authors and maintainers)
 
@@ -281,7 +307,7 @@ npm install --global @skill-graph/cli
 skill-graph --help
 ```
 
-The tooling operates against a skill library configured via [`.skill-graph/config.json`](.skill-graph/config.json) → `workspace.skill_roots`. Post-2026-05-16 monorepo split, the shipped config points at the sibling [`jacob-balslev/skills`](https://github.com/jacob-balslev/skills) repo (canonical 141-skill library). Clone the canonical skills as a sibling of this repo and the tooling resolves automatically — no env-vars needed:
+The tooling operates against a skill library configured via [`.skill-graph/config.json`](.skill-graph/config.json) → `workspace.skill_roots`. Post-2026-05-18 consolidation, the shipped config points at the public [`jacob-balslev/skills`](https://github.com/jacob-balslev/skills) repo (canonical 145-skill library). Clone the canonical skills as a sibling of this repo and the tooling resolves automatically — no env-vars needed:
 
 ```bash
 git clone https://github.com/jacob-balslev/skills.git ~/Development/skills
@@ -319,11 +345,13 @@ skill-graph audit my-skill           # Seed or run a single-skill audit
 skill-graph route "schema drift"     # Select skills for a query
 skill-graph drift                    # Check truth-source hashes
 skill-graph export                   # Generate marketplace export surface
-skill-graph evolve --top 5           # Run the continuous improvement loop
+skill-graph evolve --top 5           # PREVIEW: continuous improvement loop (monorepo-only — see Note below)
 ```
 
 Run `skill-graph --help` to see all commands (including legacy aliases).
 
+> **Note on `evolve` (PREVIEW, not standalone-compatible).** `skill-graph evolve` depends on `lib/audit-shared/auto-improve.js` and several parent-repo scripts (`scripts/run-skill-improvement-loop.js`, `scripts/skill-auto-create.js`, `scripts/dispatch-solver.js`, `agent-orchestration/logs/`) that ship only in the source Development monorepo, not in the published `@skill-graph/cli` package. The CLI prints a clear error and exits when those deps are missing. Standalone refactor tracked in [SH-6138](https://linear.app/sales-hub/issue/SH-6138) (parent EPIC SH-6132). Until then, run from the source repo where the deps are available. Use `audit`, `lint`, `route`, and `drift` (all standalone) for the read-only Karpathy operations.
+
 ## What You Get
 
 | Tool | Purpose |
@@ -362,7 +390,7 @@ Run `skill-graph --help` to see all commands (including legacy aliases).
 
 | Repo | Status | Purpose |
 |---|---|---|
-| [`jacob-balslev/skills`](https://github.com/jacob-balslev/skills) | **active** | Public open-source 141-skill library. Distributed via `npx skills add jacob-balslev/skills`. |
+| [`jacob-balslev/skills`](https://github.com/jacob-balslev/skills) | **active** | Public open-source 145-skill library. Distributed via `npx skills add jacob-balslev/skills`. |
 | [`jacob-balslev/skill-metadata-protocol`](https://github.com/jacob-balslev/skill-metadata-protocol) | mirror | Historical docs-only mirror of the protocol spec (kept for inbound-link stability). Canonical doc now in [`docs/SKILL_METADATA_PROTOCOL.md`](docs/SKILL_METADATA_PROTOCOL.md). |
 | [`jacob-balslev/skill-audit-loop`](https://github.com/jacob-balslev/skill-audit-loop) | mirror | Historical docs-only mirror of the audit workflow. Canonical doc now in [`docs/SKILL_AUDIT_LOOP.md`](docs/SKILL_AUDIT_LOOP.md). |
 
@@ -421,19 +449,17 @@ Skill Graph is not:
 
 It is a structured protocol and reference toolchain for making skills easier to route, cluster, verify, maintain, and port.
 
-## External Context
+## Where Skill Graph fits
+
+Skill Graph sits **above** plain `SKILL.md` files and **beside** runtime protocols like MCP and A2A. It is an **authoring + audit-time** project, not a runtime. Full positioning with explicit comparisons against [Anthropic Skills](https://docs.anthropic.com/en/docs/claude-code/skills), [the Agent Skills spec](https://agentskills.io/specification), [MCP](https://modelcontextprotocol.io), [A2A](https://google.github.io/A2A/latest/specification/), [Smithery](https://smithery.ai), [Composio](https://docs.composio.dev), and [AGENTS.md](https://agents.md/) lives in [**`docs/positioning.md`**](docs/positioning.md) — it names what Skill Graph is **not** before naming what it **is**.
 
-Skill Metadata Protocol is designed to sit next to existing agent-context conventions, not replace them:
+One-line summary: most agent-skills projects answer *"how does the agent find / load / call / dispatch / publish a skill?"* Skill Graph answers *"how do you keep a library of skills correct over time?"* The unique mechanism is the **Karpathy keep-or-revert audit loop** applied to skill libraries instead of training scripts (see [Skill Audit Loop](#skill-audit-loop) below and [`docs/quality-doctrine.md`](docs/quality-doctrine.md) for the quality bar that doctrine enforces).
 
-- [SKILL.md format reference](https://agentskills.io/specification) describes the portable base skill layout used by multiple agent runtimes.
-- [AGENTS.md](https://agents.md/) and [Codex AGENTS.md docs](https://developers.openai.com/codex/guides/agents-md) define always-on repository instructions.
-- [Claude Code memory docs](https://code.claude.com/docs/en/memory) document one memory model for persistent context.
-- [Model Context Protocol](https://github.com/modelcontextprotocol/modelcontextprotocol) and [OpenTelemetry Specification](https://github.com/open-telemetry/opentelemetry-specification) are useful examples of protocol-first repos that separate spec, schema, docs, and reference tooling.
-- The project framing was also discussed in [GitHub Discussion #1](https://github.com/jacob-balslev/skill-graph/discussions/1) and the linked [Bluesky thread](https://bsky.app/profile/did:plc:dydxbat6yyyhjfaln22sx66t/post/3mln2lefdi22u).
+For project framing context, see [GitHub Discussion #1](https://github.com/jacob-balslev/skill-graph/discussions/1) and the linked [Bluesky thread](https://bsky.app/profile/did:plc:dydxbat6yyyhjfaln22sx66t/post/3mln2lefdi22u).
 
 ## Status
 
-Latest release: **`@skill-graph/cli@0.5.6`** (2026-05-18) — see [`CHANGELOG.md`](CHANGELOG.md). The current contract is `schema_version: 6` — see [`schemas/skill.v6.schema.json`](schemas/skill.v6.schema.json) for the authoritative shape and [`docs/migrations/v5-to-v6.md`](docs/migrations/v5-to-v6.md) for the migration procedure. The `schemas/` directory pins v2 through v6 for tooling that consumes the schemas directly. The unversioned `skill.schema.json` tracks v6.
+Latest release: **`@skill-graph/cli@0.5.7`** (2026-05-18) — see [`CHANGELOG.md`](CHANGELOG.md). The current contract is `schema_version: 6` — see [`schemas/skill.v6.schema.json`](schemas/skill.v6.schema.json) for the authoritative shape and [`docs/migrations/v5-to-v6.md`](docs/migrations/v5-to-v6.md) for the migration procedure. The `schemas/` directory pins v2 through v6 for tooling that consumes the schemas directly. The unversioned `skill.schema.json` tracks v6.
 
 ## Contributing & Trust
 

package/SKILL_GRAPH.md

@@ -62,8 +62,8 @@ A sixth set of files — `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `LICENS
 
 | File | Role |
 |---|---|
-| `schemas/skill.schema.json` | The frontmatter schema. Unversioned — tracks latest (v4 today). |
-| `schemas/manifest.schema.json` | The compiled-manifest schema. Unversioned — tracks latest (v3 today). |
+| `schemas/skill.schema.json` | The frontmatter schema. Unversioned — tracks latest (v6 today). |
+| `schemas/manifest.schema.json` | The compiled-manifest schema. Unversioned — tracks latest (v4 today; manifest contract shape has not advanced since v4 even as the skill schema moved to v6). |
 | `schemas/skill.v4.schema.json` | Pinned v4 copy. Consumers that want the current contract validate against this file. |
 | `schemas/skill.v3.schema.json` | Frozen pinned v3 copy for consumers still migrating to v4. |
 | `schemas/manifest.v4.schema.json` | Pinned v4 manifest copy. |

package/bin/skill-graph.js

@@ -213,6 +213,30 @@ Note: skill-graph evolve is not yet standalone-compatible. It depends on
     script: 'scripts/check-protocol-consistency.js',
     help: `Usage: skill-graph protocol-check [options]\n\nCheck cross-artifact protocol consistency across the C1-C8 invariants:\n\n  C1 — Field-set parity (field-reference.md vs skill.schema.json)\n  C2 — Authored-to-generated parity (skill.schema.json -> manifest.schema.json)\n  C3 — Artifact-root convention\n  C4 — Sample manifest correctness\n  C5 — Example truth invariants\n  C6 — Versioned schema parity (skill.schema.json vs skill.v6.schema.json)\n  C7 — Generated field-reference parity\n  C8 — JSON-LD context coverage (schema fields vs skill.context.jsonld)\n\nOptions:\n  --verbose   Print per-field diagnostics for each failed check.\n\nExit codes: 0 on PASS; non-zero on any FAIL.\n`,
   },
+  doctor:  {
+    inline: true,
+    help: `Usage: skill-graph doctor [options]
+
+Run every deterministic check in one pass and print a single summary table.
+This is the recommended first command when filing a bug report or onboarding
+a new install — it surfaces the project's complete trust surface at a glance.
+
+Checks executed (in order):
+  links              scripts/check-markdown-links.js
+  protocol           scripts/check-protocol-consistency.js
+  drift              scripts/check-doc-drift.js
+  mirror-freeze      scripts/check-mirror-freeze.js
+  lint               scripts/skill-lint.js
+  manifest           scripts/generate-manifest.js --validate-only
+
+Options:
+  --json             Emit a JSON summary instead of the human table.
+  --bail             Stop at the first failure instead of running every check.
+  --skip <name>      Skip a check by short name (repeatable). Example: --skip lint
+
+Exit codes: 0 if every check PASS; 1 if any check FAIL.
+`,
+  },
 };
 
 function printHelp() {
@@ -226,7 +250,10 @@ Commands:
   route <query>    Select and explain skills for a natural-language query
   drift            Check or record grounding truth-source hashes (drift sentinel)
   export           Generate and validate the public marketplace export surface
-  evolve           Run the continuous skill-improvement loop (Karpathy-style)
+  evolve           [PREVIEW · monorepo-only] Continuous Karpathy-style improvement loop (depends on parent-repo scripts; see SH-6138)
+
+Diagnostics:
+  doctor           Run every deterministic check in one pass (recommended for bug reports)
 
 Additional commands (retained for backward compatibility):
   manifest         Generate or validate a skills.manifest.json
@@ -245,6 +272,7 @@ Examples:
   skill-graph route "audit my skills for schema conformance"
   skill-graph drift --record --apply skills/graph-audit
   skill-graph export
+  skill-graph doctor
   skill-graph evolve --top 5 --max-cycles 3
 `);
 }
@@ -326,6 +354,93 @@ Examples:
   process.exit(0);
 }
 
+// ---------------------------------------------------------------------------
+// `doctor` — run every deterministic check in one pass
+// ---------------------------------------------------------------------------
+// Aggregates the project's trust-surface checks behind one command so a
+// reader (or bug-report filer) has a single number to verify.
+
+const DOCTOR_CHECKS = [
+  { name: 'links',          script: 'scripts/check-markdown-links.js' },
+  { name: 'protocol',       script: 'scripts/check-protocol-consistency.js' },
+  { name: 'drift',          script: 'scripts/check-doc-drift.js' },
+  { name: 'mirror-freeze',  script: 'scripts/check-mirror-freeze.js' },
+  { name: 'lint',           script: 'scripts/skill-lint.js' },
+  { name: 'manifest',       script: 'scripts/generate-manifest.js', args: ['--validate-only'] },
+];
+
+function runDoctor(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(COMMANDS.doctor.help);
+    process.exit(0);
+  }
+
+  const asJson = args.includes('--json');
+  const bail = args.includes('--bail');
+  const skipList = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--skip' && args[i + 1]) skipList.push(args[i + 1]);
+  }
+
+  const results = [];
+  for (const check of DOCTOR_CHECKS) {
+    if (skipList.includes(check.name)) {
+      results.push({ ...check, status: 'SKIP', exit_code: null, duration_ms: 0, tail: '' });
+      continue;
+    }
+    const scriptPath = path.join(REPO_ROOT, check.script);
+    if (!fs.existsSync(scriptPath)) {
+      results.push({ ...check, status: 'MISSING', exit_code: null, duration_ms: 0, tail: 'script not found' });
+      if (bail) break;
+      continue;
+    }
+    const t0 = Date.now();
+    const r = spawnSync('node', [scriptPath, ...(check.args || [])], {
+      cwd: REPO_ROOT,
+      encoding: 'utf8',
+      timeout: 120_000,
+    });
+    const duration_ms = Date.now() - t0;
+    const combined = (r.stdout || '') + (r.stderr || '');
+    const tail = combined.trim().split('\n').slice(-1)[0] || '';
+    const status = r.error ? 'ERROR' : r.status === 0 ? 'PASS' : 'FAIL';
+    results.push({
+      ...check,
+      status,
+      exit_code: r.status,
+      duration_ms,
+      tail: tail.slice(0, 240),
+    });
+    if (bail && status !== 'PASS' && status !== 'SKIP') break;
+  }
+
+  if (asJson) {
+    process.stdout.write(JSON.stringify({ checks: results }, null, 2) + '\n');
+  } else {
+    const namePad = Math.max(...DOCTOR_CHECKS.map(c => c.name.length));
+    process.stdout.write(`\nskill-graph doctor — ${results.length} check(s)\n\n`);
+    for (const r of results) {
+      const badge = r.status === 'PASS'
+        ? 'PASS'
+        : r.status === 'SKIP'
+          ? 'SKIP'
+          : `${r.status}`;
+      const padded = r.name.padEnd(namePad);
+      const time = r.duration_ms ? `${r.duration_ms}ms`.padStart(6) : '     —';
+      process.stdout.write(`  ${badge}  ${padded}  ${time}  ${r.tail}\n`);
+    }
+    const failed = results.filter(r => r.status !== 'PASS' && r.status !== 'SKIP');
+    process.stdout.write(
+      failed.length === 0
+        ? `\nAll ${results.length - results.filter(r => r.status === 'SKIP').length} check(s) PASS.\n`
+        : `\n${failed.length} check(s) failed: ${failed.map(f => f.name).join(', ')}\n`
+    );
+  }
+
+  const anyFail = results.some(r => r.status !== 'PASS' && r.status !== 'SKIP');
+  process.exit(anyFail ? 1 : 0);
+}
+
 // ---------------------------------------------------------------------------
 // Main dispatcher
 // ---------------------------------------------------------------------------
@@ -348,7 +463,8 @@ function main() {
 
   // Inline subcommands run in-process.
   if (entry.inline) {
-    if (command === 'init') { runInit(args); }
+    if (command === 'init') { runInit(args); return; }
+    if (command === 'doctor') { runDoctor(args); return; }
     // (future inline commands added here)
     return;
   }

package/docs/ADOPTION.md

@@ -58,7 +58,7 @@ The fields you pay for cluster into 8 semantic purposes (Identity, Classificatio
 For the full conceptual primer read [`PRIMER.md`](PRIMER.md). To migrate your first skill from a valid plain `SKILL.md` file:
 
 1. **Copy the template** — `cp examples/skill-metadata-template.md skills/<your-skill>/SKILL.md`. The template is a real, valid, schema-conformant Skill Metadata Protocol skill whose subject is skill authoring itself; adapt by rewriting identity, description, body, and verification.
-2. **Add the 13 required Skill Metadata Protocol fields** — `schema_version: 4`, `version`, `type`, `category`, `scope`, `owner`, `freshness`, `drift_check`, `eval_artifacts`, `eval_state`, `routing_eval`, plus your existing `name` and `description`. The template inline-comments each field.
+2. **Add the 13 required Skill Metadata Protocol fields** — `schema_version: 6`, `version`, `type`, `category`, `scope`, `owner`, `freshness`, `drift_check`, `eval_artifacts`, `eval_state`, `routing_eval`, plus your existing `name` and `description`. The template inline-comments each field.
 3. **Strip the teaching annotations** — every `> **TEMPLATE NOTE:**` blockquote and `# TEMPLATE NOTE:` YAML comment must be removed before commit.
 4. **Validate locally:**
    ```bash

package/docs/PRIMER.md

@@ -2,7 +2,7 @@
 
 > **Read this if:** you author SKILL.md and your library is large enough that skills have started to depend on, verify, or exclude one another. This primer is the conceptual introduction to Skill Metadata Protocol and Skill Graph. It is *explanation* documentation — it answers *what* and *why*. For reference material see `docs/field-reference.md`; for procedures see `CONTRIBUTING.md` and `SKILL_AUDIT_LOOP.md`; for decision tables see `docs/field-decision-guide.md`.
 
-**Status.** Stable for `schema_version: 4`.
+**Status.** Stable for `schema_version: 6`.
 **Audience.** Skill authors who need skills to declare their relevance: which area they cover, which angle they take, which project or stack they fit, which taxonomy / semantic cluster they belong to, and how they should be tested or reverified. Library size is a proxy for this — these questions usually start around 5 skills, sometimes earlier if you have multiple projects, sometimes later for a single small project.
 **Prerequisites.** Working familiarity with the [SKILL.md specification](https://agentskills.io/specification), including `SKILL.md` layout and the progressive-disclosure loading model.
 
@@ -10,11 +10,12 @@
 
 | Document | Purpose |
 |---|---|
-| `docs/PRIMER.md` (this file) | Conceptual introduction: what Skill Graph is, when to adopt it, how the metadata composes |
+| `docs/PRIMER.md` (this file) | Conceptual introduction: what Skill Graph is, when to adopt it, how the metadata composes (Diátaxis: *explanation*) |
+| [`docs/QUICKSTART-30MIN.md`](QUICKSTART-30MIN.md) | Hands-on tutorial: author your first skill in 30 minutes — clone, install, fill in the template, lint, route, record the drift baseline (Diátaxis: *tutorial*). Read this if you'd rather try the tooling first; the PRIMER is the *why* behind the *how* the QUICKSTART teaches. |
 | [`README.md`](../README.md) | Project overview, quick start, five-authority-tier tour |
 | [`SKILL_GRAPH.md`](../SKILL_GRAPH.md) | Repo organisation: five **authority tiers** (schema / explanation / enforcement / consumer / specimen) and the invariants CI enforces |
 | [`docs/skill-metadata-protocol.md`](skill-metadata-protocol.md) | Archetype section map, requiredness groups, schema strictness rules |
-| [`docs/field-reference.md`](field-reference.md) | Per-field semantics for all 40 current v4 top-level fields |
+| [`docs/field-reference.md`](field-reference.md) | Per-field semantics for all current v6 top-level fields |
 | [`docs/field-decision-guide.md`](field-decision-guide.md) | Decision tables for `scope`, `relations.*`, eval-health, `portability`, `workspace_tags` |
 | [`docs/manifest-field-mapping.md`](manifest-field-mapping.md) | The authored → generated bridge: rename map, loss policy, migration notes |
 | [SKILL.md specification](https://agentskills.io/specification) | The base standard Skill Metadata Protocol extends |
@@ -259,7 +260,7 @@ The claim that authored edges buy the consumer something needs proof. This secti
 
 ```yaml
 ---
-schema_version: 4
+schema_version: 6
 name: my-skill
 description: "Use when <concrete situation>. Covers <A, B, C>. Do NOT use for <D, E>."
 ---
@@ -276,7 +277,7 @@ The `refactor` starter skill reduced to its load-bearing fields:
 
 ```yaml
 ---
-schema_version: 4
+schema_version: 6
 name: refactor
 description: "Use when reorganizing existing code without changing external behavior..."
 type: workflow

package/docs/QUICKSTART-30MIN.md

@@ -70,7 +70,7 @@ The 13 required v4 fields are: `schema_version`, `name`, `description`, `version
 For `markdown-post-frontmatter-review`, the values look like:
 
 ```yaml
-schema_version: 4
+schema_version: 6
 name: markdown-post-frontmatter-review
 description: "Use when authoring or reviewing the YAML frontmatter of a markdown post — checking required fields (title, date, slug, tags), validating against the content schema, catching ambiguous date formats, and ensuring the slug matches the file path. Activate this skill whenever the task touches files under `content/posts/**/*.md` or the `parsePostFrontmatter()` helper — even if the user just says 'the post'. Do NOT use for general YAML schema design (use a different skill) or for chasing a specific build-time validation failure (use debugging)."
 version: 0.1.0
@@ -151,7 +151,7 @@ cp examples/skill-metadata-template.md skills/post-archive-rebuild/SKILL.md
 Edit `skills/post-archive-rebuild/SKILL.md` to set:
 
 ```yaml
-schema_version: 4
+schema_version: 6
 name: post-archive-rebuild
 description: "Use when re-indexing the post archive after one or more frontmatter fields have changed — walking every post, re-extracting the indexed fields, and writing the updated archive page. Activate this skill whenever the task says 'rebuild the archive' or mentions a post-index regeneration after a content edit. Do NOT use for routine authoring of a single post (use markdown-post-frontmatter-review)."
 version: 0.1.0

package/docs/SKILL_AUDIT_CHECKLIST.md

@@ -87,7 +87,7 @@ Required dimension rows:
 
 ### 1. Frontmatter validity
 
-- [ ] `schema_version` exists and equals `5` (integer; the string `"5"` is tolerated for hand-rolled YAML for back-compat — see `schemas/skill.v5.schema.json`)
+- [ ] `schema_version` exists and equals `6` (integer; the string `"6"` is tolerated for hand-rolled YAML for back-compat — see `schemas/skill.v6.schema.json`)
 - [ ] `name` exists and matches the intended skill identifier
 - [ ] `description` exists and is specific enough to route from
 - [ ] `version` exists

package/docs/SKILL_METADATA_PROTOCOL.md

@@ -540,7 +540,7 @@ find skills -name SKILL.md -exec sed -i '' 's/schema_version: "4"/schema_version
 
 | What changed | v4 form | v5 form |
 |---|---|---|
-| Schema version | `schema_version: 4` | `schema_version: 5` |
+| Schema version | `schema_version` was `4` | `schema_version` is `5` |
 | Schema file | `schemas/skill.v4.schema.json` (open-ended `category` string) | `schemas/skill.v5.schema.json` (closed `category` enum of 6 values) |
 | `category` enum | open-ended string; values included `knowledge`, `frontend`, `ai-engineering`, `integration`, `integrations`, `data`, `workflow`, `security` | closed enum: `foundations` \| `engineering` \| `design` \| `quality` \| `agent` \| `product` |
 | `foundations` gate | implicit | explicit anti-junk-drawer rule: target 8–15 skills; cannot default here; must clear epistemic-precondition test |
@@ -557,7 +557,7 @@ Run the codemod to migrate in place: `node scripts/migrate-skill-v3-to-v4.js <pa
 
 | What changed | v3 form | v4 form |
 |---|---|---|
-| Schema version | `schema_version: 3` | `schema_version: 4` |
+| Schema version | `schema_version` was `3` | `schema_version` was bumped to `4` |
 | Flat browse shelf | `browse_category: engineering` | `category: engineering` |
 | Hierarchical path | `category: engineering/api-design` or `category_path: engineering/api-design` | `domain: engineering/api-design` |
 | Workspace relevance tags | `project_tags: [...]` | `workspace_tags: [...]` |

package/docs/_archived/marketplace-publication-priority-2026-05-18.md

@@ -9,7 +9,7 @@
 > **Purpose:** prioritized publication queue for `github.com/jacob-balslev/skills` / `skills.sh/jacob-balslev/skills/`,
 > ranked by **expected popularity** given current marketplace demand signals.
 >
-> **Scope filter (per [ADR 0008](./adr/0008-skill-surface-split-and-curation-policy.md)):**
+> **Scope filter (per [ADR 0008](../adr/0008-skill-surface-split-and-curation-policy.md)):**
 > Sales-Hub-bound, customer-data-bearing, and personal/PII-bound skills are listed in the
 > "Excluded" sections so the decision is auditable — none are recommended for publication
 > in this pass.