@agentxm/registry-protocol 0.28.4-bootstrap.0

package/dist/src/unstable/lint/catalog/skill/manifest-keys-recognized.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `skill/manifest-keys-recognized` — `skill.json` contains only keys
+ * declared by `SkillManifestSchema`.
+ *
+ * The paired `-schema-valid` rule ignores excess properties by construction
+ * (`onExcessProperty: "ignore"`); this rule rejects them so publish never
+ * silently drops unrecognized manifest data.
+ *
+ * Allowed-keys set is derived from `SkillManifestSchema.fields` — no
+ * copy-paste of field names. A schema gain (or rename) automatically updates
+ * the allowlist.
+ *
+ * Early-return arms (no findings):
+ *
+ * - `subject.isNative === false` — non-native skills have no manifest to
+ *   check.
+ * - `subject.skillJson === undefined` / non-object — nothing to enumerate;
+ *   `skill/manifest-present` owns the absence case.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { SkillRuleContext } from "../../context.js";
+import type { AdvisoryRule } from "../../rule.js";
+export declare const manifestKeysRecognizedRule: AdvisoryRule<SkillRuleContext>;
+//# sourceMappingURL=manifest-keys-recognized.d.ts.map

package/dist/src/unstable/lint/catalog/skill/manifest-keys-recognized.js

