@skill-graph/cli 0.5.6

package/docs/concept-map.md

@@ -0,0 +1,194 @@
+# Skill Graph Concept Map
+
+> **Status:** Reality-aligned teaching reference as of **2026-04-20** (schema_version 4).
+> **Source of truth precedence:** `schemas/skill.v4.schema.json` > `docs/field-reference.md` > this file.
+> **Purpose:** Explain the 40-field Skill Metadata Protocol frontmatter at a conceptual level without inventing structure that the schema does not actually enforce. If this file disagrees with the schema, the schema wins — fix this file.
+
+## What kind of graph is this?
+
+Skill Graph is a **property graph with a controlled-vocabulary set of typed predicates**, not an RDF knowledge graph. Nodes are skills. Edges are the keys inside `relations.*`. Node attributes are the 40 top-level authored frontmatter fields. A JSON-LD `@context` (`schemas/skill.context.jsonld`) projects the property graph into SKOS / Dublin Core / PROV-O triples for consumers that want RDF semantics, but authoring stays in flat YAML.
+
+Skill Graph does **not** promise:
+
+- Automated inference (no OWL reasoner runs against the graph)
+- Open-world consistency checking (the schema closes it via `additionalProperties: false`)
+- SPARQL queryability as the primary interface (you get that by applying the JSON-LD `@context` first)
+
+What it does promise: deterministic lint, manifest generation, relation-aware routing, drift detection against content-addressable truth sources, and portable export to SKILL.md.
+
+## The 40 authored fields — grouped by role
+
+The fields split into nine conceptual groups. This grouping is a teaching aid only — the schema groups by *requiredness* (always required / required-for-archetype / required-for-scope / optional). See `docs/skill-metadata-protocol.md § Requiredness Groups` for the authoritative grouping.
+
+The exact field count:
+
+- **40 top-level authored fields** — the number authors write in YAML frontmatter, including compatibility aliases.
+- **13 required-for-all fields** — every skill must populate these.
+- **5 conditionally-required fields** — unlocked by `type: overlay`, `scope: codebase`, `stability: deprecated`, `comprehension_state: present`, plus `keywords` for routable skills.
+- **18 optional enrichment fields** — including the full nested sub-fields inside `relations`, `grounding`, `portability`, `compatibility`, `lifecycle`, `runtime_telemetry`, and concept/eval receipts.
+
+When you see "possible fields" counted anywhere, that is the count including nested sub-fields and v3.1 aliases individually. The 40 count refers to canonical top-level authored keys only.
+
+### Identity (5 fields, 4 required, 1 optional)
+
+The identity of the skill — what it is, who it is, which version of itself.
+
+| Field | Cardinality | Role | W3C mapping |
+|---|---|---|---|
+| `name` | one | Stable identifier; the handle other skills point at | `dcterms:identifier` |
+| `urn` | one | Optional globally unique persistent identifier | `dcterms:identifier` |
+| `description` | one | Routing contract — *when* to activate, not *what* the skill covers | `dcterms:description` |
+| `version` | one | Semver of the skill content itself | `dcterms:hasVersion` |
+| `owner` | one | Maintenance accountability | `dcterms:creator` |
+
+### Classification (6 fields, 4 required, 2 optional)
+
+The kind of skill and where it lives in the library.
+
+| Field | Cardinality | Role | Required? |
+|---|---|---|---|
+| `schema_version` | one | Contract version - currently `4` | always |
+| `type` | one enum | Archetype — `capability`, `workflow`, `router`, `overlay` | always |
+| `scope` | one enum | Locality — `portable`, `reference`, `codebase` | always |
+| `category` | one | Flat browse bucket (e.g. `engineering`, `knowledge`) | always |
+| `domain` | one slash-path | Hierarchical domain path (e.g. `ecommerce/integrations/shopify`) | optional |
+| `stability` | one enum | `experimental`, `stable`, `frozen`, `deprecated` | optional |
+| `superseded_by` | one | Replacement skill when deprecated | required if `stability: deprecated` |
+
+### Health & drift (4 fields, 2 required, 2 optional)
+
+Whether the skill is fresh, verified, and monitored. The two required fields (`freshness`, `drift_check`) answer different questions; lifecycle and telemetry add maintenance policy and live feedback when available.
+
+| Field | Cardinality | Question it answers | Required? |
+|---|---|---|---|
+| `freshness` | one ISO date | "When was this last editorially reviewed?" | always |
+| `drift_check` | one object (`last_verified` + `truth_source_hashes?`) | "When was this last verified against truth sources, and do the source hashes still match?" | always |
+| `lifecycle` | one object (`stale_after_days?` + `review_cadence?`) | "How fast does this rot, and how often should it be re-verified?" | optional |
+| `runtime_telemetry` | one object (`feedback_source` + `metrics?`) | "What do real-world runs say about whether this works?" | optional |
+
+Proposal for v4: collapse `freshness` + `drift_check.last_verified` + `lifecycle.stale_after_days` into two primitives (`asserted_at` + `stale_after`). Tracked in the v4 roadmap.
+
+### Eval health (5 fields, 3 required, 2 optional)
+
+Three independent axes of eval status. A skill can be at any point in the 3×3×2 product of these enums.
+
+| Field | Axis | Values |
+|---|---|---|
+| `eval_artifacts` | Does an eval file exist on disk? | `none` \| `planned` \| `present` |
+| `eval_state` | Have the evals been run and passed? | `unverified` \| `passing` \| `monitored` |
+| `routing_eval` | Is routing explicitly evaluated? | `absent` \| `present` |
+| `comprehension_state` | Is concept comprehension explicitly evaluated? | `absent` \| `present` |
+| `concept` | What concept model supports comprehension grading? | seven-field teaching block |
+| `eval_last_run` | What concrete run supports the current eval claim? | `{ at, status, receipt? }` |
+
+### Activation & routing (7 fields, 1 conditionally-required, 6 optional)
+
+How the skill surfaces to a router. The three trigger fields (`triggers`, `keywords`, `examples`) answer routing at three different specificities.
+
+| Field | Cardinality | Role |
+|---|---|---|
+| `triggers` | many | Exact phrase or label triggers |
+| `keywords` | many | Semantic keywords for fuzzy matching — required when skill is routable (`scope: codebase` or non-empty `routing_bundles`) |
+| `examples` | many | Positive-class activation prompts (few-shot retrieval targets) |
+| `anti_examples` | many | Negative-class prompts (hard negatives for boundary discrimination) |
+| `paths` | many glob patterns | File-surface activation |
+| `workspace_tags` | many | Project affiliation (literal handles or semantic tags) |
+| `routing_bundles` | many | Query-time overlapping bundles (`quality`, `integrations`) |
+
+### Relations (one object, up to 8 predicate keys, each optional)
+
+Typed edges to sibling skills. Lint verifies every target exists.
+
+| Predicate | Cardinality | Semantics | W3C mapping |
+|---|---|---|---|
+| `adjacent` *(deprecated alias)* / `related` | many skill names | Symmetric "co-read" relation | `skos:related` |
+| `depends_on` | many; string or `{skill, min_version}` | Pragmatic prerequisite | `dcterms:requires` |
+| `verify_with` | many | Co-load for verification | `prov:wasInformedBy` |
+| `boundary` | many; string or `{skill, reason}` | Routing-layer anti-ownership handoff | `sg:disjointOwnership` |
+| `disjoint_with` *(v3.1)* | many; string or `{skill, reason}` | Formal class-disjointness assertion | `owl:disjointWith` |
+| `broader` *(v3.1)* | many | Cross-skill generalisation — target is more general | `skos:broader` |
+| `narrower` *(v3.1)* | many | Cross-skill specialisation — target is more specific | `skos:narrower` |
+
+`adjacent` remains valid through v3.x as a deprecated alias of `related`; the v4 bump removes it in favour of the SKOS-aligned name. `boundary` remains canonical for routing-layer handoff. ADR 0001 records the `adjacent` rename; ADR 0006 records the `boundary` / `disjoint_with` split.
+
+### Inheritance (1 field, conditionally required)
+
+| Field | Cardinality | Role |
+|---|---|---|
+| `extends` | one skill name | Parent skill being specialised — required when `type: overlay` |
+
+Skill Graph supports single-parent inheritance only. For an overlay that needs to inherit concepts from two parents, express the secondary axis as `depends_on`. The OntoClean rigidity constraints for overlays are documented in ADR 0003.
+
+### Grounding (1 object, 5 required sub-fields — conditional on `scope: codebase`)
+
+Ties the skill to hashable artifacts and documents the trust hierarchy.
+
+| Sub-field | Cardinality | Role |
+|---|---|---|
+| `grounding.domain_object` | one | Primary artifact the skill describes |
+| `grounding.grounding_mode` | one enum | `repo_specific` \| `universal` \| `hybrid` |
+| `grounding.truth_sources` | many strings or anchored objects | Authoritative files, line ranges, or anchors |
+| `grounding.failure_modes` | many | Known degradation modes |
+| `grounding.evidence_priority` | one enum | `repo_code_first` \| `general_knowledge_first` \| `equal` |
+
+Drift hash semantics: `drift_check.truth_source_hashes` maps each normalized truth-source key to a SHA-256 digest at the time of last verification. Keys are `path` for whole-file sources, `path#Lstart-Lend` for line ranges, and `path#anchor` for anchor-only sources. Directories cannot be hashed; local truth sources must resolve to files, while URL truth sources are valid references but are not fetched by the zero-dependency sentinel. The drift sentinel (`scripts/skill-graph-drift.js`) reports `DRIFT` when live hash differs from recorded, `BROKEN` when a local source is missing, `STALE` when `last_verified + lifecycle.stale_after_days < today`, `NO_BASELINE` when local truth sources are declared but no hashes are recorded, and `EXTERNAL_UNHASHED` for URL truth sources.
+
+### Cross-cutting portability & standards (5 fields, all optional)
+
+Artifact-level metadata.
+
+| Field | Cardinality | Role |
+|---|---|---|
+| `license` | one | SPDX identifier (e.g. `MIT`, `Apache-2.0`) |
+| `compatibility` | one object (`runtimes?`, `node?`, `notes?`) | Runtime environment |
+| `allowed-tools` | one space-separated string | Pre-approved tool allowlist |
+| `portability.readiness` | one enum | `declared` \| `scripted` \| `verified` — operational export readiness |
+| `portability.targets` | many, currently `["skill-md"]` only | Export destinations |
+| `urn` *(v3.1, optional)* | one | Global persistent identifier — `urn:skill:<repo>:<name>`. Target: required in v4. |
+
+## The four orthogonal classification axes (carefully qualified)
+
+Skill Graph classifies along **three strictly-orthogonal axes plus one partially-coupled axis**. The concept map's earlier claim of "four orthogonal axes" overstated the orthogonality of `routing_bundles`.
+
+| Axis | Field | Orthogonality | Question |
+|---|---|---|---|
+| Scope | `scope` | Strict — `portable`/`reference`/`codebase` do not overlap | Where does this apply? |
+| Taxonomy | `category` + `category` | Strict — one flat bucket, one tree path | What kind of concern is this? |
+| Project affiliation | `workspace_tags` | Strict — multiple tags allowed, no hierarchy | Which projects use this? |
+| Routing bundle | `routing_bundles` | **Partially coupled to taxonomy** — `quality`, `integrations`, etc. are often functions of *what the skill is*, not *when it fires* | Which query-time bundle does this join? |
+
+The taxonomy-vs-routing-group coupling is intentional for ergonomics (a router can say "load all `quality` skills") but means the fourth axis is not a strict Ranganathan facet. Keep the distinction in mind when adding routing groups: if the group is redundant with the skill's category, use the category alone.
+
+## Archetype → body-section requirements
+
+The `type` field binds to required H2 sections in the SKILL.md body. This is enforced by `scripts/skill-lint.js`.
+
+| Archetype | Required H2 sections | OntoClean rigidity (see ADR 0003) |
+|---|---|---|
+| `capability` | `## Coverage`, `## Philosophy`, `## Verification`, `## Do NOT Use When` | +R +I +U -D |
+| `workflow` | `## Coverage`, `## Philosophy`, `## Workflow`, `## Verification`, `## Do NOT Use When` | +R +I +U -D |
+| `router` | `## Coverage`, `## Routing Rules`, `## Do NOT Use When` | ~R -I ~U +D |
+| `overlay` | `## Coverage`, `## Overlay Rules`, `## Extends`, `## Do NOT Use When` | -R -I -U +D |
+
+## How the concept map differs from earlier drafts (drift log)
+
+An earlier concept map (pre-2026-04-20) contained six inaccuracies now corrected here:
+
+1. Claimed "5 metadata layers" as canonical — corrected to "9 conceptual groups" with an explicit note that the schema groups by requiredness.
+2. Listed 9 identity fields including `schema_version`/`stability`/`superseded_by` — corrected to 4 identity fields (`name`, `description`, `version`, `owner`) with the other fields moved to Classification.
+3. Described `drift_check` as a scalar date — corrected to object (v3 shape, schema-enforced).
+4. Called the axes "4 orthogonal" — corrected to "3 strictly orthogonal + 1 partially coupled".
+5. Stated the field count without distinguishing authored-vs-possible — clarified that the current schema has 36 canonical top-level authored fields, while aliases and nested sub-field counts are separate measures.
+6. Omitted the 6-field-required-for-all set (`category`, `freshness`, `drift_check`, `eval_artifacts`, `eval_state`, `routing_eval`) — restored and grouped under Health & drift and Eval health.
+
+## References
+
+- `schemas/skill.v4.schema.json` — pinned v3 schema (source of truth for types and requiredness)
+- `schemas/skill.context.jsonld` — JSON-LD `@context` for W3C interoperability
+- `docs/skill-metadata-protocol.md` — requiredness groups, archetype section map, schema strictness
+- `docs/field-reference.md` — per-field semantics (authoritative prose)
+- `docs/field-decision-guide.md` — decision tables
+- `docs/adr/0001-predicate-set.md` — predicate evolution decision
+- `docs/adr/0002-json-ld-context.md` — W3C vocabulary mapping decision
+- `docs/adr/0003-ontoclean-rigidity-tags.md` — archetype rigidity semantics
+- `docs/adr/0004-persistent-identifiers.md` — URN scheme for v4

