@vibe-agent-toolkit/agent-skills 0.2.0-rc.6 → 0.2.0-rc.8

package/dist/skill-packager.js

@@ -19,8 +19,9 @@ import { copyFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname } from 'node:path';
 import { DeferredArtifacts, DuplicateResourceIdError, ResourceRegistry, loadConfig, openFrontmatter, resolveLocalHref, rewriteFrontmatterUriReferencesFromSchema, rewriteHtmlLinks, transformContent, parseFileCached, } from '@vibe-agent-toolkit/resources';
 import { allowUnusedIssues, createAllowUsageLedger, runValidationFramework, } from '@vibe-agent-toolkit/schema';
-import { findProjectRoot, isGlob, issueLocation, resolveAssetReference, toForwardSlash, safePath, } from '@vibe-agent-toolkit/utils';
-import { CLAUDE_WEB_REFERENCES_SUBDIR, getTargetSubdir } from './content-type-routing.js';
+import { direntKindFollowingSync, findProjectRoot, isGlob, isSingleFsSegment, issueLocation, resolveAssetReference, safePath, toForwardSlash, VatError, } from '@vibe-agent-toolkit/utils';
+import { readTextContent } from '@vibe-agent-toolkit/utils/fs';
+import { getResourceSubdirForFile } from './content-type-routing.js';
 import { applyFilesConfig, buildArtifactHint, droppedGlobMatchesToIssues, explicitFilesConfigDests, globEntryDest, skippedGlobMatchesToIssues, } from './files-config.js';
 import { READ_REMEDY, withFsAttribution } from './fs-attribution.js';
 import { checkBrokenPackagedLinks, checkMissingReferencedPaths, checkUnreferencedFiles } from './post-build-checks.js';
@@ -29,7 +30,7 @@ import { detectPackagedAgentInstructionFiles } from './validators/agent-instruct
 import { checkPackagedSizeLimit } from './validators/packaged-size-limit.js';
 import { validateSkillForPackaging } from './validators/packaging-validator.js';
 import { materializeIssue } from './validators/rule-engine/index.js';
-import { deferredAssetsToIssues, walkerExclusionsToIssues } from './validators/walker-to-issues.js';
+import { deferredAssetsToIssues, outsideSkillDirLinksToIssues, walkerExclusionsToIssues } from './validators/walker-to-issues.js';
 import { walkLinkGraph } from './walk-link-graph.js';
 const PACKAGE_JSON_FILENAME = 'package.json';
 /** `withFsAttribution` action for a write in `copyAndRewriteFile` — never a copy, since the bytes are rewritten first. */
@@ -41,18 +42,20 @@ const WRITE_ACTION = 'written into the bundle';
  * `{{link.rawText}}`, not `{{link.text}}`, for the same two reasons the rewrite
  * branch uses it (see `bundledLinkTemplate`):
  *
- *  - **Correlation.** `transformContent` keys parsed links by href and lets the
- *    FIRST occurrence win, so `link.text` on a second link sharing that href is
- *    the first link's text. `rawText` is the regex's per-occurrence capture, so it
- *    always belongs to the link being replaced. Stripping with `link.text` swapped
- *    one phrase for an unrelated one in shipped prose; the rewrite branch never
- *    exposed it because it re-emits `rawText`.
+ *  - **Per-occurrence identity.** `link.text` is a property of the parsed link,
+ *    and two occurrences sharing an href are two links whose text may differ.
+ *    `rawText` is always the text of the occurrence actually being replaced, so
+ *    it cannot swap one phrase for an unrelated one in shipped prose.
  *  - **Formatting.** `rawText` keeps the inline markup the author wrote, so
  *    ``[`foo.yaml`](…)`` strips to ``` `foo.yaml` ``` rather than bare `foo.yaml`.
  *