@@ -0,0 +1,41 @@
+/**
+ * `skill/manifest-keys-recognized` — `skill.json` contains only keys
+ * declared by `SkillManifestSchema`.
+ *
+ * The paired `-schema-valid` rule ignores excess properties by construction
+ * (`onExcessProperty: "ignore"`); this rule rejects them so publish never
+ * silently drops unrecognized manifest data.
+ *
+ * Allowed-keys set is derived from `SkillManifestSchema.fields` — no
+ * copy-paste of field names. A schema gain (or rename) automatically updates
+ * the allowlist.
+ *
+ * Early-return arms (no findings):
+ *
+ * - `subject.isNative === false` — non-native skills have no manifest to
+ *   check.
+ * - `subject.skillJson === undefined` / non-object — nothing to enumerate;
+ *   `skill/manifest-present` owns the absence case.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import { SkillManifestSchema } from "@agentxm/extension-model/unstable/skills/manifest-schema";
+import { enumerateUnknownTopLevelKeys, structFieldKeys } from "../shared/schema-rule.js";
+const RULE_ID = "skill/manifest-keys-recognized";
+const SKILL_JSON = "skill.json";
+const allowedKeys = structFieldKeys(SkillManifestSchema);
+export const manifestKeysRecognizedRule = {
+    id: RULE_ID,
+    description: "skill.json uses only supported top-level fields.",
+    kind: "advisory",
+    severity: "error",
+    check: (context) => {
+        if (!context.subject.isNative) {
+            return Effect.succeed([]);
+        }
+        return Effect.succeed(enumerateUnknownTopLevelKeys(RULE_ID, "error", SKILL_JSON, allowedKeys, context.subject.skillJson));
+    },
+};
+//# sourceMappingURL=manifest-keys-recognized.js.map

package/dist/src/unstable/lint/catalog/skill/manifest-present.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `skill/manifest-present` — native skills must have a `skill.json` at the
+ * package root.
+ *
+ * Reads through `context.packageFiles` (package-root accessor) rather than
+ * `context.files` (content-root accessor). For native skills, the package
+ * root contains `skill.json` and a `src/` directory holding the skill
+ * content; `context.files` is rooted at `src/`, so `skill.json` is only
+ * reachable via `packageFiles`.
+ *
+ * Native-only via `check` early-return: when `subject.isNative === false`
+ * (managed-external skills without a declared manifest), the rule produces
+ * no findings. No separate `applies` predicate per
+ * the lint design.
+ *
+ * Advisory-only — scaffolding a manifest is a user-authored action.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { SkillRuleContext } from "../../context.js";
+export declare const manifestPresentRule: import("../../rule.ts").AdvisoryRule<SkillRuleContext<import("../../context.js").SkillContent>>;
+//# sourceMappingURL=manifest-present.d.ts.map

package/dist/src/unstable/lint/catalog/skill/manifest-present.js

@@ -0,0 +1,32 @@
+/**
+ * `skill/manifest-present` — native skills must have a `skill.json` at the
+ * package root.
+ *
+ * Reads through `context.packageFiles` (package-root accessor) rather than
+ * `context.files` (content-root accessor). For native skills, the package
+ * root contains `skill.json` and a `src/` directory holding the skill
+ * content; `context.files` is rooted at `src/`, so `skill.json` is only
+ * reachable via `packageFiles`.
+ *
+ * Native-only via `check` early-return: when `subject.isNative === false`
+ * (managed-external skills without a declared manifest), the rule produces
+ * no findings. No separate `applies` predicate per
+ * the lint design.
+ *
+ * Advisory-only — scaffolding a manifest is a user-authored action.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import { makeManifestPresentRule } from "../shared/manifest-present.js";
+const RULE_ID = "skill/manifest-present";
+const SKILL_JSON = "skill.json";
+export const manifestPresentRule = makeManifestPresentRule({
+    ruleId: RULE_ID,
+    description: "Native skills include a root skill.json manifest.",
+    manifestFile: SKILL_JSON,
+    missingMessage: "skill.json is missing for this native skill. Create skill.json with the required manifest fields (`owner`, `type`, `name`, `version`).",
+    getFiles: (context) => context.packageFiles,
+    applies: (context) => context.subject.isNative,
+});
+//# sourceMappingURL=manifest-present.js.map

package/dist/src/unstable/lint/catalog/skill/manifest-schema-valid.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `skill/manifest-schema-valid` — `skill.json` conforms to
+ * `SkillManifestSchema`.
+ *
+ * Delegates to Effect Schema. Issues map 1:1 to findings via
+ * `issuesToFindings`.
+ *
+ * Early-return arms (no findings):
+ *
+ * - `subject.isNative === false` — non-native skills have no manifest to
+ *   check (complement of `skill/manifest-present`).
+ * - `subject.skillJson === undefined` — manifest is absent (covered by
+ *   `skill/manifest-present`).
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { SkillRuleContext } from "../../context.js";
+import type { AdvisoryRule } from "../../rule.js";
+export declare const manifestSchemaValidRule: AdvisoryRule<SkillRuleContext>;
+//# sourceMappingURL=manifest-schema-valid.d.ts.map

package/dist/src/unstable/lint/catalog/skill/manifest-schema-valid.js

@@ -0,0 +1,36 @@
+/**
+ * `skill/manifest-schema-valid` — `skill.json` conforms to
+ * `SkillManifestSchema`.
+ *
+ * Delegates to Effect Schema. Issues map 1:1 to findings via
+ * `issuesToFindings`.
+ *
+ * Early-return arms (no findings):
+ *
+ * - `subject.isNative === false` — non-native skills have no manifest to
+ *   check (complement of `skill/manifest-present`).
+ * - `subject.skillJson === undefined` — manifest is absent (covered by
+ *   `skill/manifest-present`).
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import { SkillManifestSchema } from "@agentxm/extension-model/unstable/skills/manifest-schema";
+import { schemaDecodeFindings } from "../shared/schema-rule.js";
+const RULE_ID = "skill/manifest-schema-valid";
+const SKILL_JSON = "skill.json";
+export const manifestSchemaValidRule = {
+    id: RULE_ID,
+    description: "skill.json defines a valid skill manifest.",
+    kind: "advisory",
+    severity: "error",
+    check: (context) => {
+        if (!context.subject.isNative) {
+            // Non-native skills have no skill.json to schema-validate. The
+            // presence rule (manifest-present) does not fire for non-native either.
+            return schemaDecodeFindings(RULE_ID, "error", SKILL_JSON, SkillManifestSchema, undefined);
+        }
+        return schemaDecodeFindings(RULE_ID, "error", SKILL_JSON, SkillManifestSchema, context.subject.skillJson);
+    },
+};
+//# sourceMappingURL=manifest-schema-valid.js.map

package/dist/src/unstable/lint/catalog/skill/recommended-packs-valid.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `skill/recommended-packs-valid` — recommended packs are bare FQNs, never
+ * version-ranged specs. See `../shared/recommended-packs-rules.ts`.
+ */
+import type { SkillRuleContext } from "../../context.js";
+import type { AdvisoryRule } from "../../rule.js";
+export declare const recommendedPacksValidRule: AdvisoryRule<SkillRuleContext>;
+//# sourceMappingURL=recommended-packs-valid.d.ts.map