package/docs/diagrams/drift-states.mmd

@@ -0,0 +1,21 @@
+stateDiagram-v2
+  direction LR
+  [*] --> NO_BASELINE: skill declares<br/>grounding.truth_sources<br/>but truth_source_hashes absent
+  NO_BASELINE --> OK: --record --apply<br/>writes SHA-256 hashes
+  OK --> STALE: today − last_verified<br/>> lifecycle.stale_after_days
+  OK --> DRIFT: any live SHA-256<br/>≠ recorded hash
+  OK --> BROKEN: truth_source file<br/>missing on disk
+  STALE --> OK: author re-verifies<br/>bumps last_verified
+  STALE --> DRIFT: detected during re-verify
+  DRIFT --> OK: content re-verified<br/>--record --apply rewrites hashes
+  BROKEN --> OK: truth source restored<br/>--record --apply rewrites hashes
+  DRIFT --> BROKEN: truth source deleted<br/>before re-verify
+
+  note right of OK
+    Hashes match
+    within lifecycle window
+  end note
+  note right of NO_BASELINE
+    schema-valid but
+    unverifiable — fix first
+  end note

package/docs/diagrams/manifest-pipeline.mmd

@@ -0,0 +1,25 @@
+flowchart LR
+  Skills["<b>skills/&#42;/SKILL.md</b><br/>+ examples/skill-metadata-template.md<br/>authored frontmatter"]
+  Config[".skill-graph/config.json<br/>workspace roots + projects<br/><i>optional — falls back to skills/</i>"]
+  Parse["<b>parse-frontmatter.js</b><br/>YAML → object"]
+  Rename["<b>generate-manifest.js</b><br/>apply rename map<br/>group under activation / health"]
+  Hash["<b>SHA-256</b><br/>hash each grounding.truth_sources<br/>compute health.drift_detected"]
+  Validate{{"<b>ajv + manifest.schema.json</b><br/>additionalProperties: false"}}
+  Manifest["<b>skills.manifest.json</b><br/>compiled artifact"]
+
+  Skills --> Parse
+  Config -.-> Rename
+  Parse --> Rename --> Hash --> Validate
+  Validate -->|pass| Manifest
+  Validate -->|fail| Error((("exit 1")))
+
+  classDef input fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
+  classDef tool fill:#ecfdf5,stroke:#047857,color:#064e3b
+  classDef gate fill:#fce7f3,stroke:#db2777,color:#831843
+  classDef artifact fill:#fef3c7,stroke:#d97706,color:#78350f
+  classDef err fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d
+  class Skills,Config input
+  class Parse,Rename,Hash tool
+  class Validate gate
+  class Manifest artifact
+  class Error err

