@vibe-agent-toolkit/vat-development-agents 0.1.37 → 0.1.38

package/README.md

@@ -71,7 +71,7 @@ vat skills install ./packages/vat-development-agents
 vat skills list --installed
 ```
 
-The `vibe-agent-toolkit` skill will be installed to `~/.claude/plugins/vibe-agent-toolkit/` and will appear in Claude Code after restarting or running `/reload-skills`.
+The `vibe-agent-toolkit` skill will be installed to `~/.claude/plugins/vibe-agent-toolkit/` and will appear in Claude Code after restarting or running `/reload-plugins`.
 
 **What the skill includes:**
 - VAT overview and use cases

package/dist/.claude/plugins/marketplaces/vat-skills/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "vibe-agent-toolkit",
       "description": "Development agents and skills for building with vibe-agent-toolkit",
       "source": "./plugins/vibe-agent-toolkit",
-      "version": "0.1.37",
+      "version": "0.1.38",
       "author": {
         "name": "vibe-agent-toolkit contributors"
       }

package/dist/.claude/plugins/marketplaces/vat-skills/CHANGELOG.md

@@ -7,6 +7,190 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.38] - 2026-05-18
+
+### Changed (breaking, pre-1.0)
+
+- **`findProjectRoot` from `@vibe-agent-toolkit/utils` has new semantics.** It
+  now walks `vibe-agent-toolkit.config.yaml` → `.git/` and returns
+  `string | null` with no fallback to `cwd`. The previous workspace-anchored
+  behavior (workspace `package.json` → git → `cwd`, returning `string`) moved
+  to a new function: `findNodeWorkspaceRoot`, scoped to workspace `package.json`
+  lookup only and also returning `string | null`. Migration: use
+  `findNodeWorkspaceRoot` if you wanted Node-monorepo binary discovery; use
+  `findProjectRoot` if you wanted the VAT authoring boundary. Either way,
+  handle the `null` return — there is no more silent `cwd` fallback.
+
+- **`resolveLocalHref` returns a discriminated union.** From
+  `{ resolvedPath; anchor } | null` to one of `anchor_only | resolved |
+  absolute_no_root | absolute_escapes_root`. The function exported from
+  `@vibe-agent-toolkit/resources` now also accepts an optional `projectRoot`
+  parameter. Leading-`/` markdown links and frontmatter URI-references now
+  resolve against `projectRoot` per RFC 3986 §4.2 absolute-path-reference
+  semantics — matching GitHub, MkDocs, Sphinx, Docusaurus, VuePress, Jekyll,
+  Astro Starlight, Nextra, and MDN. Previously `safePath.resolve(sourceDir,
+  '/docs/foo.md')` resolved to filesystem-absolute `/docs/foo.md`. The two
+  new union kinds (`absolute_no_root`, `absolute_escapes_root`) surface to
+  consumers as the existing `broken_file` issue with distinct messages — no
+  new validation-code names. External callers destructuring the old return
+  shape must update to switch on `kind`.
+
+- **`ValidateLinkOptions.projectRoot` semantic narrowing.** In monorepos, the
+  effective root for link validation is now the nearest
+  `vibe-agent-toolkit.config.yaml` ancestor (or `.git/` ancestor), not the
+  workspace root. Cross-package relative links (`../sibling-pkg/foo.md`) are
+  still validated for file existence, case mismatches, and anchor resolution
+  — path-based logic is unaffected. **The gitignore-safety gate, however,
+  scopes to the sub-package's `projectRoot` only.** Adopters who own per-package
+  `vibe-agent-toolkit.config.yaml` files in a monorepo and rely on
+  workspace-wide gitignore checking for cross-package doc links must either
+  move the config up to the workspace root or accept the narrower scope. In
+  practice, the file-existence + anchor checks are what catch broken links;
+  the narrower gitignore gate matches how VAT already treats links to
+  truly-external files.
+
+- **Some adopter configs may need `validation.allow.LINK_OUTSIDE_PROJECT`.**
+  Because the effective `projectRoot` narrows in monorepos with per-package
+  configs, cross-package links that previously passed under workspace-wide
+  scope may now emit `LINK_OUTSIDE_PROJECT`. Add a `validation.allow` entry
+  for the affected paths or `validation.severity` override at the config that
+  governs the linking skill.
+
+- **`Logger.warn` added to the CLI `Logger` interface.** The interface widened
+  with a `warn(message: string): void` method that writes to stderr. If you
+  implement the `Logger` interface directly (custom embedders, test doubles),
+  add the method.
+
+- **`excludeReferencesFromBundle` no longer masks cross-package links flagged
+  as outside-project.** Under the new `projectRoot` model, `outside-project`
+  fires before bundle-exclusion pattern match. If you used
+  `excludeReferencesFromBundle` to hide cross-package links from audit, those
+  links will now surface — switch to `validation.severity` or `validation.allow`
+  on `LINK_OUTSIDE_PROJECT` for the relevant skill.
+
+- **Skill packager rewrites frontmatter URI-references during packaging.**
+  When a markdown file's collection has a `frontmatterSchema` configured, the
+  packager now walks every schema-annotated URI-reference field (`format:
+  uri-reference`, `uri`, `iri-reference`, `iri`) and rewrites the value with
+  the same target-path lookup that drives body-link rewriting. Body and
+  frontmatter URI-refs now agree on packaged paths, and inline comments on
+  rewritten fields survive. Previously, packaged artifacts could ship with
+  rewritten body links but stale source-path frontmatter pointers — a silent
+  half-correct rewrite.
+
+- **`@vibe-agent-toolkit/resource-compiler` now depends on
+  `@vibe-agent-toolkit/resources`.** The markdown parser there goes through
+  `openFrontmatter` so frontmatter comments survive into compiled output.
+  Pure transitive consumers see no API change; embedders who installed
+  `resource-compiler` standalone now pull `resources` too.
+
+### Added
+
+- **Canonical comment-preserving primitive for frontmatter edits:
+  `openFrontmatter` from `@vibe-agent-toolkit/resources`.** Wraps `yaml`
+  (eemeli) in a round-trip-safe editor with `get` / `set` / `setArrayItem` /
+  `appendArrayItem` / `delete` / `toString` and a settable `body`. Comments,
+  blank lines, key order, quoting style, anchors, and EOL survive on
+  mutation. `openFrontmatter(x).toString()` is byte-identical to `x` until
+  you mutate. Malformed YAML throws `FrontmatterParseError` with the
+  underlying error on `.cause`. Use this instead of `gray-matter`,
+  `front-matter`, or raw `yaml.parse` for any write path — those drop
+  comments silently.
+
+- **`createAjvWithUriFormats(options?)` from `@vibe-agent-toolkit/resources`** —
+  Ajv factory pre-registered with the URI-family formats (`uri`,
+  `uri-reference`, `iri`, `iri-reference`) plus the rest of the
+  `ajv-formats` standard vocabulary. Use this anywhere downstream code
+  compiles a schema that may reference those formats: vanilla
+  `new Ajv({ allErrors: true })` throws `unknown format "uri-reference"
+  ignored` under default strict mode, and adopters had to invent the
+  workaround themselves. `iri` / `iri-reference` are registered as no-op
+  validators (semantic validation is the caller's job — VAT uses
+  `resolveLocalHref` for that). Ajv options pass through unchanged so
+  callers control `allErrors`, `strict`, `verbose`, etc.
+
+- **Three rewriter helpers sharing one `(href: string) => string` callback
+  shape**, exported from `@vibe-agent-toolkit/resources`:
+  - `rewriteBodyLinks(body, rewriteHref)` — inline links + reference
+    definitions in the markdown body.
+  - `rewriteFrontmatterFieldsAtPaths(editor, paths, rewriteHref)` — when you
+    know the field paths by convention (`'meta.parent'`, `'adrs-cited[]'`).
+  - `rewriteFrontmatterUriReferencesFromSchema(editor, schema, rewriteHref)`
+    — when you have a JSON Schema and want every `format: uri-reference`
+    field walked automatically. Compose with `rewriteBodyLinks` for the
+    common file/folder-rename case.
+
+- **New `markdown-rewriting` skill in the `vibe-agent-toolkit` Claude Code
+  plugin** — steers any session about to programmatically edit markdown or
+  frontmatter toward the comment-preserving primitives above. Includes the
+  canonical file-move recipe (body + frontmatter together) and the
+  schema-driven variant. Triggers on prompts like "rewrite references
+  across these docs", "rename `/docs/specs/` to `/docs/architecture/`",
+  "batch-update parent_spec".
+
+- **URI-references in frontmatter are now a documented affordance.** Updates
+  to two existing skills:
+  - `vat-knowledge-resources` — explains the leading-`/` resolution
+    + comment-preservation story for schema-annotated URI-ref fields.
+  - `vat-skill-authoring` — recommends leading-`/` URI-refs for cross-document
+    references in SKILL.md frontmatter and cross-links `markdown-rewriting`
+    for programmatic edits.
+
+- **Per-command `projectRoot` and config policies, documented and enforced.**
+  Every `vat` command now declares its `projectRoot` policy (`required` /
+  `tolerate null` / `loud-cwd` / `N/A`) and config policy (`required file` /
+  `required fields` / `accept defaults` / `not used`) in `--help` output and
+  in its CLI reference doc under `packages/cli/docs/` or `docs/cli/`. The
+  canonical source is the new [Roots and Config — Canonical
+  Concepts](docs/concepts/roots-and-config.md) doc. Run `vat <cmd> --help` to
+  see the `Requirements:` block for any command.
+
+- **Loud-cwd fallback for `vat resources scan` and `vat resources validate`.**
+  When invoked without an explicit path and no `vibe-agent-toolkit.config.yaml`
+  or `.git/` ancestor is found, these commands now fall back to `cwd` and emit
+  a single stderr warning (`warn: no vibe-agent-toolkit.config.yaml or .git/
+  ancestor; using <cwd> as projectRoot`) instead of failing silently or
+  surprising the user. With an explicit path argument the path is used and no
+  warning fires.
+
+- **`docs/concepts/roots-and-config.md`** — single source of truth for the
+  three-root model (`projectRoot` / `gitRoot` / `nodeWorkspaceRoot`), the
+  config-then-git discovery ladder, the CLI-boundary discovery rule, the
+  per-command policy matrix, and the loud-cwd fallback contract. Every
+  command's `Requirements:` help block links to this doc.
+
+### Removed
+
+- `findConfigPath`, `findConfigFile` (from `packages/resources/src/config-parser.ts`),
+  `findGoverningConfig`, `resetGoverningConfigCache`. Use `findConfigFile`
+  from `@vibe-agent-toolkit/utils` for config discovery, and `findProjectRoot`
+  + `loadConfigCached` for root + config loading at CLI boundaries. Cache
+  resets: `resetGoverningConfigCache()` → `resetProjectRootCaches() +
+  resetLoadedConfigCache()`.
+
+### Performance
+
+- **`vat audit` is faster on large scan targets.** Per-skill `projectRoot`
+  lookup now hits a module-level cache pre-warmed during the scan descent, so
+  large multi-skill audits no longer repeat filesystem walk-ups per skill.
+
+### Fixed
+
+- **Markdown links to directories now surface as `broken_file`.** Previously, links resolving to an existing directory (e.g., `/docs/`, `../`, or any href whose resolved path is a directory rather than a file) silently passed validation. They now emit `broken_file` with `Link target is a directory: <path>` and a suggestion to link to a file inside the directory.
+
+- **Leading-`/` links no longer false-flag as path-traversal escapes when the project root traverses a symlink.** `isWithinProject` now canonicalizes both sides of the within-check symmetrically (via `realpathSync`). Previously, when `projectRoot` was a symlinked path — common on macOS (`/tmp` → `/private/tmp`), bind mounts, and CI containers — a legitimate `/foo.md` resolution to `projectRoot/foo.md` was incorrectly reported as `absolute_escapes_root` because only the file side was realpath'd. The same fix also corrects the latent identical bug in the pre-existing gitignore-safety gate of `validateLocalFile`.
+
+- **`vat claude plugin install` post-install hints now point to the correct Claude Code slash command.** Both the standard and `--dev` install paths previously suggested `/reload-skills`, which is not a registered Claude Code CLI command — the real one is `/reload-plugins`. Docs (`packages/cli/docs/skills.md`, `docs/guides/distributing-vat-skills.md`, plugin READMEs, `vat-example-cat-agents` distribution doc) updated to match.
+
+- **`vat resources validate` no longer floods stderr with `unknown format
+  "uri-reference" ignored` warnings.** Ajv's default vocabulary doesn't
+  include URI-family formats; with `format: uri-reference` first-class in
+  frontmatter, the validator used to log one warning per occurrence (often 20+
+  per validate run). The validator now registers `ajv-formats` against its
+  Ajv instance, which silences the warnings without changing semantics — VAT's
+  own walker validates URI-ref hrefs against `resolveLocalHref`, not Ajv's
+  format definitions. Adopter-surfaced cleanup.
+
 ## [0.1.37] - 2026-05-16
 
 ### Fixed

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "license": "MIT",
   "name": "vibe-agent-toolkit",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "author": {
     "name": "vibe-agent-toolkit contributors"
   },

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-adoption-and-configuration/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: vat-adoption-and-configuration
-description: Use when starting a new VAT project, adding VAT to an existing repo, or orienting to `vibe-agent-toolkit.config.yaml`. Covers project setup, repo structure, package.json wiring, vibe-validate integration, and the npm postinstall hook.
+description: Use when starting a new VAT project, adding VAT to an existing
+  repo, or orienting to `vibe-agent-toolkit.config.yaml`. Covers project setup,
+  repo structure, package.json wiring, vibe-validate integration, and the npm
+  postinstall hook.
 ---
 
 # VAT Adoption and Configuration

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-agent-authoring/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: vat-agent-authoring
-description: Use when authoring TypeScript portable agents — agent archetypes, agent.yaml, result envelopes, orchestration patterns, and runtime adapters (Vercel/LangChain/OpenAI/Claude Agent SDK). Paired with vat-skill-authoring for the SKILL.md side.
+description: Use when authoring TypeScript portable agents — agent archetypes,
+  agent.yaml, result envelopes, orchestration patterns, and runtime adapters
+  (Vercel/LangChain/OpenAI/Claude Agent SDK). Paired with vat-skill-authoring
+  for the SKILL.md side.
 ---
 
 # VAT Agent Authoring: Archetypes, Envelopes, Orchestration

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-audit/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: vat-audit
-description: Use when running vat audit to validate Claude plugins, agent skills, or marketplaces. Covers the audit command, --compat flag for surface compatibility analysis, --exclude for noise filtering, and interpreting audit output.
+description: Use when running vat audit to validate Claude plugins, agent
+  skills, or marketplaces. Covers the audit command, --compat flag for surface
+  compatibility analysis, --exclude for noise filtering, and interpreting audit
+  output.
 ---
 
 # VAT Audit: Validating Plugins, Skills & Marketplaces

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-enterprise-org/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: vat-enterprise-org
-description: Use for Anthropic Enterprise/Team org administration via the Admin API — user management, API-key auditing, cost/usage reporting, workspace admin, and enterprise skill distribution. Requires ANTHROPIC_ADMIN_API_KEY.
+description: Use for Anthropic Enterprise/Team org administration via the Admin
+  API — user management, API-key auditing, cost/usage reporting, workspace
+  admin, and enterprise skill distribution. Requires ANTHROPIC_ADMIN_API_KEY.
 ---
 
 # Claude Org Administration

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-knowledge-resources/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: vat-knowledge-resources
-description: Use when working with VAT resource collections, per-directory frontmatter schema validation, link validation, or the vat resources command. Covers collection configuration, schema mapping, and validation modes.
+description: Use when working with VAT resource collections, per-directory
+  frontmatter schema validation, link validation, or the vat resources command.
+  Covers collection configuration, schema mapping, and validation modes.
 ---
 
 # VAT Resources: Collections & Frontmatter Validation
@@ -111,6 +113,46 @@ const PrdFrontmatter = z.object({
 
 **Tip:** `format` is advisory in JSON Schema; pair it with a `pattern` regex when you also need parse-time rejection of invalid inputs.
 
+## URI-references in frontmatter
+
+VAT validates frontmatter fields whose schema position has `format: uri-reference`
+(or `uri`, `iri-reference`, `iri`) against the same rules as body links:
+
+- Leading-`/` is RFC 3986 §4.2 absolute-path reference — resolved against
+  the project root. Same semantics as body links.
+- Anchor fragments and external URLs are accepted; broken local refs error.
+- Inline comments on URI-ref fields are **preserved** when any tool rewrites
+  the file via `openFrontmatter` (VAT packager, hand-rolled adopter scripts).
+
+Example:
+
+```yaml
+---
+parent_spec: /docs/specs/foo.md  # the spec this one supersedes
+adrs-cited:
+  - /docs/adrs/0007-storage.md  # primary reference
+  - /docs/adrs/0011-snapshot.md  # impacted by storage choice
+---
+```
+
+Schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "parent_spec": { "type": "string", "format": "uri-reference" },
+    "adrs-cited": {
+      "type": "array",
+      "items": { "type": "string", "format": "uri-reference" }
+    }
+  }
+}
+```
+
+For tools that **modify** frontmatter (not just validate it), see
+[[markdown-rewriting]].
+
 ## Validation Output
 
 ```yaml

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-rag/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: vat-rag
-description: Use when running `vat rag index` / `vat rag query` or configuring RAG for agent context — covers the CLI commands, native embedding providers and vector store support, chunking, custom metadata, and extension points for adding new backends.
+description: Use when running `vat rag index` / `vat rag query` or configuring
+  RAG for agent context — covers the CLI commands, native embedding providers
+  and vector store support, chunking, custom metadata, and extension points for
+  adding new backends.
 ---
 
 # VAT RAG: Indexing and Querying Markdown with Native Providers

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-skill-authoring/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: vat-skill-authoring
-description: Use when authoring or revising a SKILL.md file — frontmatter, body structure, references, packagingOptions (linkFollowDepth, excludeReferencesFromBundle), and validation overrides. Paired with vat-skill-review for pre-publication checks.
+description: Use when authoring or revising a SKILL.md file — frontmatter, body
+  structure, references, packagingOptions (linkFollowDepth,
+  excludeReferencesFromBundle), and validation overrides. Paired with
+  vat-skill-review for pre-publication checks.
 ---
 
 # VAT Skill Authoring: SKILL.md Structure and Packaging
@@ -34,6 +37,29 @@ Best practices for `description`:
 - Write in third person. First-person ("I can...") and conversational second-person ("You can use...") fire `SKILL_DESCRIPTION_WRONG_PERSON`.
 - Keep under 250 characters so the Claude Code `/skills` listing doesn't truncate the tail (target ≤200 for safety, ≤130 if shipping a large skill collection). The hard schema limit is 1024.
 
+## Cross-document references in SKILL.md frontmatter
+
+When SKILL.md frontmatter references other documents (parent specs, ADRs,
+related skills), use **leading-`/`** URI-references:
+
+```yaml
+---
+parent_spec: /docs/specs/foo.md
+related-skills:
+  - /packages/foo/resources/skills/bar/SKILL.md
+---
+```
+
+These resolve against the project root per RFC 3986 §4.2 (same rule VAT
+applies to body links). Source-relative paths (`../../docs/foo.md`) also
+work but are fragile when skills move.
+
+If a tool needs to programmatically rewrite these references — e.g., when
+moving a file — load [[markdown-rewriting]] for the canonical pattern.
+Never use `gray-matter`, `front-matter`, or `js-yaml` directly for SKILL.md
+edits; they silently drop frontmatter comments. ESLint enforces this for
+VAT-internal code.
+
 ## Body Structure
 
 - Lead with a short orientation paragraph: what the skill owns and when to reach for it.

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-skill-distribution/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: vat-skill-distribution
-description: Use when setting up `vat build`, configuring plugin distribution (marketplace, plugins, managed settings), npm publishing with postinstall hooks, or `vat verify` — the full pipeline from skill source to installed plugin.
+description: Use when setting up `vat build`, configuring plugin distribution
+  (marketplace, plugins, managed settings), npm publishing with postinstall
+  hooks, or `vat verify` — the full pipeline from skill source to installed
+  plugin.
 ---
 
 # VAT Distribution: Build, Publish & Install
@@ -468,4 +471,4 @@ everything (minus `skills/` and `.claude-plugin/`), merges author `plugin.json`
 VAT-owned identity fields, and applies any `files[]` mappings for artifacts built
 outside the plugin dir.
 
-See [docs/guides/marketplace-distribution.md](resources/marketplace-distribution.md) section "Full-plugin authoring".
+See [docs/guides/marketplace-distribution.md]() section "Full-plugin authoring".

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vat-skill-review/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: vat-skill-review
-description: Use when reviewing a skill before publication or running `vat skill review`. Pre-publication quality checklist grouped into general (all skills) and CLI-backed items, tied to VAT validation codes and Anthropic's skill-authoring best practices.
+description: Use when reviewing a skill before publication or running `vat skill
+  review`. Pre-publication quality checklist grouped into general (all skills)
+  and CLI-backed items, tied to VAT validation codes and Anthropic's
+  skill-authoring best practices.
 ---
 
 # Skill Quality Checklist (vat skill review)

package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vibe-agent-toolkit/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: vibe-agent-toolkit
-description: Use when starting VAT work or deciding which VAT sub-skill applies. Router that points at sub-skills for adoption, skill/agent authoring, audit, distribution, RAG, knowledge resources, skill review, and enterprise org admin.
+description: Use when starting VAT work or deciding which VAT sub-skill applies.
+  Router that points at sub-skills for adoption, skill/agent authoring, audit,
+  distribution, RAG, knowledge resources, skill review, and enterprise org
+  admin.
 ---
 
 # Vibe Agent Toolkit
@@ -38,6 +41,7 @@ Poor fits:
 | `vat rag index` / `vat rag query`, embedding providers, vector stores, chunking | `vibe-agent-toolkit:vat-rag` |
 | Pre-publication quality review, `vat skill review`, validation-code triage | `vibe-agent-toolkit:vat-skill-review` |
 | Anthropic Admin API: org users, cost/usage, workspace skills, `ANTHROPIC_ADMIN_API_KEY` | `vibe-agent-toolkit:vat-enterprise-org` |
+| Programmatic markdown/frontmatter edits — moving files, updating references, schema-evolution migrations; comment-preserving FrontmatterEditor + rewriteBodyLinks | `vibe-agent-toolkit:markdown-rewriting` |
 
 ## CLI Surface at a Glance
 

package/dist/generated/resources/skills/SKILL.js

@@ -7,7 +7,7 @@ export const meta = {
   description: "Use when starting VAT work or deciding which VAT sub-skill applies. Router that points at sub-skills for adoption, skill/agent authoring, audit, distribution, RAG, knowledge resources, skill review, and enterprise org admin."
 };
 
-export const text = "\n# Vibe Agent Toolkit\n\n**Vibe Agent Toolkit (VAT)** is a modular toolkit for building, packaging, and distributing portable AI agents and skills that work across multiple Claude surfaces and adjacent frameworks. Write skill or agent content once; VAT handles validation, packaging, plugin/marketplace layout, and npm publishing.\n\nThis is a router skill. Load the sibling sub-skill that matches the work you\'re doing — each sub-skill owns one slice of VAT\'s surface and is designed to be pulled in on demand.\n\n## When to Use VAT\n\nGood fits:\n\n- Publishing a Claude skill or plugin to npm with a proper marketplace layout\n- Multi-runtime agent projects (Vercel AI SDK, LangChain, OpenAI, Claude Agent SDK)\n- Validating plugins / skills / marketplaces with \`vat audit\` before shipping\n- Enforcing frontmatter schemas across large markdown corpora\n- Wiring RAG indexing into an agent project\n\nPoor fits:\n\n- Simple one-off scripts where the framework is already decided\n- Non-TypeScript/JavaScript projects\n- Cases where you need deep framework-specific features with no reuse goal\n\n## Picking a Sub-skill\n\n| If you\'re working on... | Load |\n|---|---|\n| New project setup, \`vibe-agent-toolkit.config.yaml\` orientation, repo structure, vibe-validate integration, npm postinstall | \`vibe-agent-toolkit:vat-adoption-and-configuration\` |\n| Writing or revising a SKILL.md — frontmatter, body, references, packagingOptions, validation overrides | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| TypeScript agent archetypes, \`agent.yaml\`, result envelopes, orchestration, runtime adapters | \`vibe-agent-toolkit:vat-agent-authoring\` |\n| \`vat audit\` on plugins, marketplaces, skills, or settings — including \`--compat\`, \`--exclude\`, \`--user\`, CI use | \`vibe-agent-toolkit:vat-audit\` |\n| Markdown collections, \`resources:\` config, frontmatter schema validation, \`vat resources validate\` | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`vat build\`, \`vat verify\`, plugin/marketplace layout, npm publishing, postinstall | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`vat rag index\` / \`vat rag query\`, embedding providers, vector stores, chunking | \`vibe-agent-toolkit:vat-rag\` |\n| Pre-publication quality review, \`vat skill review\`, validation-code triage | \`vibe-agent-toolkit:vat-skill-review\` |\n| Anthropic Admin API: org users, cost/usage, workspace skills, \`ANTHROPIC_ADMIN_API_KEY\` | \`vibe-agent-toolkit:vat-enterprise-org\` |\n\n## CLI Surface at a Glance\n\n\`\`\`bash\nvat --help                 # top-level help\nvat build                  # build all artifacts (skills → claude plugins)\nvat verify                 # validate all artifacts\nvat skills validate        # validate skill quality\nvat resources validate     # validate markdown collections\nvat audit                  # audit plugins/skills/marketplaces/settings\nvat rag index docs/        # index markdown for RAG\nvat skill review <path>    # pre-publication review\nvat claude org --help      # enterprise admin surface\n\`\`\`\n\nEach sub-skill covers its slice of the CLI in depth — don\'t memorize this table, load the sub-skill when you need detail.\n\n## Getting Help\n\n- \`vat --help\` and \`vat <group> --help --verbose\` for CLI depth\n- Repo docs: the VAT repository\'s \`docs/\` directory carries the full setup guide, architecture notes, and design references (not bundled with this plugin)\n- Contributor reference docs (debugging VAT, install architecture) live under \`docs/contributing/\` in the VAT repo\n";
+export const text = "\n# Vibe Agent Toolkit\n\n**Vibe Agent Toolkit (VAT)** is a modular toolkit for building, packaging, and distributing portable AI agents and skills that work across multiple Claude surfaces and adjacent frameworks. Write skill or agent content once; VAT handles validation, packaging, plugin/marketplace layout, and npm publishing.\n\nThis is a router skill. Load the sibling sub-skill that matches the work you\'re doing — each sub-skill owns one slice of VAT\'s surface and is designed to be pulled in on demand.\n\n## When to Use VAT\n\nGood fits:\n\n- Publishing a Claude skill or plugin to npm with a proper marketplace layout\n- Multi-runtime agent projects (Vercel AI SDK, LangChain, OpenAI, Claude Agent SDK)\n- Validating plugins / skills / marketplaces with \`vat audit\` before shipping\n- Enforcing frontmatter schemas across large markdown corpora\n- Wiring RAG indexing into an agent project\n\nPoor fits:\n\n- Simple one-off scripts where the framework is already decided\n- Non-TypeScript/JavaScript projects\n- Cases where you need deep framework-specific features with no reuse goal\n\n## Picking a Sub-skill\n\n| If you\'re working on... | Load |\n|---|---|\n| New project setup, \`vibe-agent-toolkit.config.yaml\` orientation, repo structure, vibe-validate integration, npm postinstall | \`vibe-agent-toolkit:vat-adoption-and-configuration\` |\n| Writing or revising a SKILL.md — frontmatter, body, references, packagingOptions, validation overrides | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| TypeScript agent archetypes, \`agent.yaml\`, result envelopes, orchestration, runtime adapters | \`vibe-agent-toolkit:vat-agent-authoring\` |\n| \`vat audit\` on plugins, marketplaces, skills, or settings — including \`--compat\`, \`--exclude\`, \`--user\`, CI use | \`vibe-agent-toolkit:vat-audit\` |\n| Markdown collections, \`resources:\` config, frontmatter schema validation, \`vat resources validate\` | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`vat build\`, \`vat verify\`, plugin/marketplace layout, npm publishing, postinstall | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`vat rag index\` / \`vat rag query\`, embedding providers, vector stores, chunking | \`vibe-agent-toolkit:vat-rag\` |\n| Pre-publication quality review, \`vat skill review\`, validation-code triage | \`vibe-agent-toolkit:vat-skill-review\` |\n| Anthropic Admin API: org users, cost/usage, workspace skills, \`ANTHROPIC_ADMIN_API_KEY\` | \`vibe-agent-toolkit:vat-enterprise-org\` |\n| Programmatic markdown/frontmatter edits — moving files, updating references, schema-evolution migrations; comment-preserving FrontmatterEditor + rewriteBodyLinks | \`vibe-agent-toolkit:markdown-rewriting\` |\n\n## CLI Surface at a Glance\n\n\`\`\`bash\nvat --help                 # top-level help\nvat build                  # build all artifacts (skills → claude plugins)\nvat verify                 # validate all artifacts\nvat skills validate        # validate skill quality\nvat resources validate     # validate markdown collections\nvat audit                  # audit plugins/skills/marketplaces/settings\nvat rag index docs/        # index markdown for RAG\nvat skill review <path>    # pre-publication review\nvat claude org --help      # enterprise admin surface\n\`\`\`\n\nEach sub-skill covers its slice of the CLI in depth — don\'t memorize this table, load the sub-skill when you need detail.\n\n## Getting Help\n\n- \`vat --help\` and \`vat <group> --help --verbose\` for CLI depth\n- Repo docs: the VAT repository\'s \`docs/\` directory carries the full setup guide, architecture notes, and design references (not bundled with this plugin)\n- Contributor reference docs (debugging VAT, install architecture) live under \`docs/contributing/\` in the VAT repo\n";
 
 export const fragments = {
   whenToUseVat: {
@@ -17,8 +17,8 @@ export const fragments = {
   },
   pickingASubSkill: {
     header: "## Picking a Sub-skill",
-    body: "| If you\'re working on... | Load |\n|---|---|\n| New project setup, \`vibe-agent-toolkit.config.yaml\` orientation, repo structure, vibe-validate integration, npm postinstall | \`vibe-agent-toolkit:vat-adoption-and-configuration\` |\n| Writing or revising a SKILL.md — frontmatter, body, references, packagingOptions, validation overrides | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| TypeScript agent archetypes, \`agent.yaml\`, result envelopes, orchestration, runtime adapters | \`vibe-agent-toolkit:vat-agent-authoring\` |\n| \`vat audit\` on plugins, marketplaces, skills, or settings — including \`--compat\`, \`--exclude\`, \`--user\`, CI use | \`vibe-agent-toolkit:vat-audit\` |\n| Markdown collections, \`resources:\` config, frontmatter schema validation, \`vat resources validate\` | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`vat build\`, \`vat verify\`, plugin/marketplace layout, npm publishing, postinstall | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`vat rag index\` / \`vat rag query\`, embedding providers, vector stores, chunking | \`vibe-agent-toolkit:vat-rag\` |\n| Pre-publication quality review, \`vat skill review\`, validation-code triage | \`vibe-agent-toolkit:vat-skill-review\` |\n| Anthropic Admin API: org users, cost/usage, workspace skills, \`ANTHROPIC_ADMIN_API_KEY\` | \`vibe-agent-toolkit:vat-enterprise-org\` |",
-    text: "## Picking a Sub-skill\n\n| If you\'re working on... | Load |\n|---|---|\n| New project setup, \`vibe-agent-toolkit.config.yaml\` orientation, repo structure, vibe-validate integration, npm postinstall | \`vibe-agent-toolkit:vat-adoption-and-configuration\` |\n| Writing or revising a SKILL.md — frontmatter, body, references, packagingOptions, validation overrides | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| TypeScript agent archetypes, \`agent.yaml\`, result envelopes, orchestration, runtime adapters | \`vibe-agent-toolkit:vat-agent-authoring\` |\n| \`vat audit\` on plugins, marketplaces, skills, or settings — including \`--compat\`, \`--exclude\`, \`--user\`, CI use | \`vibe-agent-toolkit:vat-audit\` |\n| Markdown collections, \`resources:\` config, frontmatter schema validation, \`vat resources validate\` | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`vat build\`, \`vat verify\`, plugin/marketplace layout, npm publishing, postinstall | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`vat rag index\` / \`vat rag query\`, embedding providers, vector stores, chunking | \`vibe-agent-toolkit:vat-rag\` |\n| Pre-publication quality review, \`vat skill review\`, validation-code triage | \`vibe-agent-toolkit:vat-skill-review\` |\n| Anthropic Admin API: org users, cost/usage, workspace skills, \`ANTHROPIC_ADMIN_API_KEY\` | \`vibe-agent-toolkit:vat-enterprise-org\` |"
+    body: "| If you\'re working on... | Load |\n|---|---|\n| New project setup, \`vibe-agent-toolkit.config.yaml\` orientation, repo structure, vibe-validate integration, npm postinstall | \`vibe-agent-toolkit:vat-adoption-and-configuration\` |\n| Writing or revising a SKILL.md — frontmatter, body, references, packagingOptions, validation overrides | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| TypeScript agent archetypes, \`agent.yaml\`, result envelopes, orchestration, runtime adapters | \`vibe-agent-toolkit:vat-agent-authoring\` |\n| \`vat audit\` on plugins, marketplaces, skills, or settings — including \`--compat\`, \`--exclude\`, \`--user\`, CI use | \`vibe-agent-toolkit:vat-audit\` |\n| Markdown collections, \`resources:\` config, frontmatter schema validation, \`vat resources validate\` | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`vat build\`, \`vat verify\`, plugin/marketplace layout, npm publishing, postinstall | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`vat rag index\` / \`vat rag query\`, embedding providers, vector stores, chunking | \`vibe-agent-toolkit:vat-rag\` |\n| Pre-publication quality review, \`vat skill review\`, validation-code triage | \`vibe-agent-toolkit:vat-skill-review\` |\n| Anthropic Admin API: org users, cost/usage, workspace skills, \`ANTHROPIC_ADMIN_API_KEY\` | \`vibe-agent-toolkit:vat-enterprise-org\` |\n| Programmatic markdown/frontmatter edits — moving files, updating references, schema-evolution migrations; comment-preserving FrontmatterEditor + rewriteBodyLinks | \`vibe-agent-toolkit:markdown-rewriting\` |",
+    text: "## Picking a Sub-skill\n\n| If you\'re working on... | Load |\n|---|---|\n| New project setup, \`vibe-agent-toolkit.config.yaml\` orientation, repo structure, vibe-validate integration, npm postinstall | \`vibe-agent-toolkit:vat-adoption-and-configuration\` |\n| Writing or revising a SKILL.md — frontmatter, body, references, packagingOptions, validation overrides | \`vibe-agent-toolkit:vat-skill-authoring\` |\n| TypeScript agent archetypes, \`agent.yaml\`, result envelopes, orchestration, runtime adapters | \`vibe-agent-toolkit:vat-agent-authoring\` |\n| \`vat audit\` on plugins, marketplaces, skills, or settings — including \`--compat\`, \`--exclude\`, \`--user\`, CI use | \`vibe-agent-toolkit:vat-audit\` |\n| Markdown collections, \`resources:\` config, frontmatter schema validation, \`vat resources validate\` | \`vibe-agent-toolkit:vat-knowledge-resources\` |\n| \`vat build\`, \`vat verify\`, plugin/marketplace layout, npm publishing, postinstall | \`vibe-agent-toolkit:vat-skill-distribution\` |\n| \`vat rag index\` / \`vat rag query\`, embedding providers, vector stores, chunking | \`vibe-agent-toolkit:vat-rag\` |\n| Pre-publication quality review, \`vat skill review\`, validation-code triage | \`vibe-agent-toolkit:vat-skill-review\` |\n| Anthropic Admin API: org users, cost/usage, workspace skills, \`ANTHROPIC_ADMIN_API_KEY\` | \`vibe-agent-toolkit:vat-enterprise-org\` |\n| Programmatic markdown/frontmatter edits — moving files, updating references, schema-evolution migrations; comment-preserving FrontmatterEditor + rewriteBodyLinks | \`vibe-agent-toolkit:markdown-rewriting\` |"
   },
   cliSurfaceAtAGlance: {
     header: "## CLI Surface at a Glance",

package/dist/generated/resources/skills/markdown-rewriting.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Generated TypeScript declarations - DO NOT EDIT
+ */
+
+export interface Fragment {
+  readonly header: string;
+  readonly body: string;
+  readonly text: string;
+}
+
+export const meta: {
+  readonly name: string;
+  readonly description: string;
+};
+
+export const text: string;
+
+export const fragments: {
+  readonly theRule: Fragment;
+  readonly antiPatterns-DoNotUseThese: Fragment;
+  readonly canonicalRecipeMoveAFileAndUpdateReferences: Fragment;
+  readonly whenYouHaveAJsonSchemaForTheFrontmatter: Fragment;
+  readonly bulkMigrationManyFilesAtOnce: Fragment;
+  readonly whatsPreservedWhatIsnt: Fragment;
+  readonly crossLinks: Fragment;
+};
+
+export type FragmentName = keyof typeof fragments;

package/dist/generated/resources/skills/markdown-rewriting.js

@@ -0,0 +1,48 @@
+/**
+ * Generated from markdown file - DO NOT EDIT
+ */
+
+export const meta = {
+  name: "markdown-rewriting",
+  description: "Use when programmatically editing markdown or frontmatter — moving files, updating references, batch-renaming, schema-evolution migrations. Steers to comment-preserving FrontmatterEditor + rewriteBodyLinks; away from gray-matter/js-yaml/regex."
+};
+
+export const text = "\n# Editing markdown safely\n\nWhen you write code that opens a markdown file, mutates the frontmatter or\nbody, and writes it back, you have ONE job that\'s easy to get wrong: keep\nthe file\'s content stable except for the intentional change. Lose comments,\nblank lines, anchors, or quoting style, and every iteration degrades the\ndocs.\n\nVAT ships canonical primitives for this. Use them.\n\n## The rule\n\nFor **any** programmatic markdown edit, use \`@vibe-agent-toolkit/resources\`:\n\n- \`openFrontmatter(markdown)\` — round-trip-safe editor. Comments,\n  blank lines, EOL, YAML style all survive read → mutate → write. Exposes\n  \`.body\` (settable), \`.get(path)\`, \`.set(path, value)\`, \`.setArrayItem\`,\n  \`.appendArrayItem\`, \`.delete(path)\`, \`.isDirty()\`, and \`.toString()\`.\n  The underlying \`yaml.Document\` is intentionally not exposed.\n- \`rewriteBodyLinks(body, rewriteHref)\` — walk inline + reference-style\n  body links with a per-href callback.\n- \`rewriteFrontmatterFieldsAtPaths(editor, paths, rewriteHref)\` — rewrite\n  specific frontmatter fields you know by name. Path syntax: \`\'name\'\`\n  (top-level), \`\'name[]\'\` (array of strings — rewrite each item),\n  \`\'meta.parent\'\` (nested), \`\'meta.refs[]\'\` (nested array).\n- \`rewriteFrontmatterUriReferencesFromSchema(editor, schema, rewriteHref)\` —\n  walk every schema-annotated URI-reference field automatically.\n\n**The \`rewriteHref\` callback contract.** Return the new href, or return the\ninput string unchanged to skip that link. Anchor-only hrefs (\`#section\`),\nexternal URLs, and refs that don\'t match your rule should all return as-is.\nThe callback receives only the href string — there is no field-path\ncontext. When rules differ per field (e.g. \`parent_spec\` strict; \`related[]\`\npermissive), use \`rewriteFrontmatterFieldsAtPaths\` with one call per path\ngroup rather than the schema-driven helper.\n\n**The primitives are pure (no I/O).** Read and write with whatever FS API\nfits — \`fs/promises\`, \`fs-extra\`, streams, anything. The recipes below\nuse \`readFileSync\` / \`writeFileSync\` for clarity; production code is\nfree to use async equivalents.\n\n## Anti-patterns — do NOT use these\n\n- ❌ \`gray-matter\` — drops comments. Already banned by ESLint.\n- ❌ \`front-matter\` — drops comments. Already banned by ESLint.\n- ❌ \`js-yaml\` — drops comments AND has YAML 1.1 quirks (ISO date\n  promotion). Already banned by ESLint.\n- ❌ Raw \`yaml.parse(text) → mutate → yaml.stringify(obj)\` — drops comments\n  even with eemeli \`yaml\`. Use \`openFrontmatter\` for the round-trip case.\n- ❌ Regex on \`---\` fences to extract or replace frontmatter — fragile,\n  loses style.\n- ❌ Naive \`body.replaceAll(\'/docs/old/\', \'/docs/new/\')\` — matches inside\n  code blocks, inline code spans, attribute values, etc. Use\n  \`rewriteBodyLinks\` so only actual markdown links are rewritten.\n\n## Canonical recipe: move a file and update references\n\n\`\`\`typescript\nimport {\n  openFrontmatter,\n  rewriteBodyLinks,\n  rewriteFrontmatterFieldsAtPaths,\n} from \'@vibe-agent-toolkit/resources\';\nimport { readFileSync, writeFileSync } from \'node:fs\';\n\nconst rewriteHref = (href: string): string =>\n  href.replace(\'/docs/old/\', \'/docs/new/\');\n\nconst filePath = \'docs/specs/foo.md\';\nconst editor = openFrontmatter(readFileSync(filePath, \'utf8\'));\neditor.body = rewriteBodyLinks(editor.body, rewriteHref);\nrewriteFrontmatterFieldsAtPaths(\n  editor,\n  [\'parent_spec\', \'adrs-cited[]\', \'related-specs[]\'],\n  rewriteHref,\n);\nwriteFileSync(filePath, editor.toString());\n\`\`\`\n\n## When you have a JSON Schema for the frontmatter\n\nIf the file\'s frontmatter is governed by a schema (collection-validated, or\njust a hand-written schema you trust), use the schema-driven helper\ninstead of listing field paths by hand. **Compose it with \`rewriteBodyLinks\`\nto cover the body too** — most rewrites (file moves, folder renames) want\nboth sides updated:\n\n\`\`\`typescript\nimport { readFileSync, writeFileSync } from \'node:fs\';\nimport {\n  openFrontmatter,\n  rewriteBodyLinks,\n  rewriteFrontmatterUriReferencesFromSchema,\n} from \'@vibe-agent-toolkit/resources\';\n\nconst rewriteHref = (href: string): string =>\n  href.replace(\'/docs/specs/\', \'/docs/architecture/\');\n\nconst schema = JSON.parse(readFileSync(\'schemas/spec.schema.json\', \'utf8\'));\nconst filePath = \'docs/specs/foo.md\';\nconst editor = openFrontmatter(readFileSync(filePath, \'utf8\'));\n\neditor.body = rewriteBodyLinks(editor.body, rewriteHref);\nrewriteFrontmatterUriReferencesFromSchema(editor, schema, rewriteHref);\n\nwriteFileSync(filePath, editor.toString());\n\`\`\`\n\nThe schema-driven call walks every field whose schema position has\n\`format: uri-reference\` (or \`uri\`, \`iri-reference\`, \`iri\`) and rewrites\nthe value via your callback. Fields outside the URI-family are not\ntouched. **Templated-URI formats are intentionally excluded** —\n\`uri-template\` (RFC 6570 templates with \`{var}\` placeholders) and\nJSON-Pointer-derived formats aren\'t file references and don\'t fit the\nrewrite shape.\n\n**Frontmatter-only**: drop the \`rewriteBodyLinks\` line — the rest\nis identical.\n\nAfter running, diff the file (\`git diff <path>\`) to confirm the rewrite\ntouched only the fields and links you expected.\n\n## Bulk migration: many files at once\n\nWhen the rewrite spans dozens or thousands of files (folder rename,\nschema-evolution migration, citation cleanup), the natural shape is\nglob + iterate + dry-run + \`isDirty()\` gate. Pattern:\n\n\`\`\`typescript\nimport { readFileSync, writeFileSync } from \'node:fs\';\nimport { globSync } from \'glob\';  // or \`node:fs\`\'s glob, or fast-glob\nimport {\n  openFrontmatter,\n  rewriteBodyLinks,\n  rewriteFrontmatterUriReferencesFromSchema,\n} from \'@vibe-agent-toolkit/resources\';\n\nconst DRY_RUN = process.env[\'DRY_RUN\'] !== \'false\';\nconst rewriteHref = (href: string): string =>\n  href.replace(\'/docs/specs/\', \'/docs/architecture/\');\n\nconst schema = JSON.parse(readFileSync(\'schemas/spec.schema.json\', \'utf8\'));\nconst files = globSync(\'docs/**/*.md\');\n\nlet changed = 0;\nlet unchanged = 0;\nfor (const filePath of files) {\n  const original = readFileSync(filePath, \'utf8\');\n  const editor = openFrontmatter(original);\n\n  editor.body = rewriteBodyLinks(editor.body, rewriteHref);\n  rewriteFrontmatterUriReferencesFromSchema(editor, schema, rewriteHref);\n\n  // Skip files where nothing material changed. Avoids the no-op churn\n  // described in §\"What\'s preserved, what isn\'t\".\n  const next = editor.toString();\n  if (!editor.isDirty() || next === original) {\n    unchanged++;\n    continue;\n  }\n\n  if (DRY_RUN) {\n    console.log(\`would update ${filePath}\`);\n  } else {\n    writeFileSync(filePath, next);\n  }\n  changed++;\n}\n\nconsole.log(\`${DRY_RUN ? \'DRY RUN: \' : \'\'}${changed} changed, ${unchanged} unchanged\`);\n\`\`\`\n\n**Recommended workflow for bulk runs:**\n\n1. **Sentinel-first.** Run on a single representative file first\n   (\`globSync\` pattern that matches exactly one path). Eyeball the diff.\n2. **Dry-run the full set.** \`DRY_RUN=true\` lists every file the script\n   would touch. Spot-check at least 3 entries before going wet.\n3. **Iterate.** Adjust the callback or schema until the dry-run plan\n   matches your intent.\n4. **Run wet.** \`DRY_RUN=false\`. Then run your project\'s link validator\n   (\`vat resources validate\`, link-check CI, etc.) on the corpus before\n   committing — the rewrite is reversible via \`git checkout\` if any\n   targets are wrong.\n\n**Delegating to a subagent.** Bulk rewrites are good subagent work, but\nbrief them with the same three guardrails: provide the exact callback\nrule, mandate dry-run first, and ask for a structured report (counts\nof files changed/unchanged, a sample of 3 before/after diffs). Without\nthose guardrails, a subagent can silently produce a thousand-file diff\nthat\'s wrong in a subtle way and only catchable on careful review.\n\n## What\'s preserved, what isn\'t\n\n\`openFrontmatter\` inherits its preservation guarantees from \`yaml.Document\`\n(eemeli). Read-only round-trip (no mutations) is byte-identical. Once you\nmutate, the frontmatter section is re-emitted by \`yaml.Document\` and a few\nthings normalize:\n\n| Behavior | Preserved on mutation? |\n|---|---|\n| Inline comment **text** (\`# comment\`) | ✅ |\n| Inline comment **leading whitespace** (\`  #\` vs \` #\`) | ❌ collapsed to one space |\n| Leading comments on keys | ✅ (best-effort; comment-attachment is yaml.Document\'s call) |\n| Comments on individual array items | ✅ |\n| Block scalar style (\`|\`, \`>\`, \`|-\`, \`>+\`) | ✅ |\n| Quoting style (plain / single / double) | ✅ |\n| Blank lines between blocks | ✅ |\n| Key ordering | ✅ |\n| EOL (LF or CRLF) | ✅ (detected from first line break) |\n| Anchors and aliases | ✅ on round-trip; mutating them follows \`yaml.Document\` semantics, not ours |\n\n**Consequence:** even a \"no-op\" rewrite (callback returns the input\nunchanged) re-emits frontmatter and can collapse \`  #\` → \` #\` on every\nline that has an inline comment. The change is harmless but shows up in\n\`git diff\`. Two ways to skip the write in this case:\n\n- **\`editor.isDirty()\`** — returns \`true\` if any mutator was called or\n  \`body\` was reassigned to a different string. Cheap, no string compare,\n  but flips on any mutator call even when the value didn\'t change\n  (e.g. \`set(\'foo\', sameValue)\`). Fine for most workflows.\n- **Byte-level dirty check** — \`editor.toString() !== originalText\`. Catches\n  the no-op-rewrite case exactly; one extra serialize per file. Use this\n  when you must produce zero diff on no-op runs.\n\nThe bulk-migration recipe above combines both: \`isDirty()\` as the cheap\nshort-circuit, then a byte compare to filter out comment-whitespace-only\ndeltas.\n\n## Cross-links\n\n- \`vat-knowledge-resources\` — how to validate URI-references in\n  frontmatter against a collection schema.\n- \`vat-skill-authoring\` — when to use leading-\`/\` (project-root-relative)\n  URI-refs in SKILL.md frontmatter.\n";
+
+export const fragments = {
+  theRule: {
+    header: "## The rule",
+    body: "For **any** programmatic markdown edit, use \`@vibe-agent-toolkit/resources\`:\n\n- \`openFrontmatter(markdown)\` — round-trip-safe editor. Comments,\n  blank lines, EOL, YAML style all survive read → mutate → write. Exposes\n  \`.body\` (settable), \`.get(path)\`, \`.set(path, value)\`, \`.setArrayItem\`,\n  \`.appendArrayItem\`, \`.delete(path)\`, \`.isDirty()\`, and \`.toString()\`.\n  The underlying \`yaml.Document\` is intentionally not exposed.\n- \`rewriteBodyLinks(body, rewriteHref)\` — walk inline + reference-style\n  body links with a per-href callback.\n- \`rewriteFrontmatterFieldsAtPaths(editor, paths, rewriteHref)\` — rewrite\n  specific frontmatter fields you know by name. Path syntax: \`\'name\'\`\n  (top-level), \`\'name[]\'\` (array of strings — rewrite each item),\n  \`\'meta.parent\'\` (nested), \`\'meta.refs[]\'\` (nested array).\n- \`rewriteFrontmatterUriReferencesFromSchema(editor, schema, rewriteHref)\` —\n  walk every schema-annotated URI-reference field automatically.\n\n**The \`rewriteHref\` callback contract.** Return the new href, or return the\ninput string unchanged to skip that link. Anchor-only hrefs (\`#section\`),\nexternal URLs, and refs that don\'t match your rule should all return as-is.\nThe callback receives only the href string — there is no field-path\ncontext. When rules differ per field (e.g. \`parent_spec\` strict; \`related[]\`\npermissive), use \`rewriteFrontmatterFieldsAtPaths\` with one call per path\ngroup rather than the schema-driven helper.\n\n**The primitives are pure (no I/O).** Read and write with whatever FS API\nfits — \`fs/promises\`, \`fs-extra\`, streams, anything. The recipes below\nuse \`readFileSync\` / \`writeFileSync\` for clarity; production code is\nfree to use async equivalents.",
+    text: "## The rule\n\nFor **any** programmatic markdown edit, use \`@vibe-agent-toolkit/resources\`:\n\n- \`openFrontmatter(markdown)\` — round-trip-safe editor. Comments,\n  blank lines, EOL, YAML style all survive read → mutate → write. Exposes\n  \`.body\` (settable), \`.get(path)\`, \`.set(path, value)\`, \`.setArrayItem\`,\n  \`.appendArrayItem\`, \`.delete(path)\`, \`.isDirty()\`, and \`.toString()\`.\n  The underlying \`yaml.Document\` is intentionally not exposed.\n- \`rewriteBodyLinks(body, rewriteHref)\` — walk inline + reference-style\n  body links with a per-href callback.\n- \`rewriteFrontmatterFieldsAtPaths(editor, paths, rewriteHref)\` — rewrite\n  specific frontmatter fields you know by name. Path syntax: \`\'name\'\`\n  (top-level), \`\'name[]\'\` (array of strings — rewrite each item),\n  \`\'meta.parent\'\` (nested), \`\'meta.refs[]\'\` (nested array).\n- \`rewriteFrontmatterUriReferencesFromSchema(editor, schema, rewriteHref)\` —\n  walk every schema-annotated URI-reference field automatically.\n\n**The \`rewriteHref\` callback contract.** Return the new href, or return the\ninput string unchanged to skip that link. Anchor-only hrefs (\`#section\`),\nexternal URLs, and refs that don\'t match your rule should all return as-is.\nThe callback receives only the href string — there is no field-path\ncontext. When rules differ per field (e.g. \`parent_spec\` strict; \`related[]\`\npermissive), use \`rewriteFrontmatterFieldsAtPaths\` with one call per path\ngroup rather than the schema-driven helper.\n\n**The primitives are pure (no I/O).** Read and write with whatever FS API\nfits — \`fs/promises\`, \`fs-extra\`, streams, anything. The recipes below\nuse \`readFileSync\` / \`writeFileSync\` for clarity; production code is\nfree to use async equivalents."
+  },
+  antiPatterns-DoNotUseThese: {
+    header: "## Anti-patterns — do NOT use these",
+    body: "- ❌ \`gray-matter\` — drops comments. Already banned by ESLint.\n- ❌ \`front-matter\` — drops comments. Already banned by ESLint.\n- ❌ \`js-yaml\` — drops comments AND has YAML 1.1 quirks (ISO date\n  promotion). Already banned by ESLint.\n- ❌ Raw \`yaml.parse(text) → mutate → yaml.stringify(obj)\` — drops comments\n  even with eemeli \`yaml\`. Use \`openFrontmatter\` for the round-trip case.\n- ❌ Regex on \`---\` fences to extract or replace frontmatter — fragile,\n  loses style.\n- ❌ Naive \`body.replaceAll(\'/docs/old/\', \'/docs/new/\')\` — matches inside\n  code blocks, inline code spans, attribute values, etc. Use\n  \`rewriteBodyLinks\` so only actual markdown links are rewritten.",
+    text: "## Anti-patterns — do NOT use these\n\n- ❌ \`gray-matter\` — drops comments. Already banned by ESLint.\n- ❌ \`front-matter\` — drops comments. Already banned by ESLint.\n- ❌ \`js-yaml\` — drops comments AND has YAML 1.1 quirks (ISO date\n  promotion). Already banned by ESLint.\n- ❌ Raw \`yaml.parse(text) → mutate → yaml.stringify(obj)\` — drops comments\n  even with eemeli \`yaml\`. Use \`openFrontmatter\` for the round-trip case.\n- ❌ Regex on \`---\` fences to extract or replace frontmatter — fragile,\n  loses style.\n- ❌ Naive \`body.replaceAll(\'/docs/old/\', \'/docs/new/\')\` — matches inside\n  code blocks, inline code spans, attribute values, etc. Use\n  \`rewriteBodyLinks\` so only actual markdown links are rewritten."
+  },
+  canonicalRecipeMoveAFileAndUpdateReferences: {
+    header: "## Canonical recipe: move a file and update references",
+    body: "\`\`\`typescript\nimport {\n  openFrontmatter,\n  rewriteBodyLinks,\n  rewriteFrontmatterFieldsAtPaths,\n} from \'@vibe-agent-toolkit/resources\';\nimport { readFileSync, writeFileSync } from \'node:fs\';\n\nconst rewriteHref = (href: string): string =>\n  href.replace(\'/docs/old/\', \'/docs/new/\');\n\nconst filePath = \'docs/specs/foo.md\';\nconst editor = openFrontmatter(readFileSync(filePath, \'utf8\'));\neditor.body = rewriteBodyLinks(editor.body, rewriteHref);\nrewriteFrontmatterFieldsAtPaths(\n  editor,\n  [\'parent_spec\', \'adrs-cited[]\', \'related-specs[]\'],\n  rewriteHref,\n);\nwriteFileSync(filePath, editor.toString());\n\`\`\`",
+    text: "## Canonical recipe: move a file and update references\n\n\`\`\`typescript\nimport {\n  openFrontmatter,\n  rewriteBodyLinks,\n  rewriteFrontmatterFieldsAtPaths,\n} from \'@vibe-agent-toolkit/resources\';\nimport { readFileSync, writeFileSync } from \'node:fs\';\n\nconst rewriteHref = (href: string): string =>\n  href.replace(\'/docs/old/\', \'/docs/new/\');\n\nconst filePath = \'docs/specs/foo.md\';\nconst editor = openFrontmatter(readFileSync(filePath, \'utf8\'));\neditor.body = rewriteBodyLinks(editor.body, rewriteHref);\nrewriteFrontmatterFieldsAtPaths(\n  editor,\n  [\'parent_spec\', \'adrs-cited[]\', \'related-specs[]\'],\n  rewriteHref,\n);\nwriteFileSync(filePath, editor.toString());\n\`\`\`"
+  },
+  whenYouHaveAJsonSchemaForTheFrontmatter: {
+    header: "## When you have a JSON Schema for the frontmatter",
+    body: "If the file\'s frontmatter is governed by a schema (collection-validated, or\njust a hand-written schema you trust), use the schema-driven helper\ninstead of listing field paths by hand. **Compose it with \`rewriteBodyLinks\`\nto cover the body too** — most rewrites (file moves, folder renames) want\nboth sides updated:\n\n\`\`\`typescript\nimport { readFileSync, writeFileSync } from \'node:fs\';\nimport {\n  openFrontmatter,\n  rewriteBodyLinks,\n  rewriteFrontmatterUriReferencesFromSchema,\n} from \'@vibe-agent-toolkit/resources\';\n\nconst rewriteHref = (href: string): string =>\n  href.replace(\'/docs/specs/\', \'/docs/architecture/\');\n\nconst schema = JSON.parse(readFileSync(\'schemas/spec.schema.json\', \'utf8\'));\nconst filePath = \'docs/specs/foo.md\';\nconst editor = openFrontmatter(readFileSync(filePath, \'utf8\'));\n\neditor.body = rewriteBodyLinks(editor.body, rewriteHref);\nrewriteFrontmatterUriReferencesFromSchema(editor, schema, rewriteHref);\n\nwriteFileSync(filePath, editor.toString());\n\`\`\`\n\nThe schema-driven call walks every field whose schema position has\n\`format: uri-reference\` (or \`uri\`, \`iri-reference\`, \`iri\`) and rewrites\nthe value via your callback. Fields outside the URI-family are not\ntouched. **Templated-URI formats are intentionally excluded** —\n\`uri-template\` (RFC 6570 templates with \`{var}\` placeholders) and\nJSON-Pointer-derived formats aren\'t file references and don\'t fit the\nrewrite shape.\n\n**Frontmatter-only**: drop the \`rewriteBodyLinks\` line — the rest\nis identical.\n\nAfter running, diff the file (\`git diff <path>\`) to confirm the rewrite\ntouched only the fields and links you expected.",
+    text: "## When you have a JSON Schema for the frontmatter\n\nIf the file\'s frontmatter is governed by a schema (collection-validated, or\njust a hand-written schema you trust), use the schema-driven helper\ninstead of listing field paths by hand. **Compose it with \`rewriteBodyLinks\`\nto cover the body too** — most rewrites (file moves, folder renames) want\nboth sides updated:\n\n\`\`\`typescript\nimport { readFileSync, writeFileSync } from \'node:fs\';\nimport {\n  openFrontmatter,\n  rewriteBodyLinks,\n  rewriteFrontmatterUriReferencesFromSchema,\n} from \'@vibe-agent-toolkit/resources\';\n\nconst rewriteHref = (href: string): string =>\n  href.replace(\'/docs/specs/\', \'/docs/architecture/\');\n\nconst schema = JSON.parse(readFileSync(\'schemas/spec.schema.json\', \'utf8\'));\nconst filePath = \'docs/specs/foo.md\';\nconst editor = openFrontmatter(readFileSync(filePath, \'utf8\'));\n\neditor.body = rewriteBodyLinks(editor.body, rewriteHref);\nrewriteFrontmatterUriReferencesFromSchema(editor, schema, rewriteHref);\n\nwriteFileSync(filePath, editor.toString());\n\`\`\`\n\nThe schema-driven call walks every field whose schema position has\n\`format: uri-reference\` (or \`uri\`, \`iri-reference\`, \`iri\`) and rewrites\nthe value via your callback. Fields outside the URI-family are not\ntouched. **Templated-URI formats are intentionally excluded** —\n\`uri-template\` (RFC 6570 templates with \`{var}\` placeholders) and\nJSON-Pointer-derived formats aren\'t file references and don\'t fit the\nrewrite shape.\n\n**Frontmatter-only**: drop the \`rewriteBodyLinks\` line — the rest\nis identical.\n\nAfter running, diff the file (\`git diff <path>\`) to confirm the rewrite\ntouched only the fields and links you expected."
+  },
+  bulkMigrationManyFilesAtOnce: {
+    header: "## Bulk migration: many files at once",
+    body: "When the rewrite spans dozens or thousands of files (folder rename,\nschema-evolution migration, citation cleanup), the natural shape is\nglob + iterate + dry-run + \`isDirty()\` gate. Pattern:\n\n\`\`\`typescript\nimport { readFileSync, writeFileSync } from \'node:fs\';\nimport { globSync } from \'glob\';  // or \`node:fs\`\'s glob, or fast-glob\nimport {\n  openFrontmatter,\n  rewriteBodyLinks,\n  rewriteFrontmatterUriReferencesFromSchema,\n} from \'@vibe-agent-toolkit/resources\';\n\nconst DRY_RUN = process.env[\'DRY_RUN\'] !== \'false\';\nconst rewriteHref = (href: string): string =>\n  href.replace(\'/docs/specs/\', \'/docs/architecture/\');\n\nconst schema = JSON.parse(readFileSync(\'schemas/spec.schema.json\', \'utf8\'));\nconst files = globSync(\'docs/**/*.md\');\n\nlet changed = 0;\nlet unchanged = 0;\nfor (const filePath of files) {\n  const original = readFileSync(filePath, \'utf8\');\n  const editor = openFrontmatter(original);\n\n  editor.body = rewriteBodyLinks(editor.body, rewriteHref);\n  rewriteFrontmatterUriReferencesFromSchema(editor, schema, rewriteHref);\n\n  // Skip files where nothing material changed. Avoids the no-op churn\n  // described in §\"What\'s preserved, what isn\'t\".\n  const next = editor.toString();\n  if (!editor.isDirty() || next === original) {\n    unchanged++;\n    continue;\n  }\n\n  if (DRY_RUN) {\n    console.log(\`would update ${filePath}\`);\n  } else {\n    writeFileSync(filePath, next);\n  }\n  changed++;\n}\n\nconsole.log(\`${DRY_RUN ? \'DRY RUN: \' : \'\'}${changed} changed, ${unchanged} unchanged\`);\n\`\`\`\n\n**Recommended workflow for bulk runs:**\n\n1. **Sentinel-first.** Run on a single representative file first\n   (\`globSync\` pattern that matches exactly one path). Eyeball the diff.\n2. **Dry-run the full set.** \`DRY_RUN=true\` lists every file the script\n   would touch. Spot-check at least 3 entries before going wet.\n3. **Iterate.** Adjust the callback or schema until the dry-run plan\n   matches your intent.\n4. **Run wet.** \`DRY_RUN=false\`. Then run your project\'s link validator\n   (\`vat resources validate\`, link-check CI, etc.) on the corpus before\n   committing — the rewrite is reversible via \`git checkout\` if any\n   targets are wrong.\n\n**Delegating to a subagent.** Bulk rewrites are good subagent work, but\nbrief them with the same three guardrails: provide the exact callback\nrule, mandate dry-run first, and ask for a structured report (counts\nof files changed/unchanged, a sample of 3 before/after diffs). Without\nthose guardrails, a subagent can silently produce a thousand-file diff\nthat\'s wrong in a subtle way and only catchable on careful review.",
+    text: "## Bulk migration: many files at once\n\nWhen the rewrite spans dozens or thousands of files (folder rename,\nschema-evolution migration, citation cleanup), the natural shape is\nglob + iterate + dry-run + \`isDirty()\` gate. Pattern:\n\n\`\`\`typescript\nimport { readFileSync, writeFileSync } from \'node:fs\';\nimport { globSync } from \'glob\';  // or \`node:fs\`\'s glob, or fast-glob\nimport {\n  openFrontmatter,\n  rewriteBodyLinks,\n  rewriteFrontmatterUriReferencesFromSchema,\n} from \'@vibe-agent-toolkit/resources\';\n\nconst DRY_RUN = process.env[\'DRY_RUN\'] !== \'false\';\nconst rewriteHref = (href: string): string =>\n  href.replace(\'/docs/specs/\', \'/docs/architecture/\');\n\nconst schema = JSON.parse(readFileSync(\'schemas/spec.schema.json\', \'utf8\'));\nconst files = globSync(\'docs/**/*.md\');\n\nlet changed = 0;\nlet unchanged = 0;\nfor (const filePath of files) {\n  const original = readFileSync(filePath, \'utf8\');\n  const editor = openFrontmatter(original);\n\n  editor.body = rewriteBodyLinks(editor.body, rewriteHref);\n  rewriteFrontmatterUriReferencesFromSchema(editor, schema, rewriteHref);\n\n  // Skip files where nothing material changed. Avoids the no-op churn\n  // described in §\"What\'s preserved, what isn\'t\".\n  const next = editor.toString();\n  if (!editor.isDirty() || next === original) {\n    unchanged++;\n    continue;\n  }\n\n  if (DRY_RUN) {\n    console.log(\`would update ${filePath}\`);\n  } else {\n    writeFileSync(filePath, next);\n  }\n  changed++;\n}\n\nconsole.log(\`${DRY_RUN ? \'DRY RUN: \' : \'\'}${changed} changed, ${unchanged} unchanged\`);\n\`\`\`\n\n**Recommended workflow for bulk runs:**\n\n1. **Sentinel-first.** Run on a single representative file first\n   (\`globSync\` pattern that matches exactly one path). Eyeball the diff.\n2. **Dry-run the full set.** \`DRY_RUN=true\` lists every file the script\n   would touch. Spot-check at least 3 entries before going wet.\n3. **Iterate.** Adjust the callback or schema until the dry-run plan\n   matches your intent.\n4. **Run wet.** \`DRY_RUN=false\`. Then run your project\'s link validator\n   (\`vat resources validate\`, link-check CI, etc.) on the corpus before\n   committing — the rewrite is reversible via \`git checkout\` if any\n   targets are wrong.\n\n**Delegating to a subagent.** Bulk rewrites are good subagent work, but\nbrief them with the same three guardrails: provide the exact callback\nrule, mandate dry-run first, and ask for a structured report (counts\nof files changed/unchanged, a sample of 3 before/after diffs). Without\nthose guardrails, a subagent can silently produce a thousand-file diff\nthat\'s wrong in a subtle way and only catchable on careful review."
+  },
+  whatsPreservedWhatIsnt: {
+    header: "## What\'s preserved, what isn\'t",
+    body: "\`openFrontmatter\` inherits its preservation guarantees from \`yaml.Document\`\n(eemeli). Read-only round-trip (no mutations) is byte-identical. Once you\nmutate, the frontmatter section is re-emitted by \`yaml.Document\` and a few\nthings normalize:\n\n| Behavior | Preserved on mutation? |\n|---|---|\n| Inline comment **text** (\`# comment\`) | ✅ |\n| Inline comment **leading whitespace** (\`  #\` vs \` #\`) | ❌ collapsed to one space |\n| Leading comments on keys | ✅ (best-effort; comment-attachment is yaml.Document\'s call) |\n| Comments on individual array items | ✅ |\n| Block scalar style (\`|\`, \`>\`, \`|-\`, \`>+\`) | ✅ |\n| Quoting style (plain / single / double) | ✅ |\n| Blank lines between blocks | ✅ |\n| Key ordering | ✅ |\n| EOL (LF or CRLF) | ✅ (detected from first line break) |\n| Anchors and aliases | ✅ on round-trip; mutating them follows \`yaml.Document\` semantics, not ours |\n\n**Consequence:** even a \"no-op\" rewrite (callback returns the input\nunchanged) re-emits frontmatter and can collapse \`  #\` → \` #\` on every\nline that has an inline comment. The change is harmless but shows up in\n\`git diff\`. Two ways to skip the write in this case:\n\n- **\`editor.isDirty()\`** — returns \`true\` if any mutator was called or\n  \`body\` was reassigned to a different string. Cheap, no string compare,\n  but flips on any mutator call even when the value didn\'t change\n  (e.g. \`set(\'foo\', sameValue)\`). Fine for most workflows.\n- **Byte-level dirty check** — \`editor.toString() !== originalText\`. Catches\n  the no-op-rewrite case exactly; one extra serialize per file. Use this\n  when you must produce zero diff on no-op runs.\n\nThe bulk-migration recipe above combines both: \`isDirty()\` as the cheap\nshort-circuit, then a byte compare to filter out comment-whitespace-only\ndeltas.",
+    text: "## What\'s preserved, what isn\'t\n\n\`openFrontmatter\` inherits its preservation guarantees from \`yaml.Document\`\n(eemeli). Read-only round-trip (no mutations) is byte-identical. Once you\nmutate, the frontmatter section is re-emitted by \`yaml.Document\` and a few\nthings normalize:\n\n| Behavior | Preserved on mutation? |\n|---|---|\n| Inline comment **text** (\`# comment\`) | ✅ |\n| Inline comment **leading whitespace** (\`  #\` vs \` #\`) | ❌ collapsed to one space |\n| Leading comments on keys | ✅ (best-effort; comment-attachment is yaml.Document\'s call) |\n| Comments on individual array items | ✅ |\n| Block scalar style (\`|\`, \`>\`, \`|-\`, \`>+\`) | ✅ |\n| Quoting style (plain / single / double) | ✅ |\n| Blank lines between blocks | ✅ |\n| Key ordering | ✅ |\n| EOL (LF or CRLF) | ✅ (detected from first line break) |\n| Anchors and aliases | ✅ on round-trip; mutating them follows \`yaml.Document\` semantics, not ours |\n\n**Consequence:** even a \"no-op\" rewrite (callback returns the input\nunchanged) re-emits frontmatter and can collapse \`  #\` → \` #\` on every\nline that has an inline comment. The change is harmless but shows up in\n\`git diff\`. Two ways to skip the write in this case:\n\n- **\`editor.isDirty()\`** — returns \`true\` if any mutator was called or\n  \`body\` was reassigned to a different string. Cheap, no string compare,\n  but flips on any mutator call even when the value didn\'t change\n  (e.g. \`set(\'foo\', sameValue)\`). Fine for most workflows.\n- **Byte-level dirty check** — \`editor.toString() !== originalText\`. Catches\n  the no-op-rewrite case exactly; one extra serialize per file. Use this\n  when you must produce zero diff on no-op runs.\n\nThe bulk-migration recipe above combines both: \`isDirty()\` as the cheap\nshort-circuit, then a byte compare to filter out comment-whitespace-only\ndeltas."
+  },
+  crossLinks: {
+    header: "## Cross-links",
+    body: "- \`vat-knowledge-resources\` — how to validate URI-references in\n  frontmatter against a collection schema.\n- \`vat-skill-authoring\` — when to use leading-\`/\` (project-root-relative)\n  URI-refs in SKILL.md frontmatter.",
+    text: "## Cross-links\n\n- \`vat-knowledge-resources\` — how to validate URI-references in\n  frontmatter against a collection schema.\n- \`vat-skill-authoring\` — when to use leading-\`/\` (project-root-relative)\n  URI-refs in SKILL.md frontmatter."
+  }
+};

package/dist/generated/resources/skills/vat-knowledge-resources.d.ts

@@ -25,6 +25,7 @@ export const fragments: {
   readonly addingANewDocType: Fragment;
   readonly recommendFormatUriReferenceForPathShapedFrontmatterFields: Fragment;
   readonly annotatingFrontmatterSchemasWithZod4: Fragment;
+  readonly uriReferencesInFrontmatter: Fragment;
   readonly validationOutput: Fragment;
 };