package/dist/src/unstable/lint/catalog/skill/recommended-packs-valid.js

@@ -0,0 +1,12 @@
+/**
+ * `skill/recommended-packs-valid` — recommended packs are bare FQNs, never
+ * version-ranged specs. See `../shared/recommended-packs-rules.ts`.
+ */
+import { MANIFEST_FILENAME } from "@agentxm/extension-model/unstable/skills/manifest-schema";
+import { makeRecommendedPacksValidRule } from "../shared/recommended-packs-rules.js";
+export const recommendedPacksValidRule = makeRecommendedPacksValidRule({
+    namespace: "skill",
+    manifestFile: MANIFEST_FILENAME,
+    manifestJson: (context) => context.subject.skillJson,
+});
+//# sourceMappingURL=recommended-packs-valid.js.map

package/dist/src/unstable/lint/catalog/skill/skill-md-present.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `skill/skill-md-present` — every skill must have a `SKILL.md` at its root.
+ *
+ * Applies to every skill context (native and non-native). Upstream-required
+ * by the agentskills specification; also the precondition for the
+ * `skill/frontmatter-parseable` cascade.
+ *
+ * Advisory-only (no autofix). Scaffolding `SKILL.md` requires user-authored
+ * content and is not a meaning-preserving normalization.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { SkillRuleContext } from "../../context.js";
+import type { AdvisoryRule } from "../../rule.js";
+export declare const skillMdPresentRule: AdvisoryRule<SkillRuleContext>;
+//# sourceMappingURL=skill-md-present.d.ts.map

package/dist/src/unstable/lint/catalog/skill/skill-md-present.js

@@ -0,0 +1,37 @@
+/**
+ * `skill/skill-md-present` — every skill must have a `SKILL.md` at its root.
+ *
+ * Applies to every skill context (native and non-native). Upstream-required
+ * by the agentskills specification; also the precondition for the
+ * `skill/frontmatter-parseable` cascade.
+ *
+ * Advisory-only (no autofix). Scaffolding `SKILL.md` requires user-authored
+ * content and is not a meaning-preserving normalization.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+const RULE_ID = "skill/skill-md-present";
+const SKILL_MD = "SKILL.md";
+export const skillMdPresentRule = {
+    id: RULE_ID,
+    description: "Skills include a root SKILL.md file.",
+    kind: "advisory",
+    severity: "error",
+    check: (context) => Effect.map(context.files.exists(SKILL_MD), (present) => {
+        if (present) {
+            return [];
+        }
+        return [
+            {
+                kind: "advisory",
+                ruleId: RULE_ID,
+                severity: "error",
+                message: "SKILL.md is missing. Create SKILL.md with the required frontmatter (`name`, `description`).",
+                location: { file: SKILL_MD },
+            },
+        ];
+    }),
+};
+//# sourceMappingURL=skill-md-present.js.map

package/dist/src/unstable/lint/catalog/skill/standalone-declaration-valid.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `skill/standalone-declaration-valid` — a manifest that opts out of standalone
+ * use names the packs it needs. See `../shared/recommended-packs-rules.ts`.
+ */
+import type { SkillRuleContext } from "../../context.js";
+import type { AdvisoryRule } from "../../rule.js";
+export declare const standaloneDeclarationValidRule: AdvisoryRule<SkillRuleContext>;
+//# sourceMappingURL=standalone-declaration-valid.d.ts.map

package/dist/src/unstable/lint/catalog/skill/standalone-declaration-valid.js