package/docs/diagrams/routing-harness.mmd

@@ -0,0 +1,41 @@
+flowchart LR
+  Start(["For each skill S<br/>in manifest"])
+  HasCases{{"S has examples[]<br/>or anti_examples[]?"}}
+  Skip(["SKIP<br/>no cases"])
+  Pos["Positive cases<br/>S.examples[]"]
+  Neg["Negative cases<br/>S.anti_examples[]"]
+  Route1["skill-graph-route<br/>top-1 winner"]
+  Route2["skill-graph-route<br/>top-1 winner"]
+  WinEq{{"winner === S?"}}
+  WinBound{{"winner === S?<br/>winner &isin; S.boundary?<br/>winner === null?"}}
+  PosPass(["PASS<br/>positive"])
+  PosFail(["FAIL<br/>positive"])
+  NegPass(["PASS<br/>negative"])
+  NegFail(["FAIL<br/>negative"])
+  Gap(["COVERAGE_GAP<br/>informational"])
+
+  Start --> HasCases
+  HasCases -->|no| Skip
+  HasCases -->|yes| Pos
+  HasCases -->|yes| Neg
+  Pos --> Route1 --> WinEq
+  Neg --> Route2 --> WinBound
+  WinEq -->|yes| PosPass
+  WinEq -->|no| PosFail
+  WinBound -->|winner === S| NegFail
+  WinBound -->|winner &isin; boundary| NegPass
+  WinBound -->|winner === null| Gap
+  WinBound -->|winner &notin; boundary<br/>and non-null| NegFail
+
+  classDef start fill:#ecfdf5,stroke:#047857,color:#064e3b
+  classDef gate fill:#fce7f3,stroke:#db2777,color:#831843
+  classDef work fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
+  classDef pass fill:#ecfdf5,stroke:#047857,color:#064e3b,font-weight:bold
+  classDef fail fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d,font-weight:bold
+  classDef skip fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95,stroke-dasharray:4 2
+  class Start,Skip start
+  class HasCases,WinEq,WinBound gate
+  class Pos,Neg,Route1,Route2 work
+  class PosPass,NegPass pass
+  class PosFail,NegFail fail
+  class Gap skip