- * Text was the ONLY field the collision could corrupt: the map key is the full
- * href including any `#fragment`, so two links that collide there necessarily
- * resolve to the same resource and carry the same fragment.
+ * > This used to explain the first reason as a defence against `transformContent`
+ * > keying parsed links by href and letting the FIRST occurrence win. That
+ * > correlation is gone: `transformContent` now splices each parsed link at its
+ * > own `[startOffset, endOffset)` span, so there is no shared-href map to collide
+ * > in for any link the parser located. `rawText` remains correct and remains the
+ * > right choice — the reasoning above no longer depends on a collision that the
+ * > rewriter can still have.
  */
 const DEFAULT_STRIP_TEMPLATE = '{{link.rawText}}';
 /**
@@ -292,7 +295,7 @@ export async function packageSkill(skillPath, options = {}) {
     const registry = options.registry ?? await createProjectRegistry(projectRoot);
     // 3b. Load per-collection frontmatter schemas (Gap 3: packager rewrites frontmatter URI-refs
     // against the same schemas the validator uses, with body parity).
-    const collectionSchemas = await loadCollectionSchemas(registry.config, projectRoot);
+    const { schemas: collectionSchemas, issues: collectionSchemaIssues } = await loadCollectionSchemas(registry.config, projectRoot);
     // 4. Walk the link graph using registry data
     const linkFollowDepth = options.linkFollowDepth ?? 2;
     const excludeConfig = options.excludeReferencesFromBundle;
@@ -322,7 +325,7 @@ export async function packageSkill(skillPath, options = {}) {
     if (options.gitTracker !== undefined) {
         packagerWalkOptions.gitTracker = options.gitTracker;
     }
-    const { bundledResources, bundledAssets, excludedReferences, deferredAssets } = walkLinkGraph(skillResourceId, registry, packagerWalkOptions);
+    const { bundledResources, bundledAssets, excludedReferences, outsideSkillDirLinks, deferredAssets } = walkLinkGraph(skillResourceId, registry, packagerWalkOptions);
     // Register non-markdown bundled assets in the source registry so link rewriting
     // can resolve them (resolvedId must be set on links pointing to YAML, JSON, etc.).
     // For any asset whose id is already taken (a path-slug clash — `a-b/c.html`
@@ -344,7 +347,6 @@ export async function packageSkill(skillPath, options = {}) {
     // 7. Clean stale output (skip when source SKILL.md lives inside the output, e.g. builder flow)
     const resolvedOutput = safePath.resolve(outputPath);
     const sourceInOutput = safePath.resolve(skillPath).startsWith(resolvedOutput + '/');
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- outputPath is validated
     if (!sourceInOutput && existsSync(resolvedOutput)) {
         await rm(resolvedOutput, { recursive: true });
     }
@@ -407,9 +409,7 @@ export async function packageSkill(skillPath, options = {}) {
     // The build's own output directory. An unwritable `dist/` or a full disk failed
     // here with a bare errno naming an output path the author never typed — the
     // same shape as the copiers, at the step before any of them run.
-    await withFsAttribution(`skill '${skillMetadata.name}' output directory ${issueLocation(outputPath, projectRoot) || '.'}`, 
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- outputPath is validated
-    () => mkdir(outputPath, { recursive: true }), 'created');
+    await withFsAttribution(`skill '${skillMetadata.name}' output directory ${issueLocation(outputPath, projectRoot) || '.'}`, () => mkdir(outputPath, { recursive: true }), 'created');
     await copyAndRewriteFiles(skillPath, bundledFiles, {
         pathMap,
         rewriteLinks,
@@ -471,7 +471,7 @@ export async function packageSkill(skillPath, options = {}) {
         // directory, not the plugin the skill will be installed into, so there is no
         // wider root to give it — the sibling-search parameter that measured 1.9%
         // instead of 3.8% was deleted for having no caller. The shipped rate is 3.8%.
-        ...await checkMissingReferencedPaths(outputPath),
+        ...await checkMissingReferencedPaths(outputPath, target),
         // The only byte measurement in the pipeline. Built phase for the same reason
         // as its neighbour above: a `files:` entry materializes files here that the
         // source tree does not have, so the bytes that ship are only knowable now.
@@ -495,8 +495,8 @@ export async function packageSkill(skillPath, options = {}) {
         // path a reader can open is its source path.
         ...droppedGlobMatchesToIssues(appliedFiles.dropped, projectRoot),
         // The same receipt, for matches that are not copyable files at all. Anchored
-        // identically and for the identical reason. Until issue #183 this population
-        // had no channel because the build died on the first one it met.
+        // identically and for the identical reason. Without a channel of its own this
+        // population is invisible: the build used to die on the first one it met.
         ...skippedGlobMatchesToIssues(appliedFiles.skipped, projectRoot),
         // Presence-side backstop for agent-instruction files. The walker excludes
         // them from link-following, but a `files:` glob can still copy one in, and
@@ -511,6 +511,9 @@ export async function packageSkill(skillPath, options = {}) {
         // A receipt for each `files:` entry that was dropped for pointing into declared
         // test input — the build already produced the right artifact; this just says so.
         ...testInputFileEntryIssues(droppedTestInputFiles),
+        // A collection schema that could not be loaded, so its frontmatter was not
+        // rewritten (see loadCollectionSchemas).
+        ...collectionSchemaIssues,
         // Backstop: if declared test input reached the output despite both exclusions,
         // say so rather than shipping an answer key silently.
         ...checkPackagedTestInput({ pathMap, outputPath, testInputDirs }),
@@ -522,6 +525,7 @@ export async function packageSkill(skillPath, options = {}) {
         // (a pattern match is author-declared intent; this exclusion is VAT's).
         ...testInputLinkIssues(excludedReferences, testInputDirs, projectRoot),
         ...deferredAssetsToIssues(deferredAssets, projectRoot),
+        ...outsideSkillDirLinksToIssues(outsideSkillDirLinks, projectRoot),
     ];
     // ONE ledger for BOTH lanes below. `options.validation.allow` governs the
     // build-receipt lane AND the built-SKILL.md lane, but the two see disjoint
@@ -600,7 +604,7 @@ function withRunAllowUnused(framework, ledger) {
  *
  * ## 🚨 This lane's link graph is EMPTY — and that is the NORMAL case
  *
- * Measured 2026-08 on a probe fixture (one skill, one `reference.md` reachable by
+ * Measured on a probe fixture (one skill, one `reference.md` reachable by
  * a single relative link from `SKILL.md`), run three ways with ONE variable —
  * where the packaged output lands:
  *
@@ -623,7 +627,7 @@ function withRunAllowUnused(framework, ledger) {
  * `${CLAUDE_PLUGIN_ROOT}` invocation inside a bundled reference is caught at
  * source and CANNOT be caught in the built artifact.
  *
- * 🔑 Measured vs inferred. The three rows are MEASURED (2026-08, that probe).
+ * 🔑 Measured vs inferred. The three rows are MEASURED (that probe).
  * That the finding is still LIVE is inferred from this function's own body: it
  * passes only the built `SKILL.md` path, with no registry and no population
  * source rooted at the output tree, so `validateSkillForPackaging` resolves
@@ -644,7 +648,7 @@ function withRunAllowUnused(framework, ledger) {
  */
 async function runPostBuildValidation(outputPath, validation, allowLedger) {
     const builtSkillPath = safePath.join(outputPath, 'SKILL.md');
-    return validateSkillForPackaging(builtSkillPath, validation ? { validation } : undefined, 'built', { allowLedger });
+    return validateSkillForPackaging(builtSkillPath, validation ? { validation } : undefined, 'built', { allowLedger, unreadable: 'refuse' });
 }
 /**
  * Assemble the final PackageSkillResult from intermediate data.
@@ -719,6 +723,9 @@ export async function createProjectRegistry(projectRoot, options = {}) {
     const registry = await ResourceRegistry.fromCrawl({
         baseDir: projectRoot,
         include: ['**/*.md'],