@@ -0,0 +1,12 @@
+/**
+ * `skill/standalone-declaration-valid` — a manifest that opts out of standalone
+ * use names the packs it needs. See `../shared/recommended-packs-rules.ts`.
+ */
+import { MANIFEST_FILENAME } from "@agentxm/extension-model/unstable/skills/manifest-schema";
+import { makeStandaloneDeclarationValidRule } from "../shared/recommended-packs-rules.js";
+export const standaloneDeclarationValidRule = makeStandaloneDeclarationValidRule({
+    namespace: "skill",
+    manifestFile: MANIFEST_FILENAME,
+    manifestJson: (context) => context.subject.skillJson,
+});
+//# sourceMappingURL=standalone-declaration-valid.js.map

package/dist/src/unstable/lint/catalog/skill-accessor/contexts.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `buildSkillRuleContexts` — build `SkillRuleContext[]` from a structural
+ * `installedSkills` input. The full lint workspace view
+ * (`LintWorkspaceView`) satisfies this by construction.
+ *
+ * The minimal shape is **exactly** the set of fields the function reads per
+ * installed skill:
+ *
+ * - `isNative` — whether the skill is expected to expose `skill.json`
+ *   (registry-installed natives: `true`; managed external: `false`).
+ * - `skillJson` — pre-decoded `skill.json` when present (caller decodes
+ *   once per skill, so rules don't re-read + re-parse).
+ * - `displayRoot` — posix-relative root used by the renderer; the caller
+ *   picks per provenance (see the table below).
+ * - `files` — the pre-bound content-root `SkillFileAccessor` (rooted at the
+ *   directory containing `SKILL.md`). The caller chooses VFT or
+ *   platform-backed.
+ * - `packageFiles` — the pre-bound package-root `SkillFileAccessor` (rooted
+ *   at the directory containing `skill.json` for native skills). For
+ *   non-native skills, callers MAY alias `files`.
+ *
+ * Provenance → `displayRoot` table:
+ *
+ * | Surface                                   | `displayRoot`                                 |
+ * | ----------------------------------------- | --------------------------------------------- |
+ * | Publish                                   | `""`                                          |
+ * | Registry-installed native skill           | `agent_extensions/<source>/<@owner>/skills/<name>/src` |
+ * | Portable acquired skill                   | `agent_extensions/<source>/<source-full-name>`         |
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { SkillFileAccessor, SkillRuleContext } from "../../context.js";
+/**
+ * Minimal structural shape `buildSkillRuleContexts` needs per installed
+ * skill. The full lint workspace view exposes
+ * `installedSkills: ReadonlyArray<InstalledSkillInfo>`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface InstalledSkillInfo {
+    readonly isNative: boolean;
+    readonly skillJson: unknown;
+    readonly expectedName?: string;
+    readonly displayRoot: string;
+    readonly files: SkillFileAccessor;
+    readonly packageFiles: SkillFileAccessor;
+}
+/**
+ * Project an input's `installedSkills` into `SkillRuleContext`s with their
+ * `displayRoot` and `subject` fields pre-populated.
+ *
+ * Publish callers bypass this helper and construct a single context directly
+ * — they have exactly one skill in play and no workspace.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const buildSkillRuleContexts: (input: {
+    readonly installedSkills: ReadonlyArray<InstalledSkillInfo>;
+}) => ReadonlyArray<SkillRuleContext>;
+//# sourceMappingURL=contexts.d.ts.map

package/dist/src/unstable/lint/catalog/skill-accessor/contexts.js

@@ -0,0 +1,55 @@
+/**
+ * `buildSkillRuleContexts` — build `SkillRuleContext[]` from a structural
+ * `installedSkills` input. The full lint workspace view
+ * (`LintWorkspaceView`) satisfies this by construction.
+ *
+ * The minimal shape is **exactly** the set of fields the function reads per
+ * installed skill:
+ *
+ * - `isNative` — whether the skill is expected to expose `skill.json`
+ *   (registry-installed natives: `true`; managed external: `false`).
+ * - `skillJson` — pre-decoded `skill.json` when present (caller decodes
+ *   once per skill, so rules don't re-read + re-parse).
+ * - `displayRoot` — posix-relative root used by the renderer; the caller
+ *   picks per provenance (see the table below).
+ * - `files` — the pre-bound content-root `SkillFileAccessor` (rooted at the
+ *   directory containing `SKILL.md`). The caller chooses VFT or
+ *   platform-backed.
+ * - `packageFiles` — the pre-bound package-root `SkillFileAccessor` (rooted
+ *   at the directory containing `skill.json` for native skills). For
+ *   non-native skills, callers MAY alias `files`.
+ *
+ * Provenance → `displayRoot` table:
+ *
+ * | Surface                                   | `displayRoot`                                 |
+ * | ----------------------------------------- | --------------------------------------------- |
+ * | Publish                                   | `""`                                          |
+ * | Registry-installed native skill           | `agent_extensions/<source>/<@owner>/skills/<name>/src` |
+ * | Portable acquired skill                   | `agent_extensions/<source>/<source-full-name>`         |
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+// -----------------------------------------------------------------------------
+// buildSkillRuleContexts
+// -----------------------------------------------------------------------------
+/**
+ * Project an input's `installedSkills` into `SkillRuleContext`s with their
+ * `displayRoot` and `subject` fields pre-populated.
+ *
+ * Publish callers bypass this helper and construct a single context directly
+ * — they have exactly one skill in play and no workspace.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const buildSkillRuleContexts = (input) => input.installedSkills.map((info) => ({
+    subject: {
+        isNative: info.isNative,
+        skillJson: info.skillJson,
+        ...(info.expectedName === undefined ? {} : { expectedName: info.expectedName }),
+    },
+    files: info.files,
+    packageFiles: info.packageFiles,
+    displayRoot: info.displayRoot,
+}));
+//# sourceMappingURL=contexts.js.map

package/dist/src/unstable/lint/catalog/skill-accessor/vft.d.ts

@@ -0,0 +1,77 @@
+/**
+ * VFT-backed `SkillFileAccessor` for publish callers.
+ *
+ * A Virtual File Tree (VFT) is an in-memory representation of an extracted
+ * archive — the registry publish pipeline extracts an upload into a VFT, then
+ * passes that tree into Phase 4 decode/lint. The VFT's schema and bounds
+ * (max size, file count, path depth) are owned by the registry extract phase
+ * (Phase 4 concern); this accessor treats the tree as a read-only
+ * `path -> Uint8Array` map and enforces its own rooted-read + no-`..`-escape
+ * invariants at the rule boundary.
+ *
+ * Bounds enforcement here:
+ *
+ * - Paths are normalized to posix, `./` prefixes are stripped.
+ * - Empty path resolves to the accessor root itself (useful for
+ *   `location.file = ""` findings but not currently exercised by the v1
+ *   catalog).
+ * - Any path containing a `..` segment raises `FileAccessError {
+ *   reason: "path-escape" }` from `readBytes` and resolves to `false` from
+ *   `exists`.
+ * - Absolute paths (starting with `/` or a Windows drive letter) are
+ *   treated as escape attempts.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { SkillFileAccessor } from "../../context.js";
+/**
+ * Minimal shape of a Virtual File Tree consumed by the accessor.
+ *
+ * The registry VFT (Phase 4, this-repo) MUST satisfy this interface. The
+ * registry may (and will) expose additional methods — file count, archive
+ * bounds, iteration — but those are the extract phase's concern.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface VFTNode {
+    /**
+     * Whether the given posix path points to a file within the tree.
+     */
+    readonly hasFile: (posixPath: string) => boolean;
+    /**
+     * Return the bytes for the given posix path, or `undefined` when the path
+     * does not resolve to a file (missing, directory, or outside the tree).
+     */
+    readonly getFile: (posixPath: string) => Uint8Array | undefined;
+}
+/**
+ * Build a VFT-backed `SkillFileAccessor` rooted at the tree's root.
+ *
+ * Callers that root the skill at a sub-path of the archive should pre-strip
+ * that sub-path before constructing the tree — the accessor enforces no
+ * `..` escape above the root it was given.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const makeVftSkillFileAccessor: (tree: VFTNode) => SkillFileAccessor;
+/**
+ * Build a VFT-backed `SkillFileAccessor` rooted at a sub-path of the tree.
+ *
+ * Publish callers use this when the archive layout nests the skill content
+ * under a directory (for native managed skills: `src/` holds the content
+ * accessor root while the archive root holds the package). The
+ * `prefix` is a posix path relative to the tree root; every rule-supplied
+ * path is resolved as `<prefix>/<path>` before dispatching to the tree.
+ *
+ * Bounds enforcement matches {@link makeVftSkillFileAccessor} — path traversal
+ * checks run on the caller-supplied path before the prefix is applied, so
+ * rules still cannot escape above the scoped root.
+ *
+ * The prefix itself is normalized posix (leading `./` and trailing `/` stripped);
+ * an empty or `.` prefix is equivalent to {@link makeVftSkillFileAccessor}.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const makeVftSkillFileAccessorScoped: (tree: VFTNode, prefix: string) => SkillFileAccessor;
+//# sourceMappingURL=vft.d.ts.map

package/dist/src/unstable/lint/catalog/skill-accessor/vft.js

@@ -0,0 +1,135 @@
+/**
+ * VFT-backed `SkillFileAccessor` for publish callers.
+ *
+ * A Virtual File Tree (VFT) is an in-memory representation of an extracted
+ * archive — the registry publish pipeline extracts an upload into a VFT, then
+ * passes that tree into Phase 4 decode/lint. The VFT's schema and bounds
+ * (max size, file count, path depth) are owned by the registry extract phase
+ * (Phase 4 concern); this accessor treats the tree as a read-only
+ * `path -> Uint8Array` map and enforces its own rooted-read + no-`..`-escape
+ * invariants at the rule boundary.
+ *
+ * Bounds enforcement here:
+ *
+ * - Paths are normalized to posix, `./` prefixes are stripped.
+ * - Empty path resolves to the accessor root itself (useful for
+ *   `location.file = ""` findings but not currently exercised by the v1
+ *   catalog).
+ * - Any path containing a `..` segment raises `FileAccessError {
+ *   reason: "path-escape" }` from `readBytes` and resolves to `false` from
+ *   `exists`.
+ * - Absolute paths (starting with `/` or a Windows drive letter) are
+ *   treated as escape attempts.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+/**
+ * Build a VFT-backed `SkillFileAccessor` rooted at the tree's root.
+ *
+ * Callers that root the skill at a sub-path of the archive should pre-strip
+ * that sub-path before constructing the tree — the accessor enforces no
+ * `..` escape above the root it was given.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const makeVftSkillFileAccessor = (tree) => {
+    return {
+        exists: (path) => {
+            const normalized = normalizeAndCheck(path);
+            if (normalized.kind !== "ok") {
+                return Effect.succeed(false);
+            }
+            return Effect.succeed(tree.hasFile(normalized.path));
+        },
+        readBytes: (path) => {
+            const normalized = normalizeAndCheck(path);
+            if (normalized.kind === "escape") {
+                return failFileAccess(path, "path-escape", `path escapes the accessor root: ${path}`);
+            }
+            const bytes = tree.getFile(normalized.path);
+            if (bytes === undefined) {
+                return failFileAccess(path, "read-error", `file not found at ${path}`);
+            }
+            return Effect.succeed(bytes);
+        },
+    };
+};
+/**
+ * Build a VFT-backed `SkillFileAccessor` rooted at a sub-path of the tree.
+ *
+ * Publish callers use this when the archive layout nests the skill content
+ * under a directory (for native managed skills: `src/` holds the content
+ * accessor root while the archive root holds the package). The
+ * `prefix` is a posix path relative to the tree root; every rule-supplied
+ * path is resolved as `<prefix>/<path>` before dispatching to the tree.
+ *
+ * Bounds enforcement matches {@link makeVftSkillFileAccessor} — path traversal
+ * checks run on the caller-supplied path before the prefix is applied, so
+ * rules still cannot escape above the scoped root.
+ *
+ * The prefix itself is normalized posix (leading `./` and trailing `/` stripped);
+ * an empty or `.` prefix is equivalent to {@link makeVftSkillFileAccessor}.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const makeVftSkillFileAccessorScoped = (tree, prefix) => {
+    const normalizedPrefix = normalizePrefix(prefix);
+    if (normalizedPrefix === "") {
+        return makeVftSkillFileAccessor(tree);
+    }
+    const join = (path) => path === "" ? normalizedPrefix : `${normalizedPrefix}/${path}`;
+    return {
+        exists: (path) => {
+            const normalized = normalizeAndCheck(path);
+            if (normalized.kind !== "ok") {
+                return Effect.succeed(false);
+            }
+            return Effect.succeed(tree.hasFile(join(normalized.path)));
+        },
+        readBytes: (path) => {
+            const normalized = normalizeAndCheck(path);
+            if (normalized.kind === "escape") {
+                return failFileAccess(path, "path-escape", `path escapes the accessor root: ${path}`);
+            }
+            const bytes = tree.getFile(join(normalized.path));
+            if (bytes === undefined) {
+                return failFileAccess(path, "read-error", `file not found at ${path}`);
+            }
+            return Effect.succeed(bytes);
+        },
+    };
+};
+const normalizePrefix = (prefix) => {
+    const stripped = prefix.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+    if (stripped === "" || stripped === ".") {
+        return "";
+    }
+    return stripped;
+};
+const normalizeAndCheck = (path) => {
+    if (path === "" || path === "." || path === "./") {
+        return { kind: "ok", path: "" };
+    }
+    // Windows drive letters (`C:/`) and absolute posix paths both count as
+    // escape attempts at a skill-rooted accessor.
+    if (/^[a-z]:[\\/]/i.test(path) || path.startsWith("/") || path.startsWith("\\")) {
+        return { kind: "escape" };
+    }
+    const normalized = path.replace(/\\/g, "/").replace(/^\.\//, "");
+    const segments = normalized.split("/");
+    for (const segment of segments) {
+        if (segment === "..") {
+            return { kind: "escape" };
+        }
+    }
+    return { kind: "ok", path: normalized };
+};
+const failFileAccess = (path, reason, message) => Effect.fail({
+    _tag: "FileAccessError",
+    path,
+    reason,
+    message,
+});
+//# sourceMappingURL=vft.js.map

package/dist/src/unstable/lint/catalog/skill.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `skill/*` rule catalog.
+ *
+ * Per the lint design, registry publish and `axm lint`
+ * run exactly these rules against each skill context:
+ *
+ * | ID                                     | Severity | Autofix |
+ * | -------------------------------------- | -------- | ------- |
+ * | `skill/skill-md-present`               | error    | —       |
+ * | `skill/manifest-present`               | error    | —       |
+ * | `skill/frontmatter-parseable`          | error    | —       |
+ * | `skill/frontmatter-standard-valid`      | error    | —       |
+ * | `skill/manifest-schema-valid`          | error    | —       |
+ * | `skill/manifest-keys-recognized`       | error    | —       |
+ * | `skill/standalone-declaration-valid`   | warning  | —       |
+ * | `skill/recommended-packs-valid`        | warning  | —       |
+ *
+ * The last two come from `catalog/shared/recommended-packs-rules.ts`; every
+ * non-pack catalog registers the same pair against its own manifest.
+ *
+ * All ship `kind: "advisory"`. Native-vs-non-native applicability is
+ * expressed via `check` early-return (no separate `applies` predicate); see
+ * each rule's module for the guard.
+ *
+ * Rule ids are **registered with the lint config allowlist at module-load
+ * time**, so importing this catalog extends the set of accepted
+ * `axm.json` `lint.rules` keys. Consumers that never import the
+ * catalog (the registry Worker bundle for `pack`-only routes, e.g.) don't pay
+ * the registration cost.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type { LintRule } from "../rule.js";
+import type { SkillRuleContext } from "../context.js";
+/**
+ * Ordered v1 `skill/*` rule catalog. Declaration order is the evaluation
+ * order within a single `evaluateContexts` call (deterministic ordering is
+ * test-observable; see `evaluate.ts`).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const skillRules: ReadonlyArray<LintRule<SkillRuleContext>>;
+//# sourceMappingURL=skill.d.ts.map