package/docs/diagrams/starter-graph.mmd

@@ -0,0 +1,53 @@
+flowchart LR
+  A11Y["a11y<br/><i>capability · portable</i>"]
+  DBG["debugging<br/><i>workflow · portable</i>"]
+  DOC["documentation<br/><i>capability · portable</i>"]
+  GA["graph-audit<br/><i>capability · codebase</i>"]
+  LO["lint-overlay<br/><i>overlay · portable</i>"]
+  RF["refactor<br/><i>workflow · portable</i>"]
+  SR["skill-router<br/><i>router · portable</i>"]
+  TS["testing-strategy<br/><i>capability · portable</i>"]
+  ST(["skill-metadata-template<br/><i>specimen · reference</i>"])
+
+  %% depends_on — thick solid, load-bearing
+  RF ==>|depends_on<br/>^1.0.0| TS
+  LO ==>|extends| TS
+
+  %% verify_with — dashed, co-load for confidence
+  A11Y -.->|verify_with| TS
+  DBG -.->|verify_with| TS
+  GA  -.->|verify_with| TS
+  RF  -.->|verify_with| TS
+  TS  -.->|verify_with| DBG
+  SR  -.->|verify_with| GA
+  ST  -.->|verify_with| DOC
+
+  %% adjacent — thin undirected, suggested co-reading
+  DBG --- TS
+  DBG --- RF
+
+  %% boundary — red, anti-ownership
+  A11Y -. boundary .-x RF
+  DBG  -. boundary .-x DOC
+  DOC  -. boundary .-x DBG
+  DOC  -. boundary .-x A11Y
+  DOC  -. boundary .-x RF
+  GA   -. boundary .-x DOC
+  LO   -. boundary .-x DBG
+  RF   -. boundary .-x DOC
+  SR   -. boundary .-x DOC
+  ST   -. boundary .-x RF
+  TS   -. boundary .-x DOC
+
+  classDef capability fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
+  classDef workflow fill:#ecfdf5,stroke:#047857,color:#064e3b
+  classDef router fill:#fce7f3,stroke:#db2777,color:#831843
+  classDef overlay fill:#fef3c7,stroke:#d97706,color:#78350f,stroke-dasharray:4 2
+  classDef specimen fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95
+  classDef codebase stroke-width:3px
+  class A11Y,DOC,GA,TS capability
+  class DBG,RF workflow
+  class SR router
+  class LO overlay
+  class ST specimen
+  class GA codebase