+        // A build must not ship a shorter bundle: a directory this crawl cannot
+        // list refuses the run by name — see `RegistryUnreadablePolicy`.
+        unreadable: 'refuse',
         ...(options.populationSource !== undefined && { populationSource: options.populationSource }),
     }, config === undefined ? undefined : { config });
     registry.resolveLinks();
@@ -730,30 +737,40 @@ export async function createProjectRegistry(projectRoot, options = {}) {
  * Mirrors ResourceRegistry.validateAgainstCollectionSchema's loading flow so
  * the packager rewrites frontmatter URI-refs against the same schemas the
  * validator uses. Collections without a frontmatterSchema configured are
- * absent from the map. Schema file read/parse failures are silently skipped
- * — the validator will surface those errors elsewhere; the packager just
- * won't rewrite the un-routed collection's frontmatter.
+ * absent from the map.
+ *
+ * A schema that cannot be resolved, read or parsed is absent from the map too,
+ * and that is REPORTED as a `FRONTMATTER_SCHEMA_ERROR` issue in the build's own
+ * receipt — the same code `vat validate` gives the same config. It used to be
+ * swallowed on the theory that "the validator will surface it elsewhere", which
+ * left `vat build` shipping a bundle whose frontmatter URI-refs still pointed
+ * at source-tree paths, with a clean report and nothing to say why.
  */
 async function loadCollectionSchemas(config, baseDir) {
     const schemas = new Map();
+    const issues = [];
     const collections = config?.resources?.collections;
     if (!collections)
-        return schemas;
+        return { schemas, issues };
     for (const [collectionId, collectionConfig] of Object.entries(collections)) {
         const schemaPath = collectionConfig.validation?.frontmatterSchema;
         if (schemaPath === undefined)
             continue;
         try {
             const resolvedPath = resolveAssetReference(schemaPath, baseDir);
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- schema path from validated config
             const content = await readFile(resolvedPath, 'utf-8');
             schemas.set(collectionId, JSON.parse(content));
         }
-        catch {
-            // Schema unavailable — validator will report; packager skips rewrite.
+        catch (error) {
+            issues.push(materializeIssue('FRONTMATTER_SCHEMA_ERROR', {
+                location: schemaPath,
+                message: `Collection "${collectionId}" declares frontmatterSchema "${schemaPath}", which could not ` +
+                    `be loaded: ${error instanceof Error ? error.message : String(error)}. Frontmatter ` +
+                    `URI-references in this collection were NOT rewritten for the packaged output.`,
+            }));
         }
     }
-    return schemas;
+    return { schemas, issues };
 }
 /**
  * Generate a synthetic resource ID for a non-markdown asset that collides with an
@@ -980,7 +997,6 @@ function applyFilesEntriesToPathMap(filesConfig, projectRoot, outputPath, pathMa
         // have helped. A wrong diagnosis with a confident wrong remedy attached.
         // Only ENOENT is absence; a refusal is reported as itself, naming the entry.
         try {
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- source path from validated config
             statSync(absoluteSource);
         }
         catch (error) {
@@ -1121,21 +1137,6 @@ function stampDeferredDestResolvedId(resources, absDestTarget, id) {
     }
     return linked;
 }
-// ============================================================================
-// Path Map Building
-// ============================================================================
-/**
- * Determine the resource subdirectory for a file.
- *
- * For claude-web target: uses the existing references directory.
- * For claude-code target: uses content-type routing based on file extension.
- */
-export function getResourceSubdirForFile(filePath, target) {
-    if (target === 'claude-web') {
-        return CLAUDE_WEB_REFERENCES_SUBDIR;
-    }
-    return getTargetSubdir(filePath);
-}
 /**
  * The FILENAME_COLLISION finding for one pair of sources that package to one dest.
  *
@@ -1320,6 +1321,106 @@ async function copyAndRewriteFiles(skillPath, bundledFiles, ctx) {
  *
  * For non-markdown files, performs a plain binary copy.
  */
+/**
+ * Re-base a resource's link spans onto the frontmatter-stripped body.
+ *
+ * ## 🚨 Why this exists: the span rewrite was INERT here, and could mis-splice
+ *
+ * `transformContent` identifies each link by its parsed `[startOffset,
+ * endOffset)` span rather than by replaying a regex and correlating on href —
+ * which is the whole point, because the two grammars disagree about what the
+ * href IS. Its docstring states the precondition outright: *links must come from
+ * the same bytes as content*.
+ *
+ * This call site violated it. `resource.links` are parsed from the WHOLE FILE,
+ * and `editor.body` has the frontmatter block removed — so every offset was off
+ * by the frontmatter's length. Measured on a four-line skill: span `[45, 77)`
+ * against a body shifted by 40, where `body.slice(45, 81)` is `"ails.\n"`. Every
+ * splice declined and every link fell back to the pre-fix regex path, so the
+ * headline defect (`[![alt](img)](url)` silently not rewritten) was still
+ * shipping. Worse, a stale span can land on a *different*, structurally valid
+ * link and rewrite ITS href to the first link's target.
+ *
+ * ## The re-base is VERIFIED, not assumed
+ *
+ * Subtracting `content.length - body.length` is correct if and only if `body` is
+ * a literal SUFFIX of `content` — that is exactly the statement "every body index
+ * `i` is content index `i + offset`". `String.endsWith` decides it outright, so
+ * the arithmetic is checked rather than argued, and a body that is not a suffix
+ * comes back with its spans REMOVED instead of with coordinates nothing verified.
+ * `openFrontmatter` does yield a suffix today, across CRLF, a commented block, an
+ * absent block and empty input; the check is what keeps that a fact rather than a
+ * comment that outlives the code it describes.
+ *
+ * ⛔ **This used to claim `splicableFrom` as its backstop, and that claim was
+ * false.** The words were: "`splicableFrom` refuses any span whose destination is
+ * not exactly the parser's href, so a misalignment that survives this degrades to
+ * *no rewrite* rather than to a wrong one." It does not. That comparison is keyed
+ * on the HREF, which two links in one document routinely share, so a stale span
+ * landing on a same-href neighbour passes it and the neighbour is rewritten
+ * through the first link's metadata. Constructed and pinned in
+ * `packages/resources/test/content-transform.test.ts` › *two links sharing an
+ * href defeat the destination comparison*, where a tuned frontmatter length makes
+ * two labels swap places. A mitigation keyed on a value the two candidates have
+ * in common cannot be a guarantee, and a guard resting on one is resting on
+ * nothing.
+ *
+ * 🔑 What holds instead, in full, because the precondition has two halves:
+ *
+ * 1. *The spans address `content`* — discharged by the reader, not by this
+ *    function. `resource.links` and `content` must come from the same decode of
+ *    the same file, which is why the caller's read is pinned to
+ *    `readTextContent` with a 🚨 of its own. A second reader is the one way this
+ *    half fails, and it fails invisibly.
+ * 2. *The subtraction maps `content` onto `body`* — discharged here, by
+ *    `endsWith`.
+ *
+ * `splicableFrom`'s destination check remains a useful mitigation for the
+ * residue. It is not counted on, and nothing here degrades gracefully because of
+ * it.
+ *
+ * @param content - The file as read, which the links were parsed from
+ * @param body - The frontmatter-stripped body the rewrite will run over
+ * @param links - The resource's links, carrying whole-file offsets
+ * @param onUnverifiable - Called when `body` is not a suffix of `content`, so the
+ *   caller can say which file lost its span-driven rewrite. Never called on the
+ *   normal path.
+ * @returns The same links with offsets stated against `body`, or with no offsets
+ *   at all when the re-base could not be verified
+ */
+export function bodyRelativeLinks(content, body, links, onUnverifiable) {
+    if (!content.endsWith(body)) {
+        onUnverifiable();
+        return links.map(withoutSpan);
+    }
+    const offset = content.length - body.length;
+    if (offset === 0)
+        return [...links];
+    return links.map((link) => ({
+        ...link,
+        ...(link.startOffset === undefined ? {} : { startOffset: link.startOffset - offset }),
+        ...(link.endOffset === undefined ? {} : { endOffset: link.endOffset - offset }),
+    }));
+}
+/**
+ * The link with its coordinates dropped and everything else kept.
+ *
+ * ⚠️ Dropping them is the point, and returning the link unchanged would be the
+ * bug: an unrebased whole-file span still ADDRESSES the body's bytes, just the
+ * wrong ones, so `splicableFrom` would happily splice at it. Without a span the
+ * link is `UNRECOGNISED`, which routes it to the pre-span regex replay — the
+ * behaviour this call site had before spans existed. A documented degrade, not a
+ * silent one; the caller warns.
+ *
+ * @param link - A link whose offsets could not be re-based
+ * @returns The same link with no `startOffset` and no `endOffset` key
+ */
+function withoutSpan(link) {
+    const stripped = { ...link };
+    delete stripped.startOffset;
+    delete stripped.endOffset;
+    return stripped;
+}
 async function copyAndRewriteFile(sourcePath, targetPath, ctx) {
     // Through the SAME attribution point as the `files:` lanes. This is the default
     // path for every ordinary markdown-linked file in a build — the most-travelled
@@ -1330,7 +1431,6 @@ async function copyAndRewriteFile(sourcePath, targetPath, ctx) {
     const subject = `linked file ${issueLocation(sourcePath, ctx.projectRoot) || '.'}`;
     // Ensure target directory exists
     await withFsAttribution(subject, async () => {
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- targetPath is constructed from validated paths
         await mkdir(dirname(targetPath), { recursive: true });
     });
     const lower = sourcePath.toLowerCase();
@@ -1341,10 +1441,34 @@ async function copyAndRewriteFile(sourcePath, targetPath, ctx) {
         await withFsAttribution(subject, () => copyFile(sourcePath, targetPath));
         return;
     }
-    // Read source file
-    const content = await withFsAttribution(subject, 
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- sourcePath is validated
-    () => readFile(sourcePath, 'utf-8'), 
+    // Read source file.
+    //
+    // 🚨 `readTextContent`, never `readFile(path, 'utf-8')` — and here the reason
+    // is sharper than the general one `link-parser.ts:149` gives. THE LINKS WERE
+    // PARSED FROM THIS FILE BY THAT READER, and `bodyRelativeLinks` below
+    // re-bases their offsets by differencing two string lengths. Two different
+    // readers make that subtraction meaningless: `readTextContent` strips a BOM
+    // and decodes UTF-16/32, so on a BOM-bearing file `readFile` returned a
+    // string one character longer, `OPENING_FENCE` (`/^---\r?\n/`) then failed to
+    // match, `openFrontmatter` reported no frontmatter, the offset came out 0,
+    // and every span stayed whole-file — silently reverting the fix this call
+    // site exists to deliver.
+    //
+    // ⛔ This comment used to add "it failed CLOSED rather than corrupting, only
+    // because `splicableFrom` compares the destination to the href." That is not
+    // a guarantee and must not be read as one: the destination check is keyed on
+    // the href, which two links in one document routinely share, so a stale span
+    // landing on a same-href neighbour passes it (constructed in
+    // `content-transform.test.ts` › *two links sharing an href defeat the
+    // destination comparison*). The BOM shift also survives
+    // `bodyRelativeLinks`'s own `endsWith` check, because a body equal to the
+    // content IS a suffix of it — nothing downstream can see that the links came
+    // from a different decode. **One reader is the only thing standing between
+    // this lane and a wrong rewrite.** Do not swap it.
+    //
+    // It also stops a UTF-16 source being written back as mojibake, which the
+    // `utf-8` read did on the copy as well as the rewrite.
+    const { text: content } = await withFsAttribution(subject, () => readTextContent(sourcePath), 
     // Not "copied": the read is the step that failed, and this lane reads before
     // it rewrites, so naming the copy would point past the actual failure.
     'read for link rewriting', READ_REMEDY);
@@ -1365,9 +1489,7 @@ async function copyAndRewriteFile(sourcePath, targetPath, ctx) {
                 `Source-relative links inside it are not rewritten.`
             : `Copied '${sourcePath}' verbatim without link rewriting: it lost a resource-id collision to ` +
                 `'${winner}', which was registered first and holds the id. Source-relative links inside it are not rewritten.`);
-        await withFsAttribution(subject, 
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- targetPath is constructed from validated paths
-        () => writeFile(targetPath, content, 'utf-8'), WRITE_ACTION);
+        await withFsAttribution(subject, () => writeFile(targetPath, content, 'utf-8'), WRITE_ACTION);
         return;
     }
     // HTML: offset-splice link rewrite (no frontmatter, no template body rewrite).
@@ -1377,9 +1499,7 @@ async function copyAndRewriteFile(sourcePath, targetPath, ctx) {
             ctx.warn(`Could not rewrite <${info.tagName} ${info.attr}="${info.from}"> in '${sourcePath}' (${info.reason}); ` +
                 `the original value was kept.`);
         });
-        await withFsAttribution(subject, 
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- targetPath is constructed from validated paths
-        () => writeFile(targetPath, rewritten, 'utf-8'), WRITE_ACTION);
+        await withFsAttribution(subject, () => writeFile(targetPath, rewritten, 'utf-8'), WRITE_ACTION);
         return;
     }
     // Parse once via FrontmatterEditor so comments survive any frontmatter
@@ -1387,7 +1507,13 @@ async function copyAndRewriteFile(sourcePath, targetPath, ctx) {
     // for the existing rule/template body-link rewrite contract (unchanged).
     const editor = openFrontmatter(content);
     // Body rewrite (existing behavior, unchanged contract).
-    editor.body = transformContent(editor.body, resource.links, {
+    const rebased = bodyRelativeLinks(content, editor.body, resource.links, () => {
+        ctx.warn(`Rewrote links in '${sourcePath}' without parsed spans: the frontmatter-stripped body is not a ` +
+            `suffix of the file as read, so the offsets the parser reported cannot be moved onto it. ` +
+            `Links are matched by href instead, which is the pre-span behaviour — a link the two grammars ` +
+            `disagree about (an image inside a link, most often) may go unrewritten.`);
+    });
+    editor.body = transformContent(editor.body, rebased, {
         linkRewriteRules: ctx.rewriteRules,
         resourceRegistry: ctx.toRegistry,
         sourceFilePath: targetPath, // Output path so relativePath is computed from output location
@@ -1407,9 +1533,7 @@ async function copyAndRewriteFile(sourcePath, targetPath, ctx) {
             }
         }
     }
-    await withFsAttribution(subject, 
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- targetPath is constructed from validated paths
-    () => writeFile(targetPath, editor.toString(), 'utf-8'), WRITE_ACTION);
+    await withFsAttribution(subject, () => writeFile(targetPath, editor.toString(), 'utf-8'), WRITE_ACTION);
 }
 /**
  * Build the per-href rewrite callback used for frontmatter URI-refs and HTML attributes.
@@ -1463,10 +1587,10 @@ function buildHrefRewriter(fromRegistry, toRegistry, sourcePath, targetPath, pro
  * but this check acts as a safety net in case files are introduced through other means.
  */
 async function validateNoNestedSkillMd(outputPath, skillName) {
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- outputPath is validated
     const entries = readdirSync(outputPath, { recursive: true, withFileTypes: true });
     const nestedSkillMds = entries
-        .filter(entry => entry.isFile() && entry.name === 'SKILL.md')
+        // Followed: a symlinked nested SKILL.md is a nested skill marker all the same.
+        .filter(entry => entry.name === 'SKILL.md' && direntKindFollowingSync(entry.parentPath, entry) === 'file')
         .map(entry => safePath.relative(outputPath, safePath.join(entry.parentPath, entry.name)))
         .filter(relativePath => relativePath !== 'SKILL.md'); // Exclude the root SKILL.md
     if (nestedSkillMds.length > 0) {
@@ -1634,14 +1758,13 @@ const ZIP_SIZE_ERROR_BYTES = 8 * 1024 * 1024;
  * Thrown when a claude-web ZIP exceeds the 8MB Claude.ai upload limit.
  * The CLI catches this and exits with code 1.
  */
-export class ZipSizeLimitError extends Error {
+export class ZipSizeLimitError extends VatError {
     sizeBytes;
     limitBytes;
     constructor(sizeBytes, limitBytes) {
         const mb = (sizeBytes / 1024 / 1024).toFixed(1);
-        super(`ZIP size ${mb}MB exceeds 8MB limit for Claude.ai upload. ` +
+        super('ZIP_SIZE_LIMIT', `ZIP size ${mb}MB exceeds 8MB limit for Claude.ai upload. ` +
             `Reduce the number of linked resources or use --target claude-code.`);
-        this.name = 'ZipSizeLimitError';
         this.sizeBytes = sizeBytes;
         this.limitBytes = limitBytes;
     }
@@ -1653,7 +1776,6 @@ export class ZipSizeLimitError extends Error {
  * @param zipPath - Path to the ZIP file
  */
 function validateZipSize(zipPath) {
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- zipPath is constructed from validated outputPath
     const stats = statSync(zipPath);
     const bytes = stats.size;
     if (bytes >= ZIP_SIZE_ERROR_BYTES) {
@@ -1734,7 +1856,6 @@ async function createNpmPackage(outputPath, metadata) {
         files: ['**/*.md'],
     };
     const packageJsonPath = safePath.join(outputPath, PACKAGE_JSON_FILENAME);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path is constructed from validated outputPath
     await writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2), 'utf-8');
     // For now, just return a placeholder path
     // Full npm pack implementation would require running `npm pack`
@@ -1759,7 +1880,6 @@ async function createMarketplaceManifest(outputPath, metadata) {
         created: new Date().toISOString(),
     };
     const manifestPath = safePath.join(dirname(outputPath), `${metadata.name}.marketplace.json`);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path is constructed from validated outputPath
     await writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8');
     return manifestPath;
 }
@@ -1773,6 +1893,15 @@ async function createMarketplaceManifest(outputPath, metadata) {
  * @returns Default output path
  */
 function getDefaultSkillOutputPath(skillPath, skillName) {
+    // The name may have come from the H1 title when frontmatter carries none,
+    // and the directory this returns is `rm -rf`'d before the package is
+    // written: a SKILL.md headed `# ../../../canary` used to delete `<root>/canary`
+    // through the public `packageSkill` export, issues empty, `hasErrors` false.
+    if (!isSingleFsSegment(skillName)) {
+        throw new VatError('SKILL_NAME_NOT_A_SEGMENT', `Cannot derive an output directory from skill name "${skillName}": a name must be a single ` +
+            `path segment (no separators, not "." or ".."). Declare \`name:\` in the SKILL.md frontmatter ` +
+            `or pass an explicit outputPath.`);
+    }
     const skillPackageRoot = findPackageRoot(skillPath);
     return safePath.join(skillPackageRoot, 'dist', 'skills', skillName);
 }
@@ -1791,7 +1920,6 @@ function findPackageRoot(skillPath, fallbackToSkillDir = false) {
     // Walk up until we find a package.json or hit the filesystem root
     while (currentDir !== dirname(currentDir)) {
         const packageJsonPath = safePath.join(currentDir, PACKAGE_JSON_FILENAME);
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- Searching for package.json
         if (existsSync(packageJsonPath)) {
             return currentDir;
         }