@vibe-agent-toolkit/agent-skills 0.1.42 → 0.2.0-rc.10

package/dist/skill-packager.js

@@ -17,19 +17,25 @@
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { copyFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname } from 'node:path';
-import { allowUnusedIssues, createAllowUsageLedger, runValidationFramework, } from '@vibe-agent-toolkit/agent-schema';
-import { DeferredArtifacts, ResourceRegistry, loadConfig, openFrontmatter, resolveLocalHref, rewriteFrontmatterUriReferencesFromSchema, rewriteHtmlLinks, transformContent, parseMarkdown, } from '@vibe-agent-toolkit/resources';
-import { findProjectRoot, isGlob, issueLocation, resolveAssetReference, toForwardSlash, safePath, } from '@vibe-agent-toolkit/utils';
-import { CLAUDE_WEB_REFERENCES_SUBDIR, getTargetSubdir } from './content-type-routing.js';
-import { applyFilesConfig, buildArtifactHint, droppedGlobMatchesToIssues, explicitFilesConfigDests, globEntryDest, } from './files-config.js';
-import { checkBrokenPackagedLinks, checkUnreferencedFiles } from './post-build-checks.js';
+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 { direntKindFollowingSync, findProjectRoot, isGlob, isSingleFsSegment, issueLocation, resolveAssetReference, safePath, toForwardSlash, toForwardSlashAnyPlatform, 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 { LINK_GRAPH_MEMBER_GLOBS } from './link-graph-members.js';
+import { checkBrokenPackagedLinks, checkMissingReferencedPaths, checkUnreferencedFiles } from './post-build-checks.js';
 import { checkPackagedTestInput, partitionTestInputFileEntries, resolveTestInputDirs, testInputExcludeRules, testInputFileEntryIssues, testInputLinkIssues, } from './test-input.js';
 import { detectPackagedAgentInstructionFiles } from './validators/agent-instruction-presence.js';
+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. */
+const WRITE_ACTION = 'written into the bundle';
 /**
  * Default template for excluded links when no explicit template is configured —
  * renders just the link text.
@@ -37,18 +43,20 @@ const PACKAGE_JSON_FILENAME = 'package.json';
  * `{{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}}';
 /**
@@ -105,8 +113,16 @@ const DEFAULT_PACKAGING_TARGET = 'claude-code';
  * repo has been bitten by). It is required rather than defaulted because the test-input
  * rule is project-wide: omitting it silently packages another skill's eval answer key.
  * A lane with genuinely no project to enumerate passes `[]` explicitly.
+ *
+ * `hasConventionalSuite` is the RUN's conventional-suite probe, and travels with
+ * `projectSkills` for the same reason and on the same schedule: this conversion runs
+ * once per skill and asks the filesystem about every root in `projectSkills`, so a
+ * per-call probe makes a build of S skills cost S² probes over S paths. Required, not
+ * defaulted — a `probe?` would let every existing caller keep the quadratic silently,
+ * which is precisely how the `projectSkills` rule above once shipped as a no-op. A
+ * lane packaging a single skill calls `conventionalSuiteProbe()` at its own call site.
  */
-export function packagingConfigToPackageOptions(config, anchors, projectSkills) {
+export function packagingConfigToPackageOptions(config, anchors, projectSkills, hasConventionalSuite) {
     return {
         outputPath: anchors.outputPath,
         formats: ['directory'],
@@ -135,7 +151,7 @@ export function packagingConfigToPackageOptions(config, anchors, projectSkills)
         // excluded as well. Keyed to this skill alone, that sibling's answer key was
         // ordinary content and shipped.
         ...(() => {
-            const testInputDirs = resolveTestInputDirs(config, dirname(anchors.skillPath), projectSkills);
+            const testInputDirs = resolveTestInputDirs(config, dirname(anchors.skillPath), projectSkills, hasConventionalSuite);
             return testInputDirs.length > 0 ? { testInputDirs } : {};
         })(),
     };
@@ -176,6 +192,11 @@ export function packagingConfigToPackageOptions(config, anchors, projectSkills)
  *   (`vat build` also validates the SOURCE tree, whose matches count too).
  *   Containment does not change that: a skill that threw may still have matched
  *   allow entries before it threw, and those matches count for the run.
+ * @param runOptions - Registry-build options for the RUN. Named apart from the
+ *   per-skill `options` destructured in the loop below, which it is not: it
+ *   configures the ONE shared registry {@link createProjectRegistry} builds here.
+ *   It does NOT reach the per-skill post-build validation, which builds a private
+ *   registry over the BUILT tree — see {@link runPostBuildValidation}
  * @returns One outcome per input spec, in input order
  *
  * @example
@@ -189,17 +210,26 @@ export function packagingConfigToPackageOptions(config, anchors, projectSkills)
  * const runIssues = allowUnusedIssues(ledger);
  * ```
  */
-export async function packageSkills(skills, projectRoot, allowLedger) {
+export async function packageSkills(skills, projectRoot, allowLedger, runOptions = {}) {
     // 1. Create one registry for the entire project. Through the shared builder:
     // this used to call `fromCrawl` directly and omit the config, so skills built
     // here belonged to no collection while a skill built through the single-skill
     // fallback did.
-    const registry = await createProjectRegistry(projectRoot);
+    //
+    // `runOptions` is forwarded rather than absorbed: this is the ONLY registry the
+    // run builds, so a caller that wants the run on the projection lane has no
+    // other seam to reach. Dropping it here would leave `vat skills build`
+    // reaching a store it opened and never used.
+    const registry = await createProjectRegistry(projectRoot, runOptions);
     // 2. Package each skill against the shared registry
     const outcomes = [];
     for (const { skillPath, options } of skills) {
         try {
-            const result = await packageSkill(skillPath, { ...options, registry, allowLedger });
+            const result = await packageSkill(skillPath, {
+                ...options,
+                registry,
+                allowLedger,
+            });
             outcomes.push({ status: 'built', skillPath, result });
         }
         catch (error) {
@@ -235,7 +265,7 @@ export async function packageSkills(skills, projectRoot, allowLedger) {
 export async function packageSkill(skillPath, options = {}) {
     const { formats = ['directory'], rewriteLinks = true, resourceNaming = 'basename', stripPrefix, target = DEFAULT_PACKAGING_TARGET, } = options;
     // 1. Parse SKILL.md frontmatter and links
-    const parseResult = await parseMarkdown(skillPath);
+    const parseResult = await parseFileCached(skillPath, 'markdown');
     const skillMetadata = extractSkillMetadata(parseResult, skillPath);
     // 2. Find project boundary (config root -> git root -> skill dir).
     // Library callers fall back to the skill directory when canonical
@@ -266,7 +296,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;
@@ -296,13 +326,13 @@ 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 collides with a paired markdown file (e.g. config.yaml +
-    // config.md both produce id `resources-config`), we set a synthetic resolvedId on
-    // links pointing to it so link rewriting still works.
-    const collidedAssets = await registerBundledAssets(registry, bundledAssets);
+    // For any asset whose id is already taken (a path-slug clash — `a-b/c.html`
+    // and `a/b-c.html` both flatten to `a-b-c-html`), we set a synthetic
+    // resolvedId on links pointing to it so link rewriting still works.
+    const { collidedAssets, collisions: assetCollisions } = await registerBundledAssets(registry, bundledAssets, projectRoot);
     resolveCollidedAssetLinks(collectResourcesWithLinks(bundledResources, skillResource), collidedAssets);
     // Combine bundled file paths: markdown resources + non-markdown assets
     const bundledFiles = [
@@ -318,7 +348,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 });
     }
@@ -378,12 +407,21 @@ export async function packageSkill(skillPath, options = {}) {
     // 11. Build unified rewrite rules (bundled + excluded, all via transformContent)
     const rewriteRules = buildRewriteRules(excludedIds, excludeConfig?.rules ?? [], excludeConfig?.defaultTemplate);
     // 12. Copy and rewrite files
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- outputPath is validated
-    await mkdir(outputPath, { recursive: true });
+    // 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) || '.'}`, () => mkdir(outputPath, { recursive: true }), 'created');
     await copyAndRewriteFiles(skillPath, bundledFiles, {
         pathMap,
         rewriteLinks,
         fromRegistry: registry,
+        // Both sources, because they record disjoint populations: the registry's
+        // own log holds crawl-time drops made by `addResources`, while
+        // `registerBundledAssets` holds the per-asset drops `addResource` only ever
+        // signalled by throwing. An HTML file that collides with a same-named
+        // markdown file appears ONLY in the second.
+        duplicateIdDrops: new Map([...registry.getDuplicateIdCollisions(), ...assetCollisions]
+            .map(c => [toForwardSlash(c.conflictingPath), c.existingPath])),
         toRegistry: outputRegistry,
         rewriteRules,
         templateContext: { skill: { name: skillMetadata.name } },
@@ -425,6 +463,30 @@ export async function packageSkill(skillPath, options = {}) {
         ...collisionIssues,
         ...await checkUnreferencedFiles(outputPath, filesConfigDests),
         ...await checkBrokenPackagedLinks(outputPath, droppedGlobDests),
+        // The inverse of checkUnreferencedFiles: paths the docs NAME that the bundle
+        // does not contain. Built phase only — a `files:` dest exists here and not in
+        // the source tree, so the same check at source phase flags every injected
+        // script.
+        //
+        // SKILL-LOCAL, and this is the ONLY caller. The packager knows its own output
+        // 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, 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.
+        //
+        // ⚠️ Runs before step 14, so it does not weigh what `generatePackageArtifacts`
+        // adds. Measured, so the residue is not a guess: the `zip` and `npm` formats
+        // write to `<outputPath>.zip` / `.tgz`, OUTSIDE the bundle and outside the
+        // upload; only the `npm` format's synthetic package.json and the `marketplace`
+        // format's manifest land inside, and both are a few hundred bytes. The order
+        // is not free to change — checkUnreferencedFiles two lines up would flag that
+        // same synthetic package.json — so the under-count is stated rather than
+        // fixed. If an artifact step ever writes something LARGE into outputPath, this
+        // call has to move after it and the framework run with it.
+        ...checkPackagedSizeLimit(outputPath),
         // A receipt for every file a glob matched and the never-package list refused.
         // Reported as an issue, not written to stderr: a file vanishing from a bundle
         // has to be visible in `issueCounts`, or CI reads a clean report for a build
@@ -433,6 +495,10 @@ export async function packageSkill(skillPath, options = {}) {
         // dropped file is a source file that never reached the output, so the only
         // 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. 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
         // a file that arrives without a link is invisible to the link lane.
@@ -446,6 +512,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 }),
@@ -457,6 +526,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
@@ -516,10 +586,70 @@ function withRunAllowUnused(framework, ledger) {
  *
  * `allowLedger` is required, not optional: this lane is one half of a build, so
  * it must never conclude on its own that an allow entry matched nothing.
+ *
+ * ⛔ This lane stays on the walk and is handed no `populationSource`. It validates
+ * the BUILT tree under `outputPath` — a different tree from the one the run
+ * enumerated, not tracked by git, and not covered by the packaging registry. A
+ * source produced by `withResourcePopulationSource` is bound to the PROJECT root
+ * and its git tree hash, so offering it a build-output directory asks it a
+ * question about a tree it does not describe. Forwarding it here was tried and
+ * reverted — the giveaway was a source offered `<root>/out/<skill>` instead of
+ * the root.
+ *
+ * The store-poisoning half of that hazard is now closed at the seam rather than by
+ * this comment: `ResourceRegistry.populationFrom` compares the source's own bound
+ * root against the crawl's base and declines a mismatch back onto the walk. So a
+ * future forward here would be a no-op that warns, not a corrupted extent key.
+ * What it would still NOT be is a speed-up, which is why nothing is forwarded:
+ * the built tree is a different tree, so there is no stored answer for it to hit.
+ *
+ * ## 🚨 This lane's link graph is EMPTY — and that is the NORMAL case
+ *
+ * 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:
+ *
+ * | lane | output location | `fileCount` | `directFileCount` | `maxLinkDepth` | `totalLines` |
+ * |---|---|---:|---:|---:|---:|
+ * | source | n/a | 2 | 1 | 1 | 13 |
+ * | built | INSIDE the project (`<root>/dist/skills/<name>/`) | **1** | **0** | **0** | **10** |
+ * | built | outside any project root (control) | 2 | 1 | 1 | 14 |
+ *
+ * The middle row is the defect; the third row PROVES the cause — the only
+ * difference between them is whether the output falls under the crawl's
+ * `**\/dist\/**` exclusion (`BUILD_OUTPUT_GLOBS`). `packageSkill`'s default output
+ * IS the middle row, so this is the normal case, not an edge case. The result's
+ * own `files.dependencies` still reads `["reference.md"]`: the packager copied it,
+ * and the validator invoked here — immediately afterwards — cannot see it.
+ *
+ * ⚠️ It is not only a metrics hole. `collectNonPortableAssetReferenceIssues` and
+ * `collectNonPortableCommandIssues` iterate `bundledFiles`, so in the built lane
+ * they never open a single bundled reference file. A non-portable
+ * `${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 (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
+ * `findProjectRoot` back to the SOURCE project and crawls it under the default
+ * exclude — the built tree is never enumerated, `getResource` misses, and the
+ * walk starts from nothing. The probe is no longer only a probe: it is pinned as
+ * a committed regression test at
+ * `packages/cli/test/integration/built-lane-link-graph.integration.test.ts`
+ * (fixture `BUNDLING_SKILL_FILES`), asserting the middle row as today's
+ * behaviour. When this is fixed, those assertions flip in the fixing change.
+ *
+ * ⛔ Do NOT fix it by widening the crawl. That same `**\/dist\/**` exclusion is
+ * the stated correctness proof for `crawlAndResolveRegistry`'s process-lifetime
+ * memo, which the audit lane, the validate lane AND this lane all share — see the
+ * comment on `walkRegistryCache` in `validators/packaging-validator.ts`. Widening
+ * it retracts that argument for every lane sharing the memo; this is not a
+ * one-lane fix.
  */
 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.
@@ -546,9 +676,6 @@ function assemblePackageResult(input) {
     }
     return result;
 }
-// ============================================================================
-// Registry Creation
-// ============================================================================
 /**
  * Build THE project registry: every markdown file under `projectRoot`, parsed,
  * with links resolved and the project config attached.
@@ -566,12 +693,41 @@ function assemblePackageResult(input) {
  * so a lane that built its own config-less registry rewrote frontmatter
  * differently from the lane that used this one — which is why there is now only
  * one builder rather than two that happened to differ in one argument.
+ *
+ * ## Why the include set is markdown-only, unlike `crawlAndResolveRegistry`'s
+ *
+ * The difference is deliberate and is NOT a hole that leaves HTML unrewritten.
+ * A bundled HTML file joins this registry later, on demand, via
+ * {@link registerBundledAssets} — which parses it and resolves its links before
+ * the copy step, so `rewriteHtmlLinks` reaches it. Crawling every `.html` under
+ * the project up front would parse generated output the build never bundles,
+ * and would move `page.md` vs `page.html` id collisions from the narrow
+ * bundled-asset path onto the whole-project crawl.
+ *
+ * Widening this glob would NOT widen what the walker follows: routing is
+ * markdown-only regardless — see `isRoutable` in `walk-link-graph.ts`.
+ *
+ * ## The optional population source, and why it cannot widen that glob
+ *
+ * `populationSource` replaces the ENUMERATION only. `ResourceRegistry.crawl`
+ * re-applies this function's `include` — and the crawl's default `exclude` —
+ * to whatever the source offers, through the same compiled matcher the walk
+ * itself uses, so a source that enumerates a whole tree still yields exactly
+ * the project's markdown here. That is what makes handing this builder a
+ * projection a cost change rather than a scope change.
+ *
+ * Selecting the lane stays the CLI's job: this signature takes a source, never
+ * an environment. A library caller that passes nothing keeps the walk.
  */
-export async function createProjectRegistry(projectRoot) {
+export async function createProjectRegistry(projectRoot, options = {}) {
     const config = await loadConfig(projectRoot);
     const registry = await ResourceRegistry.fromCrawl({
         baseDir: projectRoot,
-        include: ['**/*.md'],
+        include: [...LINK_GRAPH_MEMBER_GLOBS],
+        // 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();
     return registry;
@@ -582,30 +738,40 @@ export async function createProjectRegistry(projectRoot) {
  * 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
@@ -636,26 +802,51 @@ function collectResourcesWithLinks(bundledResources, skillResource) {
  * and compute the output `relativePath`. Without this, non-markdown links get stripped
  * to empty `()` parentheses.
  *
- * Collision handling: if an asset's generated ID clashes with an existing markdown
- * resource (e.g. paired `config.yaml` + `config.md` both produce id `resources-config`),
- * `addResource` throws. We catch this, skip source-registry indexing for the asset,
- * and return it so the caller can synthesize a unique ID for link rewriting.
+ * Collision handling: if an asset's generated id is already taken, `addResource`
+ * throws. We catch this, skip source-registry indexing for the asset, and return
+ * it so the caller can synthesize a unique ID for link rewriting.
+ *
+ * The clash is a **path-slug** one, not an extension one. This used to claim the
+ * example was "paired `config.yaml` + `config.md`, both producing id
+ * `resources-config`" — {@link generateIdFromPath} appends the extension, so
+ * those are `config-yaml` and `config-md` and cannot collide. What does collide
+ * is two paths that flatten to the same slug: `a-b/c.html` and `a/b-c.html` are
+ * both `a-b-c-html`.
  *
- * @returns Paths of assets that could not be added to the source registry due to
- *   duplicate-ID collisions. Caller must wire these up manually.
+ * @returns The colliding asset paths, and the collisions themselves. The caller
+ *   must wire the paths up manually; the collisions are what let the
+ *   verbatim-copy diagnostic name the file that actually won the id.
  */
-async function registerBundledAssets(registry, bundledAssets) {
+async function registerBundledAssets(registry, bundledAssets, projectRoot) {
     const collidedAssets = [];
+    const collisions = [];
     if (bundledAssets.length === 0) {
-        return collidedAssets;
+        return { collidedAssets, collisions };
     }
     for (const assetPath of bundledAssets) {
         try {
-            await registry.addResource(assetPath);
+            // `addResource` parses the file, so it READS it — which makes this the first
+            // place a build touches a linked asset, and the place an unreadable one
+            // actually fails. It reported a bare `EACCES … open '/abs/path'` with no
+            // skill named and no remedy: the same shape as the copiers, one step
+            // earlier, and the step that fires first.
+            await withFsAttribution(`linked file ${issueLocation(assetPath, projectRoot) || '.'}`, () => registry.addResource(assetPath), 
+            // The file is read to discover its links before anything is copied, so
+            // naming the copy would point past the step that actually failed.
+            'read while collecting the files this skill links to', READ_REMEDY);
         }
         catch (error) {
-            if (error instanceof Error && error.message.startsWith('Duplicate resource ID')) {
+            // `addResource` (singular) THROWS on a collision and — unlike
+            // `addResources` — records nothing in the registry's collision log. So
+            // this catch is the ONLY place a bundled-asset collision is ever
+            // observable; drop the structured error here and the fact is gone.
+            if (error instanceof DuplicateResourceIdError) {
                 collidedAssets.push(assetPath);
+                collisions.push({
+                    id: error.id,
+                    existingPath: error.existingPath,
+                    conflictingPath: error.conflictingPath,
+                });
             }
             else {
                 throw error;
@@ -663,7 +854,7 @@ async function registerBundledAssets(registry, bundledAssets) {
         }
     }
     registry.resolveLinks();
-    return collidedAssets;
+    return { collidedAssets, collisions };
 }
 /**
  * Manually set `resolvedId` on links pointing to collided assets.
@@ -798,9 +989,23 @@ function applyFilesEntriesToPathMap(filesConfig, projectRoot, outputPath, pathMa
         // joinUnderRoot guards against a dest escaping the output dir (zip-slip class),
         // defense-in-depth beyond the schema refine on SkillFileEntry.dest.
         const absoluteDest = safePath.joinUnderRoot(outputPath, fileEntry.dest);
-        // Validate source exists at build time
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- source path from validated config
-        if (!existsSync(absoluteSource)) {
+        // Validate source exists at build time.
+        //
+        // `statSync` in a guard, not `existsSync`: `existsSync` swallows EACCES and
+        // answers FALSE, so a source the process cannot REACH — one under a directory
+        // it may not traverse — was reported as "does not exist", and for a `dist/`
+        // path `buildArtifactHint` then told the author to run a build that would not
+        // 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 {
+            statSync(absoluteSource);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                const reason = error instanceof Error ? error.message : String(error);
+                throw new Error(`files entry for skill '${skillName}': source '${fileEntry.source}' could not be read: ${reason}. ` +
+                    `Check the file's permissions and ownership, and that every directory above it is traversable.`);
+            }
             throw new Error(`files entry for skill '${skillName}': source '${fileEntry.source}' does not exist.${buildArtifactHint(fileEntry.source)}`);
         }
         // If this source was auto-discovered, override its destination; otherwise add it
@@ -933,21 +1138,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.
  *
@@ -1132,32 +1322,175 @@ 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
+    // copier in the packager — and it was the last one still letting a raw errno be
+    // the build's whole explanation: `EACCES: permission denied, open '/abs/path'`,
+    // with no skill named and no remedy. Easy to believe it was covered because the
+    // `files:` fix landed in this same file; it is a different function.
+    const subject = `linked file ${issueLocation(sourcePath, ctx.projectRoot) || '.'}`;
     // Ensure target directory exists
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- targetPath is constructed from validated paths
-    await mkdir(dirname(targetPath), { recursive: true });
+    await withFsAttribution(subject, async () => {
+        await mkdir(dirname(targetPath), { recursive: true });
+    });
     const lower = sourcePath.toLowerCase();
     const isMarkdown = lower.endsWith('.md');
     const isHtml = lower.endsWith('.html') || lower.endsWith('.htm');
     // Non-rewritable files or rewriting disabled: plain binary copy
     if ((!isMarkdown && !isHtml) || !ctx.rewriteLinks) {
-        await copyFile(sourcePath, targetPath);
+        await withFsAttribution(subject, () => copyFile(sourcePath, targetPath));
         return;
     }
-    // Read source file
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- sourcePath is validated
-    const content = await 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);
     // Look up the resource in the "from" registry
     const resource = ctx.fromRegistry.getResource(safePath.resolve(sourcePath));
     if (!resource) {
-        // Resource not in registry — write content as-is. For HTML this is only
-        // reachable on an ID collision (e.g. page.html + page.md), where the asset
-        // is copied verbatim and its links are NOT rewritten (v1 limitation,
-        // mirrors the pre-existing asset-collision behavior).
-        ctx.warn(`Copied '${sourcePath}' verbatim without link rewriting: it is not in the resource registry ` +
-            `(typically an ID collision with a same-named markdown file). Source-relative links inside it are not rewritten.`);
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- targetPath is constructed from validated paths
-        await writeFile(targetPath, content, 'utf-8');
+        // Resource not in registry — write content as-is, links unrewritten.
+        //
+        // The cause used to be guessed from the basename ("typically an ID
+        // collision with a same-named markdown file"), which is a plausible
+        // hypothesis this function had no way to check, and which named no file the
+        // author could go look at. The collision is now looked up, so the message
+        // either names the winning file as an observed fact or says nothing about
+        // cause at all.
+        const winner = ctx.duplicateIdDrops.get(toForwardSlash(sourcePath));
+        ctx.warn(winner === undefined
+            ? `Copied '${sourcePath}' verbatim without link rewriting: it is not in the resource registry. ` +
+                `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, () => writeFile(targetPath, content, 'utf-8'), WRITE_ACTION);
         return;
     }
     // HTML: offset-splice link rewrite (no frontmatter, no template body rewrite).
@@ -1167,8 +1500,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.`);
         });
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- targetPath is constructed from validated paths
-        await writeFile(targetPath, rewritten, 'utf-8');
+        await withFsAttribution(subject, () => writeFile(targetPath, rewritten, 'utf-8'), WRITE_ACTION);
         return;
     }
     // Parse once via FrontmatterEditor so comments survive any frontmatter
@@ -1176,7 +1508,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
@@ -1196,8 +1534,7 @@ async function copyAndRewriteFile(sourcePath, targetPath, ctx) {
             }
         }
     }
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- targetPath is constructed from validated paths
-    await writeFile(targetPath, editor.toString(), 'utf-8');
+    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.
@@ -1251,10 +1588,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) {
@@ -1380,9 +1717,10 @@ export function generateTargetPath(filePath, basePath, strategy = 'basename', st
     // Strip prefix from relative path (if specified)
     // Works for both resource-id and preserve-path strategies
     if (stripPrefix) {
-        // Normalize separators for consistent matching
-        const normalizedRelPath = relPath.replaceAll('\\', '/');
-        const normalizedPrefix = stripPrefix.replaceAll('\\', '/').replace(/\/$/, ''); // Remove trailing slash
+        // `relPath` is already forward-slashed by `safePath.relative`; `stripPrefix`
+        // is author-written config, so its backslashes read as separators anywhere.
+        const normalizedRelPath = relPath;
+        const normalizedPrefix = toForwardSlashAnyPlatform(stripPrefix).replace(/\/$/, ''); // Remove trailing slash
         if (normalizedRelPath.startsWith(normalizedPrefix + '/')) {
             // Strip the prefix and leading slash
             relPath = normalizedRelPath.substring(normalizedPrefix.length + 1);
@@ -1422,14 +1760,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;
     }
@@ -1441,7 +1778,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) {
@@ -1522,7 +1858,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`
@@ -1547,7 +1882,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;
 }
@@ -1561,6 +1895,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);
 }
@@ -1579,7 +1922,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;
         }