package/docs/field-decision-guide.md

@@ -0,0 +1,315 @@
+# Skill Graph Field Decision Guide
+
+> Decision tables for the three hardest field choices in a `SKILL.md` file.
+> For full field semantics and rules, see `docs/field-reference.md`.
+> For field groups and conditional requiredness, see `docs/skill-metadata-protocol.md`.
+
+---
+
+## 1. Which `scope` do I use?
+
+`scope` tells routers and auditors whether your skill is portable, documentation-backed, or grounded in a specific codebase.
+
+### Decision table
+
+| Situation | Correct `scope` |
+|---|---|
+| Skill applies across any codebase or team with no repo-specific claims | `portable` |
+| Skill is primarily a reference for a contract, spec, or document (e.g., "Skill Metadata Protocol for this repo") | `reference` |
+| Skill makes concrete claims about files, APIs, or behavior in a specific codebase | `codebase` |
+| Skill is a starter or template that could be copied into any project | `portable` |
+| Skill references specific file paths, function names, or deployment details | `codebase` |
+| Skill documents abstract methodology (testing strategy, refactoring patterns) | `portable` |
+
+### Diagnostic questions
+
+**Q: Does my skill say "in `src/integrations/shopify/client.ts`" or similar?**
+→ `codebase`
+
+**Q: Does my skill say "in the codebase" without naming specific files?**
+→ `portable`
+
+**Q: Is my skill's primary purpose to be a reference for a contract document (like a schema or this Skill Metadata Protocol)?**
+→ `reference`
+
+**Q: Would this skill work unchanged if copied into a completely different project?**
+→ `portable` (if yes), `codebase` (if no)
+
+### Important constraint
+
+`scope: codebase` requires a populated `grounding` block. The schema enforces this — `scripts/skill-lint.js` will reject a codebase-scoped skill without grounding. If you choose `codebase`, populate `grounding` before committing.
+
+### Migration from v1
+
+The v1 scope values (`generic`, `operational`) were renamed in schema_version 2 (SH-5784) and are rejected as hard errors by the v2+ schemas. For the full v1 → v2 rename table see [`docs/field-reference.md § scope`](field-reference.md#scope); for the codemod that applies every v2 → v3 change automatically, see [`docs/manifest-field-mapping.md § Migration Note — v2 → v3`](manifest-field-mapping.md#migration-note--v2--v3-v040).
+
+### Examples
+
+```yaml
+# Correct: skill about abstract testing patterns
+scope: portable
+
+# Correct: skill that references this repo's protocol documents
+scope: reference
+
+# Correct: skill that covers Shopify integration in a specific codebase
+scope: codebase
+grounding:
+  domain_object: Shopify integration behavior
+  grounding_mode: repo_specific
+  # ...
+```
+
+---
+
+## 2. Which `relations.*` key do I use?
+
+The four relation keys serve distinct purposes. Using the wrong key creates misleading graph edges.
+
+### Decision table
+
+| Field | Use when | Do NOT use when |
+|---|---|---|
+| `adjacent` | Another skill is useful next reading or common co-loading | You need ordering or verification |
+| `boundary` | Users commonly confuse this skill with another | You only want related reading |
+| `verify_with` | A second skill materially increases confidence on the same task | The other skill is merely adjacent |
+| `depends_on` | This skill cannot be applied correctly before another one | You just want a recommended pairing |
+
+### Concrete examples
+
+The distinction between these relation types is best illustrated by existing usage in the library:
+
+- **`depends_on`** — `refactor` declares `depends_on: [testing-strategy]` because refactoring without understanding test strategy is unsafe. The concepts are foundational to the skill's correctness.
+
+- **`verify_with`** — `graph-audit` declares `verify_with: [testing-strategy]` because running the graph-audit verification alongside testing-strategy evals materially increases confidence in the skill's claims. They are commonly used together in audit pipelines.
+
+- **`adjacent`** — `refactor` declares `adjacent: [debugging, testing-strategy]` because readers of the refactor skill would benefit from understanding debugging and testing approaches. These are topically related but not mandatory dependencies.
+
+- **`boundary`** — `refactor` declares `boundary: [documentation]` to prevent confusion. Documentation skills are not owned by refactor — they are a separate domain. This guards against incorrect skill activation.
+
+When a skill extends another skill's base behavior (e.g., an overlay), use the `extends` field instead of relations.
+
+### Combined example
+
+```yaml
+relations:
+  adjacent:
+    - webhook-integration   # related: reader may want this context
+  boundary:
+    - fulfillment           # not owned here: route to fulfillment skill
+  verify_with:
+    - test-coverage         # co-load during audits
+  depends_on:
+    - api-key-management    # hard dependency: skill builds on this
+```
+
+### Validation
+
+All relation targets must be the `name` of an existing skill in the library. `scripts/skill-lint.js` rejects dangling targets (targets that point to non-existent skills).
+
+---
+
+## 3. What eval-health and `portability` state do I choose?
+
+### Eval-health state: the three orthogonal axes
+
+Schema_version 2 (SH-5784) split the v1 `eval_status` enum into three orthogonal fields because the old enum mixed artifact state, runtime state, and routing coverage into a single ordinal. Each axis now has its own value.
+
+#### `eval_artifacts` — "does a file exist?"
+
+```
+Does an eval artifact file exist for this skill?
+  NO  →  Is eval work intentionally deferred?
+            YES → planned
+            NO  → none
+  YES → present
+```
+
+| Value | Use when |
+|---|---|
+| `none` | No eval planned or authored. Rare — use sparingly. |
+| `planned` | Evals are intended but no artifact exists yet. Temporary state. |
+| `present` | At least one eval artifact exists on disk. `scripts/skill-lint.js` verifies it. |
+
+#### `eval_state` — "has it been run and passed?"
+
+```
+Have the evals been run and passed recently?
+  NO                                → unverified
+  YES, one-off manual run           → passing
+  YES, continuously run by a toolchain → monitored
+```
+
+| Value | Use when |
+|---|---|
+| `unverified` | Artifacts exist but no passing run has been recorded (or no artifacts yet). |
+| `passing` | A recent run exists and was green. Needs a concrete receipt. |
+| `monitored` | Actively run on a cadence by a live toolchain. |
+
+#### `routing_eval` — "do we check routing coverage?"
+
+| Value | Use when |
+|---|---|
+| `absent` | Routing / trigger coverage is not evaluated for this skill. Default for most starters. |
+| `present` | Eval artifacts include routing assertions (does the skill activate for the right prompts?). |
+
+**Anti-pattern.** Do not set `eval_state: passing` without an actual passing run. Do not set `eval_artifacts: present` without a real file — the lint script checks. Do not claim `routing_eval: present` when the eval only checks content, not routing.
+
+### Migration from v1
+
+The v1 `eval_status` enum collapsed three concerns into one. Map each old value to the new triple:
+
+| v1 `eval_status` | `eval_artifacts` | `eval_state` | `routing_eval` |
+|---|---|---|---|
+| `none` | `none` | `unverified` | `absent` |
+| `pending` | `planned` | `unverified` | `absent` |
+| `evals` | `present` | `passing` | `absent` |
+| `passing` | `present` | `passing` | `absent` |
+| `active` | `present` | `monitored` | `absent` |
+| `evals+trigger` | `present` | `passing` | `present` |
+
+### `portability.readiness` decision
+
+The `readiness` field is operational, not ordinal. Each value says something concrete about what is true of the skill today.
+
+| Readiness | Use when |
+|---|---|
+| `declared` | Portability is claimed in metadata only; no export tooling has run. |
+| `scripted` | Export tooling exists for at least one listed target (e.g., `scripts/export-skill.js` covers `skill-md`). |
+| `verified` | Export tooling exists AND the exported output has been verified in the target runtime with a receipt artifact. |
+
+**Quick heuristic:**
+- `scope: portable` with no repo paths AND export script covers at least one target → `readiness: scripted`
+- `scope: codebase` with concrete repo paths AND no export tooling yet → `readiness: declared`
+- Export tooling ran AND the output was loaded into the target runtime AND passed a smoke test → `readiness: verified`
+
+### `portability.targets` decision
+
+`targets` declares which runtimes the skill is portable to. (Renamed from `exports` in v2.)
+
+| Target | Include when |
+|---|---|
+| `skill-md` | The skill can be transformed to a valid SKILL.md file via `scripts/export-skill.js`. |
+
+The enum accepts only `skill-md` today. Other runtimes — `cursor`, `windsurf`, `copilot`, `agents-md` — were removed from the enum in 0.3.0. They previously sat in the enum as compatibility *goals* with no working transform, which violated the contract's `additionalProperties: false` strictness rule. Re-add via a new RFC and the same PR that ships the transform for that runtime.
+
+**Rule of thumb:** if the skill can round-trip through `scripts/export-skill.js` today, include `skill-md`. Otherwise omit the `portability` block entirely.
+
+### Migration from v1
+
+| v1 `portability.level` | v2 `portability.readiness` |
+|---|---|
+| `high` | `scripted` (if an export script covers at least one target) else `declared` |
+| `medium` | `scripted` (if an export script covers at least one target) else `declared` |
+| `low` | `declared` |
+
+`portability.exports` was renamed to `portability.targets`. Values are unchanged.
+
+```yaml
+# Canonical: the only target currently accepted by the schema.
+portability:
+  readiness: scripted
+  targets:
+    - skill-md
+```
+
+---
+
+## 4. How do I tag a skill for multiple projects?
+
+`workspace_tags` is the v3 mechanism for multi-project relevance. It is flat and composable — no hierarchy required. A workspace config at `.skill-graph/config.json` expands literal project handles into semantic tag sets, so one skill tag can match many projects.
+
+### Decision table
+
+| Situation | Correct `workspace_tags` |
+|---|---|
+| Skill applies to every project (cross-cutting concern) | Omit `workspace_tags` (ambient) |
+| Skill applies to one specific project and not reusable elsewhere | `[literal-project-handle]` |
+| Skill applies to several projects that share a technology / domain | Semantic tag(s) that the workspace config maps those projects to |
+| Skill applies to one project by literal handle AND to a semantic group | Both: `[literal-handle, semantic-tag]` |
+| Single-project workspace | Omit `workspace_tags` always |
+
+### Literal vs semantic tags
+
+| Tag style | Example | When to use |
+|---|---|---|
+| Literal | `<your-project-handle>` (whatever short kebab-case name you give a project in your workspace config) | Precise targeting. Couples the skill to a specific project name. Readable but brittle to renames. |
+| Semantic | `ecommerce`, `saas`, `b2b` | Reusable across projects. The workspace config declares which literal projects expand to which semantic tags, so one tag matches several projects. |
+
+**Prefer semantic when possible.** Literal handles work but they bind the skill to a project name. Semantic tags describe the domain and survive project renames.
+
+### Diagnostic questions
+
+**Q: Does my workspace have more than one project?**
+→ If no, omit `workspace_tags` always.
+
+**Q: Is this skill a cross-cutting concern (GDPR, a11y, testing patterns, general coding rules)?**
+→ Omit `workspace_tags` — ambient.
+
+**Q: Does this skill reference a specific project's files or domain?**
+→ Tag with that project's literal handle OR its semantic tags.
+
+**Q: Would I want to reuse this skill if I cloned the current project pattern into a new project?**
+→ If yes, tag with semantic tags (so the new project can map its handle to those tags). If no, tag with the literal handle.
+
+### Example
+
+```yaml
+# One specific project only — literal targeting
+workspace_tags: [<project-a>]
+
+# Cross-ecommerce — semantic, applies to every project whose config maps to `ecommerce`
+workspace_tags: [ecommerce]
+
+# Explicit both — literal match on <project-a>, semantic match on any ecommerce project
+workspace_tags: [<project-a>, ecommerce]
+```
+
+With a hypothetical two-project workspace config:
+
+```json
+{
+  "workspace": {
+    "projects": {
+      "<project-a>":  { "semantic_tags": ["ecommerce", "saas", "b2b"] },
+      "<project-b>":  { "semantic_tags": ["ecommerce", "b2c"] }
+    }
+  }
+}
+```
+
+(`<project-a>` and `<project-b>` are placeholders — adopters use whatever kebab-case handles they choose.) A skill with `workspace_tags: [ecommerce]` routes into both projects. A skill with `workspace_tags: [b2b]` routes only into the first. A skill with no `workspace_tags` routes into all projects (ambient).
+
+---
+
+## 5. Do I use `category`, `category`, `workspace_tags`, or `routing_bundles`?
+
+These four fields all group skills, but they answer different questions. Picking the wrong field creates misleading organization that corrodes routing quality. Use this table before adding any skill-grouping field:
+
+| Field | Answers the question | Shape | Primary consumer |
+|---|---|---|---|
+| `category` | What flat bucket does this skill live in for quick browsing? | single string (e.g., `integration`) | human browse UI, filter dropdowns |
+| `category` | Where does this skill sit in a hierarchy for tree browsing? | slash-delimited path (e.g., `ecommerce/integrations/shopify`) | folder-tree UI, docs site navigation |
+| `workspace_tags` | Which of my projects is this skill relevant to? | flat array (e.g., `[<project-a>, ecommerce]`) | router filter at routing time |
+| `routing_bundles` | Which batch-activation group does this skill belong to? | flat array (e.g., `[quality, security]`) | router batch-load by group label |
+
+### Three rules that prevent misuse
+
+1. **Never use `category` for routing.** It's a browse index. If you find yourself writing "when the router sees `integration` it should load all X" — you want `routing_bundles`, not `category`.
+
+2. **Never use `workspace_tags` for taxonomy.** It's a routing filter. If you find yourself tagging every skill with every project handle to build a grouping — you want `category` or `category`.
+
+3. **Never use `category` to filter routing.** A hierarchy helps humans find skills. The router doesn't walk it. If you want the router to match `ecommerce/integrations/shopify` at query time, flatten it into `routing_bundles: [integrations]` or `workspace_tags: [ecommerce]`.
+
+### Worked example
+
+A Shopify skill in a multi-project, large-library workspace:
+
+```yaml
+category: integration        # "Where does it live in a flat browse UI?"
+category: ecommerce/integrations/shopify   # "Where in a tree?"
+workspace_tags: [ecommerce]           # "Which of my projects?"
+routing_bundles: [integrations]      # "Which batch-activation group?"
+```
+
+Each field does a distinct job. None is redundant with the others. A smaller library can omit `category` entirely; a single-project workspace can omit `workspace_tags`; a library with no batch-activation pattern can omit `routing_bundles`. `category` is always present because it is required.