@agent-loom/loom 1.0.2 → 1.0.3

package/dist/manifest.js

@@ -4,40 +4,368 @@
  * Parses manifest.yaml files and resolves $ref / file / registry references
  * to produce a fully resolved manifest ready for rendering.
  */
-import { readFile, readdir } from 'node:fs/promises';
-import { resolve, dirname, basename, extname, relative, join } from 'node:path';
+import { readFile, readdir, stat, realpath } from 'node:fs/promises';
+import { resolve, dirname, basename, extname, relative, join, isAbsolute } from 'node:path';
 import yaml from 'js-yaml';
-import { isSharedRef, isLocalFileRef, isRegistrySkillRef, isMcpInlineDef, } from './types.js';
+import { isSharedRef, isLocalFileRef, isRegistrySkillRef, isDiscoverSkillsRef, isDiscoverAgentRef, isMcpInlineDef, } from './types.js';
+import { parseFrontmatterRaw, stripFrontmatter } from './util/frontmatter.js';
+import { resolveBinaryToCache } from './util/binary-cache.js';
+// =============================================================================
+// Path safety (security primitives)
+//
+// Manifest-controlled paths flow into renderers and writers. A malicious or
+// hand-edited template can declare `$ref: ../../.vscode/pwned` or
+// `name: ../../escape` and cause loom to read or write outside the workspace.
+// These helpers close that vector at the resolver layer so downstream code
+// (renderers, writers) never sees an unsafe path.
+//
+// Recovered from PR #134 cycle 1-3 review (commits dc9c4dd, 2432428, b16ef3c)
+// during the foundation-first carve in 2026-05.
+// =============================================================================
+/**
+ * Validate that `name` is safe to use as a single filesystem path
+ * component (skill dir, prompt filename, agent slug). Frontmatter
+ * `name:` values flow into renderer paths; a malicious template can
+ * declare `name: ../../../.vscode/pwned` and have the renderer write
+ * outside the workspace. This helper closes that vector at the
+ * resolver layer so renderers never see an unsafe name.
+ */
+export function isSafePathSegment(name) {
+    if (typeof name !== 'string' || name.length === 0)
+        return false;
+    if (name === '.' || name === '..')
+        return false;
+    if (name.includes('/') || name.includes('\\'))
+        return false;
+    // eslint-disable-next-line no-control-regex
+    if (name.includes('\0'))
+        return false;
+    // Reject Windows drive letters (e.g. `C:`) used as directory names.
+    if (/^[A-Za-z]:/.test(name))
+        return false;
+    return true;
+}
+function unsafePathSegmentMessage(kind, name, source) {
+    return `[loom] Unsafe ${kind} name "${name}" from ${source}: names must be a single filesystem path segment.`;
+}
+function assertSafePathSegment(kind, name, source) {
+    if (!isSafePathSegment(name)) {
+        throw new Error(unsafePathSegmentMessage(kind, name, source));
+    }
+    return name;
+}
+/**
+ * Resolve `ref` against `root`, then assert the result stays under
+ * `root` after symlink resolution. Throws on escape (absolute paths,
+ * `..` traversal, symlinks pointing out). Use for every manifest-
+ * controlled relative path before reading or writing it.
+ *
+ * Skips the realpath check if the file does not yet exist (e.g. a
+ * renderer about to write to it); returns the lexically-resolved path
+ * in that case. Callers that need realpath safety on an existing file
+ * should call after stat.
+ */
+export async function safeJoinUnder(root, ref) {
+    if (typeof ref !== 'string' || ref.length === 0) {
+        throw new Error(`manifest path safety: empty reference`);
+    }
+    if (isAbsolute(ref)) {
+        throw new Error(`manifest path safety: absolute paths not allowed: ${ref}`);
+    }
+    const candidate = resolve(root, ref);
+    let realRoot;
+    try {
+        realRoot = await realpath(root);
+    }
+    catch {
+        realRoot = resolve(root);
+    }
+    let realCandidate;
+    try {
+        realCandidate = await realpath(candidate);
+    }
+    catch {
+        // Doesn't exist yet -- fall back to lexical containment check.
+        realCandidate = candidate;
+    }
+    const rel = relative(realRoot, realCandidate);
+    if (rel === '' || rel === '.' || (!rel.startsWith('..') && !isAbsolute(rel))) {
+        return realCandidate;
+    }
+    throw new Error(`manifest path safety: "${ref}" escapes its root (${root})`);
+}
 // =============================================================================
 // Parse
 // =============================================================================
 /**
- * Parse a manifest.yaml file into a typed Manifest object.
+ * Parse a manifest into a typed Manifest object.
+ *
+ * Accepts either:
+ *   - A path to a manifest file (`.../manifest.yaml` or `.../dobby.yaml`)
+ *   - A path to a directory containing one of those filenames
+ *
+ * When given a directory, prefers `manifest.yaml`; falls back to
+ * `dobby.yaml` (with a one-time deprecation note). If both are
+ * present, prefers `manifest.yaml` and warns.
+ *
+ * Per U5/U6, field-name and layout aliases are normalized at parse time:
+ *   - `mcpServers:` -> `mcp:`
+ *   - `sparseCheckout:` -> `paths:` (+ `sparse: true`)
+ *   - `team:` -> `template:`
+ *   - flat top-level resources -> wrapped in synthetic `contents:`
+ * Each kind of alias triggers a once-per-session deprecation warning.
+ * See normalizeManifestAliases.
  */
-export async function parseManifest(manifestPath) {
+export async function parseManifest(pathOrDir) {
+    const manifestPath = await resolveManifestPath(pathOrDir);
     const content = await readFile(manifestPath, 'utf-8');
     const raw = yaml.load(content);
-    return raw;
+    const normalized = normalizeManifestAliases(raw, manifestPath);
+    return normalized;
+}
+/**
+ * Resolve a path-or-directory argument into the actual manifest file path.
+ *
+ * - If the path is a file, returns it unchanged.
+ * - If the path is a directory, probes `manifest.yaml` first (canonical),
+ *   then `dobby.yaml` (legacy alias). Logs a one-time deprecation
+ *   warning when falling back to `dobby.yaml`.
+ * - Throws if neither is found.
+ *
+ * Exported so callers (e.g. validate.ts) can probe for a manifest using
+ * the same rules without re-reading the file.
+ */
+export async function resolveManifestPath(pathOrDir) {
+    let isDir = false;
+    try {
+        const s = await stat(pathOrDir);
+        isDir = s.isDirectory();
+    }
+    catch {
+        // Path doesn't exist; fall through and let the file read fail with the
+        // original ENOENT so the caller sees the same error as before.
+        return pathOrDir;
+    }
+    if (!isDir)
+        return pathOrDir;
+    const canonical = join(pathOrDir, 'manifest.yaml');
+    const dobby = join(pathOrDir, 'dobby.yaml');
+    const hasCanonical = await fileExists(canonical);
+    const hasDobby = await fileExists(dobby);
+    if (hasCanonical && hasDobby) {
+        console.warn(`[loom] Both manifest.yaml and dobby.yaml present in ${pathOrDir}; ` +
+            `using manifest.yaml. Remove dobby.yaml to silence this warning.`);
+        return canonical;
+    }
+    if (hasCanonical)
+        return canonical;
+    if (hasDobby) {
+        logFilenameDeprecation(pathOrDir);
+        return dobby;
+    }
+    throw new Error(`No manifest.yaml or dobby.yaml found in ${pathOrDir}`);
+}
+async function fileExists(path) {
+    try {
+        const s = await stat(path);
+        return s.isFile();
+    }
+    catch {
+        return false;
+    }
 }
 // =============================================================================
-// Resolve
+// Field-name aliases (U5: dobby-style -> canonical)
 // =============================================================================
 /**
- * Resolve all $ref, file, and registry references in a parsed manifest.
+ * One-time deprecation log dedup, keyed by alias name. Each deprecated
+ * field is reported at most once per process, no matter how many
+ * manifests use it. Tests can clear the set via
+ * `_resetAliasDeprecationsForTest`.
+ */
+const ALIAS_DEPRECATION_LOGGED = new Set();
+/**
+ * Top-level fields that, when present at the manifest root and `contents:`
+ * is absent, signal a flat layout (dobby-style). These are hoisted into
+ * a synthetic `contents:` wrapper by normalizeManifestAliases so the
+ * resolver doesn't need a separate code path. `prerequisites:` stays at
+ * the root since that's the canonical location.
+ */
+const FLAT_LAYOUT_RESOURCES = [
+    'instructions',
+    'skills',
+    'agents',
+    'mcp',
+    'mcpServers',
+    'repos',
+    'prompts',
+];
+/**
+ * Walk a freshly-loaded manifest YAML object and rename dobby-style
+ * field names to loom's canonical names. The input object is shallow-
+ * cloned; the caller's object is never mutated. Each alias triggers a
+ * one-time deprecation warning per session.
  *
- * @param manifest - Parsed manifest (from parseManifest)
- * @param templateDir - Absolute path to the template directory (contains manifest.yaml)
- * @param registryRoot - Absolute path to the registry root (contains shared/)
+ * Aliases supported:
+ *   - top-level `team:` -> `template:` (only when `template:` absent)
+ *   - top-level `mcpServers:` -> `mcp:` (also recognized inside `contents:`)
+ *   - per-repo entry: `sparseCheckout:` -> `paths:` (also sets
+ *     `sparse: true` when no explicit `sparse:` key is given)
+ *   - flat layout: top-level `instructions:` / `skills:` / `agents:` /
+ *     `mcp:` / `repos:` / `prompts:` are hoisted into a synthetic
+ *     `contents:` block when `contents:` is absent. Per U6, this
+ *     collapses the dobby-format flat layout into the canonical
+ *     contents:-wrapped layout that resolveManifest expects.
+ *
+ * Filename-level aliases (e.g. dobby.yaml -> manifest.yaml) are
+ * handled in `resolveManifestPath` before this function runs.
+ */
+export function normalizeManifestAliases(raw, sourcePath) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return raw;
+    }
+    let out = { ...raw };
+    // U6: `team:` -> `template:` alias (used by dobby.yaml). Only fires
+    // when `template:` is absent so canonical manifests are untouched.
+    if ('team' in out && !('template' in out)) {
+        logAliasDeprecation('team', 'template', sourcePath);
+        out.template = out.team;
+        delete out.team;
+    }
+    // U6: flat layout -> synthetic `contents:` wrapper. Triggered when
+    // `contents:` is absent but at least one resource field lives at the
+    // root. After hoisting, the rest of normalize and resolveManifest
+    // operate on the unified shape.
+    if (!('contents' in out)) {
+        const hoisted = {};
+        let hadAny = false;
+        for (const field of FLAT_LAYOUT_RESOURCES) {
+            if (field in out) {
+                hoisted[field] = out[field];
+                delete out[field];
+                hadAny = true;
+            }
+        }
+        if (hadAny) {
+            logAliasDeprecation('flat-layout', 'contents', sourcePath);
+            // U6: implicit filesystem discovery for skills and agents in
+            // flat-layout dobby-style manifests. Matches the prior dobby
+            // adapter's behavior so existing dobby checkouts render skills
+            // and agents from disk without requiring dobby.yaml edits.
+            // Order encodes precedence: shared first, team second (later
+            // dirs override earlier on duplicate names; see
+            // resolveSkillEntries / discoverSkillsFromDirs).
+            if (!('skills' in hoisted)) {
+                hoisted.skills = [{ discover: ['../_shared/skills', './skills'] }];
+            }
+            if (!('agents' in hoisted)) {
+                hoisted.agents = [{ discover: ['./agents'] }];
+            }
+            out.contents = hoisted;
+            // Defaults for fields the canonical schema requires but flat-
+            // layout dobby.yaml typically omits. Existing values are kept.
+            if (!('version' in out))
+                out.version = '1.0.0';
+            if (!('targets' in out))
+                out.targets = ['copilot'];
+        }
+    }
+    // Top-level `mcpServers:` (legacy dobby flat layout, kept for
+    // safety in case flat hoisting was already done by an earlier pass).
+    if ('mcpServers' in out) {
+        logAliasDeprecation('mcpServers', 'mcp', sourcePath);
+        if (!('mcp' in out))
+            out.mcp = out.mcpServers;
+        delete out.mcpServers;
+    }
+    // Inside `contents:` (canonical nested layout, or freshly-hoisted
+    // flat layout): mcpServers -> mcp, walk repos for sparseCheckout
+    // -> paths.
+    if (typeof out.contents === 'object' &&
+        out.contents !== null &&
+        !Array.isArray(out.contents)) {
+        const contents = { ...out.contents };
+        if ('mcpServers' in contents) {
+            logAliasDeprecation('mcpServers', 'mcp', sourcePath);
+            if (!('mcp' in contents))
+                contents.mcp = contents.mcpServers;
+            delete contents.mcpServers;
+        }
+        if (Array.isArray(contents.repos)) {
+            contents.repos = contents.repos.map((entry) => normalizeRepoEntryAliases(entry, sourcePath));
+        }
+        out.contents = contents;
+    }
+    // Top-level `repos:` (e.g. canonical layout where repos: is at root,
+    // or a flat layout that was NOT hoisted because contents: was already
+    // present). Apply sparseCheckout normalization in place.
+    if (Array.isArray(out.repos)) {
+        out.repos = out.repos.map((entry) => normalizeRepoEntryAliases(entry, sourcePath));
+    }
+    return out;
+}
+function normalizeRepoEntryAliases(entry, sourcePath) {
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+        return entry;
+    }
+    const r = { ...entry };
+    if ('sparseCheckout' in r) {
+        logAliasDeprecation('sparseCheckout', 'paths', sourcePath);
+        if (!('paths' in r))
+            r.paths = r.sparseCheckout;
+        if (!('sparse' in r) && r.sparseCheckout != null)
+            r.sparse = true;
+        delete r.sparseCheckout;
+    }
+    return r;
+}
+function logAliasDeprecation(aliasName, canonicalName, sourcePath) {
+    if (ALIAS_DEPRECATION_LOGGED.has(aliasName))
+        return;
+    ALIAS_DEPRECATION_LOGGED.add(aliasName);
+    const where = sourcePath ? ` (manifest: ${sourcePath})` : '';
+    if (aliasName === 'flat-layout') {
+        console.warn(`[loom] Top-level resources without a 'contents:' wrapper are deprecated; ` +
+            `nest 'instructions:', 'skills:', 'agents:', 'mcp:', 'repos:', 'prompts:' ` +
+            `under 'contents:' instead.${where}`);
+        return;
+    }
+    console.warn(`[loom] Field '${aliasName}' is deprecated; use '${canonicalName}' instead.${where}`);
+}
+/**
+ * One-time deprecation log dedup for the dobby.yaml filename. Tests
+ * can clear it via `_resetAliasDeprecationsForTest`.
+ */
+function logFilenameDeprecation(dir) {
+    if (ALIAS_DEPRECATION_LOGGED.has('dobby.yaml-filename'))
+        return;
+    ALIAS_DEPRECATION_LOGGED.add('dobby.yaml-filename');
+    console.warn(`[loom] Found dobby.yaml in ${dir}; this filename is supported as an alias ` +
+        `but the canonical filename is 'manifest.yaml'. Rename to silence this warning.`);
+}
+/**
+ * Test-only: clear the once-per-session dedup so subsequent calls log
+ * again. Production code should never need to call this.
  */
-export async function resolveManifest(manifest, templateDir, registryRoot) {
+export function _resetAliasDeprecationsForTest() {
+    ALIAS_DEPRECATION_LOGGED.clear();
+}
+export async function resolveManifest(manifest, templateDir, registryRoot, options = {}) {
+    const legacyAgents = await readLegacyAgentManifests(templateDir);
+    const selectedLegacyAgents = scopeLegacyAgents(legacyAgents, options.agents);
+    const contents = mergeLegacyAgentContents(manifest.contents, selectedLegacyAgents);
+    const prerequisiteEntries = deduplicateEntries([
+        ...(manifest.prerequisites ?? []),
+        ...selectedLegacyAgents.flatMap((a) => a.manifest.prerequisites ?? []),
+    ], prereqEntryKey);
     const [instructions, skills, agents, mcp, repos, prerequisites, prompts] = await Promise.all([
-        resolveInstructions(manifest.contents.instructions ?? [], templateDir, registryRoot),
-        resolveSkills(manifest.contents.skills ?? [], templateDir),
-        resolveAgents(manifest.contents.agents ?? [], templateDir),
-        resolveMcp(manifest.contents.mcp ?? [], registryRoot),
-        resolveRepos(manifest.contents.repos ?? [], registryRoot),
-        resolvePrerequisites(manifest.prerequisites ?? [], registryRoot),
-        resolvePrompts(manifest.contents.prompts ?? [], templateDir, registryRoot),
+        resolveInstructions(contents.instructions ?? [], templateDir, registryRoot),
+        resolveSkillEntries(contents.skills ?? [], templateDir),
+        resolveAgentEntries(contents.agents ?? [], templateDir, () => { }, registryRoot),
+        resolveMcpEntries(contents.mcp ?? [], registryRoot),
+        resolveRepos(contents.repos ?? [], registryRoot),
+        resolvePrerequisites(prerequisiteEntries, registryRoot),
+        resolvePrompts(contents.prompts ?? [], templateDir, registryRoot),
     ]);
     return {
         version: manifest.version,
@@ -52,56 +380,286 @@ export async function resolveManifest(manifest, templateDir, registryRoot) {
         prerequisites,
     };
 }
+function scopeLegacyAgents(legacyAgents, selectedAgents) {
+    const wanted = new Set((selectedAgents ?? []).filter(Boolean));
+    if (wanted.size === 0)
+        return legacyAgents;
+    return legacyAgents.filter((source) => {
+        const agentId = source.manifest.agent?.id;
+        return wanted.has(source.dir) || (agentId !== undefined && wanted.has(agentId));
+    });
+}
+async function readLegacyAgentManifests(templateDir) {
+    const agentsDir = join(templateDir, 'agents');
+    let entries;
+    try {
+        entries = (await readdir(agentsDir, { withFileTypes: true }));
+    }
+    catch {
+        return [];
+    }
+    const result = [];
+    for (const entry of entries.filter((e) => e.isDirectory()).sort((a, b) => String(a.name).localeCompare(String(b.name)))) {
+        const dir = String(entry.name);
+        const manifestPath = join(agentsDir, dir, 'manifest.yaml');
+        try {
+            const s = await stat(manifestPath);
+            if (!s.isFile())
+                continue;
+            const parsed = yaml.load(await readFile(manifestPath, 'utf-8'));
+            if (parsed?.agent)
+                result.push({ dir, manifest: parsed });
+        }
+        catch {
+            continue;
+        }
+    }
+    return result;
+}
+async function readLegacyAgentManifestFromDir(agentDir) {
+    const manifestPath = join(agentDir, 'manifest.yaml');
+    try {
+        const s = await stat(manifestPath);
+        if (!s.isFile())
+            return undefined;
+        const parsed = yaml.load(await readFile(manifestPath, 'utf-8'));
+        return parsed?.agent ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function mergeLegacyAgentContents(contents, legacyAgents) {
+    if (legacyAgents.length === 0)
+        return contents;
+    const agentContents = legacyAgents.map((a) => a.manifest.contents ?? {});
+    const agentEntries = contents.agents ?? [{ discover: ['./agents'] }];
+    return {
+        ...contents,
+        instructions: [
+            ...(contents.instructions ?? []),
+            ...agentContents.flatMap((c) => c.instructions ?? []),
+        ],
+        skills: deduplicateEntries([
+            ...(contents.skills ?? []),
+            ...agentContents.flatMap((c) => c.skills ?? []),
+        ], skillEntryKey),
+        agents: agentEntries,
+        mcp: deduplicateEntries([
+            ...(contents.mcp ?? []),
+            ...agentContents.flatMap((c) => c.mcp ?? []),
+        ], mcpEntryKey),
+        repos: deduplicateEntries([
+            ...(contents.repos ?? []),
+            ...agentContents.flatMap((c) => c.repos ?? []),
+        ], repoEntryKey),
+        prompts: [
+            ...(contents.prompts ?? []),
+            ...agentContents.flatMap((c) => c.prompts ?? []),
+        ],
+    };
+}
 // =============================================================================
 // Internal resolvers
 // =============================================================================
 async function resolveInstructions(entries, templateDir, registryRoot) {
-    return Promise.all(entries.map(async (entry) => {
-        if (isSharedRef(entry)) {
-            const filePath = resolve(registryRoot, entry.$ref);
-            const content = await readFile(filePath, 'utf-8');
-            return { scope: entry.scope, content, sourcePath: entry.$ref };
+    // Per U6: instruction entries are resolved with best-effort
+    // semantics: missing `scope` defaults to '**' (was: dobby adapter
+    // hardcoded this for its catalog format) and missing files emit a
+    // warning instead of erroring. The strict reference check still
+    // lives in validate.ts for `loom validate` -- apply's job is to
+    // produce a usable workspace from the manifest it was given, even
+    // if a few files have rotted.
+    const resolved = await Promise.all(entries.map(async (entry) => {
+        const scope = (entry.scope ?? '**');
+        try {
+            if (isSharedRef(entry)) {
+                const filePath = await safeJoinUnder(registryRoot, entry.$ref);
+                const content = await readFile(filePath, 'utf-8');
+                return { scope, content, sourcePath: entry.$ref };
+            }
+            if (isLocalFileRef(entry)) {
+                const filePath = await safeJoinUnder(templateDir, entry.file);
+                const content = await readFile(filePath, 'utf-8');
+                return { scope, content, sourcePath: entry.file };
+            }
+            throw new Error(`Unknown instruction entry type: ${JSON.stringify(entry)}`);
         }
-        if (isLocalFileRef(entry)) {
-            const filePath = resolve(templateDir, entry.file);
-            const content = await readFile(filePath, 'utf-8');
-            return { scope: entry.scope, content, sourcePath: entry.file };
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                const refLabel = isSharedRef(entry)
+                    ? entry.$ref
+                    : isLocalFileRef(entry)
+                        ? entry.file
+                        : JSON.stringify(entry);
+                console.warn(`[loom] Skipping missing instruction file: ${refLabel}`);
+                return null;
+            }
+            throw err;
         }
-        throw new Error(`Unknown instruction entry type: ${JSON.stringify(entry)}`);
     }));
+    return resolved.filter((r) => r !== null);
 }
-async function resolveSkills(entries, templateDir) {
-    return Promise.all(entries.map(async (entry) => {
+/**
+ * Resolve a list of skill entries (registry / file / discover) into
+ * `ResolvedSkill[]`. Exposed so adapters (e.g. the dobby adapter) can
+ * pump entries through the same code path used by `resolveManifest`
+ * rather than re-implementing skill discovery.
+ *
+ * Each entry expands to zero, one, or many ResolvedSkill values:
+ *   - `registry:` -> 1 entry (registry coordinates only, no content)
+ *   - `file:` -> 1 entry (SKILL.md content + extra files)
+ *   - `discover:` -> N entries (one per immediate subdirectory of each
+ *     listed dir that contains a SKILL.md). Within a discover entry,
+ *     later paths override earlier ones on duplicate skill names
+ *     (preserving "team skills override shared skills" semantics).
+ *
+ * No cross-entry deduplication is performed -- callers that need it
+ * apply their own pass after concatenating the result.
+ */
+export async function resolveSkillEntries(entries, templateDir, log = () => { }) {
+    const resolved = [];
+    for (const entry of entries) {
         if (isRegistrySkillRef(entry)) {
-            return {
-                type: 'registry',
+            resolved.push({
                 registry: entry.registry,
                 ref: entry.ref,
-            };
+                name: entry.ref,
+            });
+            continue;
+        }
+        if (isDiscoverSkillsRef(entry)) {
+            const discovered = await discoverSkillsFromDirs(entry.discover, templateDir, log);
+            resolved.push(...discovered);
+            continue;
         }
         if (isLocalFileRef(entry)) {
-            const filePath = resolve(templateDir, entry.file);
+            const filePath = await safeJoinUnder(templateDir, entry.file);
             const content = await readFile(filePath, 'utf-8');
-            const name = parseFrontmatterField(content, 'name');
+            const frontmatterName = parseFrontmatterField(content, 'name');
+            const fallbackName = basename(filePath).toLowerCase() === 'skill.md'
+                ? basename(dirname(filePath))
+                : basename(filePath, extname(filePath)).replace(/\.skill$/, '');
+            const name = assertSafePathSegment('skill', frontmatterName === undefined ? fallbackName : frontmatterName, entry.file);
             const skillDir = dirname(filePath);
             const extraFiles = await collectExtraFiles(skillDir, filePath);
-            return {
-                type: 'local',
-                name: name ?? entry.name,
+            resolved.push({
+                name,
                 content,
                 sourcePath: entry.file,
                 extraFiles: extraFiles.length > 0 ? extraFiles : undefined,
-            };
+            });
+            continue;
         }
         throw new Error(`Unknown skill entry type: ${JSON.stringify(entry)}`);
-    }));
+    }
+    return resolved;
+}
+/**
+ * Walk each listed directory looking for `<name>/SKILL.md` and return a
+ * ResolvedSkill[] with content + extra files. Within `dirs`, later
+ * paths override earlier ones on duplicate skill names -- so caller
+ * order encodes precedence (e.g. `[shared, team]` -> team wins).
+ *
+ * Relative paths are resolved against `baseDir`; absolute paths are
+ * used as-is. Missing directories are silently skipped (matches dobby's
+ * "best effort" discovery).
+ */
+async function discoverSkillsFromDirs(dirs, baseDir, log) {
+    const byName = new Map();
+    for (const rawDir of dirs) {
+        let skillsRoot;
+        if (isAbsolute(rawDir)) {
+            skillsRoot = rawDir;
+        }
+        else {
+            try {
+                skillsRoot = await safeJoinUnder(baseDir, rawDir);
+            }
+            catch (err) {
+                log(`  Warning: skipping skill discover dir: ${err.message}`);
+                continue;
+            }
+        }
+        let entries;
+        try {
+            entries = (await readdir(skillsRoot, { withFileTypes: true }));
+        }
+        catch {
+            continue; // Directory doesn't exist -- that's fine, just skip
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const skillDir = join(skillsRoot, String(entry.name));
+            const skillMdPath = join(skillDir, 'SKILL.md');
+            try {
+                const s = await stat(skillMdPath);
+                if (!s.isFile())
+                    continue;
+            }
+            catch {
+                continue; // No SKILL.md -- not a skill directory
+            }
+            try {
+                const content = await readFile(skillMdPath, 'utf-8');
+                const frontmatter = parseFrontmatterRaw(content);
+                const name = typeof frontmatter.name === 'string' ? frontmatter.name : String(entry.name);
+                if (!isSafePathSegment(name)) {
+                    log(`  Warning: skipping skill ${entry.name}: ${unsafePathSegmentMessage('skill', name, skillMdPath)}`);
+                    continue;
+                }
+                const extraFiles = await collectExtraFiles(skillDir, skillMdPath);
+                // Last-write-wins on duplicate names: later dirs override earlier.
+                byName.set(name, {
+                    name,
+                    content,
+                    sourcePath: skillMdPath,
+                    extraFiles: extraFiles.length > 0 ? extraFiles : undefined,
+                });
+            }
+            catch (err) {
+                log(`  Warning: could not read skill ${entry.name}: ${err.message}`);
+            }
+        }
+    }
+    return Array.from(byName.values());
 }
+// File extensions that are safe to read as UTF-8 text. Everything else
+// is read as a Buffer so binary assets (.png, .ico, .zip, ...) survive
+// the resolver intact. Recovered from PR #134 cycle 3.
+const TEXT_EXTENSIONS = new Set([
+    '.md', '.markdown', '.txt', '.rst', '.json', '.yaml', '.yml',
+    '.toml', '.ini', '.cfg', '.conf', '.csv', '.tsv', '.log',
+    '.html', '.xml', '.xsd', '.js', '.mjs', '.cjs', '.ts', '.tsx',
+    '.jsx', '.py', '.rb', '.go', '.rs', '.c', '.cc', '.cpp', '.h',
+    '.hpp', '.cs', '.java', '.kt', '.swift', '.sh', '.bash', '.zsh',
+    '.fish', '.ps1', '.psm1', '.bat', '.cmd', '.sql',
+]);
+// Bound traversal of pathological registries (symlink loops would be
+// caught by `Dirent#isSymbolicLink()` below, but a deeply-nested or
+// fan-out tree would still consume unbounded memory without these caps).
+const MAX_EXTRA_FILES = 200;
+const MAX_EXTRA_DEPTH = 8;
 /**
- * Recursively collect all files in a skill directory except the main SKILL.md.
+ * Recursively collect files in a skill directory except the main SKILL.md.
+ *
+ * Hardening (recovered from PR #134 cycle 3):
+ *  - Symlinks (file or directory) are skipped. Following them would let
+ *    a malicious skill point at e.g. `id_rsa -> ~/.ssh/id_rsa` and
+ *    silently pull the key into the rendered workspace.
+ *  - Non-text extensions (.png, .ico, .zip, etc.) are read as binary
+ *    Buffer to avoid lossy UTF-8 decode of binary bytes.
+ *  - Per-file readFile is wrapped in try/catch so one EACCES/EISDIR
+ *    aborts only that entry, not the whole skill resolution.
+ *  - Depth cap (8) and per-skill file cap (200) prevent runaway
+ *    traversal of pathological registries.
  */
-async function collectExtraFiles(dir, mainFile, baseDir) {
+async function collectExtraFiles(dir, mainFile, baseDir, depthLeft = MAX_EXTRA_DEPTH, countSoFar = { value: 0 }) {
     baseDir = baseDir ?? dir;
     const results = [];
+    if (depthLeft < 0)
+        return results;
     let dirEntries;
     try {
         dirEntries = await readdir(dir, { withFileTypes: true });
@@ -110,42 +668,345 @@ async function collectExtraFiles(dir, mainFile, baseDir) {
         return results;
     }
     for (const entry of dirEntries) {
+        if (countSoFar.value >= MAX_EXTRA_FILES)
+            break;
+        // Skip symlinks defensively. Dirent#isSymbolicLink() reflects lstat
+        // semantics (Node uses lstat to populate Dirent), so a symlinked
+        // file or symlinked directory is detected and skipped here.
+        if (entry.isSymbolicLink())
+            continue;
         const fullPath = join(dir, String(entry.name));
         if (entry.isDirectory()) {
-            results.push(...(await collectExtraFiles(fullPath, mainFile, baseDir)));
+            results.push(...(await collectExtraFiles(fullPath, mainFile, baseDir, depthLeft - 1, countSoFar)));
+        }
+        else if (entry.isFile() && fullPath !== mainFile) {
+            try {
+                const ext = (entry.name.match(/\.[^.]+$/)?.[0] ?? '').toLowerCase();
+                const isText = TEXT_EXTENSIONS.has(ext);
+                const content = isText
+                    ? await readFile(fullPath, 'utf-8')
+                    : await readFile(fullPath); // Buffer; renderer writes raw
+                results.push({
+                    relativePath: relative(baseDir, fullPath).replace(/\\/g, '/'),
+                    content: content,
+                });
+                countSoFar.value++;
+            }
+            catch {
+                // EACCES / EISDIR / permission errors: skip the file but
+                // continue walking. One bad file shouldn't tank the whole
+                // skill resolution. (Pre-cycle-3 behavior aborted the resolve here.)
+                continue;
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Resolve a list of agent entries (file: or discover:) into
+ * `ResolvedAgent[]`. Exposed so adapters (e.g. the dobby adapter) can
+ * pump entries through the same code path used by `resolveManifest`
+ * rather than re-implementing agent loading + frontmatter parsing.
+ *
+ * Each entry expands to zero, one, or many ResolvedAgent values:
+ *   - `file:` -> 1 entry (read agent.md, parse frontmatter for ALL
+ *     metadata: name, description, model, tools, mcp-servers).
+ *   - `discover:` -> N entries (one per immediate subdir containing
+ *     an `*.agent.md`). Within a discover entry, later paths
+ *     override earlier ones on duplicate agent ids.
+ *
+ * Per U4, the .agent.md frontmatter is the only source of agent
+ * metadata. Manifest entries declare routing (the file path) only;
+ * model/tools overrides at the entry level are not honored. Per U4.5,
+ * the same applies to per-agent MCPs: an agent file's frontmatter
+ * `mcp-servers:` block is the single source of per-agent MCP
+ * declarations. The block is a map keyed by server id; each value
+ * carries the same fields as a top-level inline MCP entry (type,
+ * command, args, url, env, binary, ...).
+ *
+ * Across the entries array, later entries override earlier ones on
+ * duplicate agent ids -- so caller order encodes precedence
+ * (consistent with U2's skill-discovery rule).
+ */
+export async function resolveAgentEntries(entries, templateDir, log = () => { }, registryRoot) {
+    const mcpRoot = registryRoot ?? templateDir;
+    const byId = new Map();
+    for (const entry of entries) {
+        if (isDiscoverAgentRef(entry)) {
+            const discovered = await discoverAgentsFromDirs(entry.discover, templateDir, log, mcpRoot);
+            for (const a of discovered)
+                byId.set(a.agentId, a);
+            continue;
         }
-        else if (fullPath !== mainFile) {
-            const content = await readFile(fullPath, 'utf-8');
-            results.push({
-                relativePath: relative(baseDir, fullPath).replace(/\\/g, '/'),
+        if (isLocalFileRef(entry)) {
+            const filePath = await safeJoinUnder(templateDir, entry.file);
+            const raw = await readFile(filePath, 'utf-8');
+            const fm = parseFrontmatterRaw(raw);
+            const legacy = await readLegacyAgentManifestFromDir(dirname(filePath));
+            const legacyAgent = legacy?.agent;
+            const agentId = assertSafePathSegment('agent id', deriveAgentIdFromSourcePath(entry.file), entry.file);
+            const name = assertSafePathSegment('agent', (typeof fm.name === 'string' ? fm.name : undefined) ?? legacyAgent?.name ?? agentId, entry.file);
+            const description = (typeof fm.description === 'string' ? fm.description : undefined) ?? legacyAgent?.description ?? '';
+            const content = stripFrontmatter(raw);
+            const sourcePath = basename(filePath) === 'agent.md'
+                ? join(dirname(filePath), `${agentId}.agent.md`)
+                : filePath;
+            // Per U4: all metadata comes from frontmatter. No entry-level
+            // model/tools overlay -- the .agent.md file is the single source
+            // of truth. Dobby's `model:` is canonically a YAML array; when
+            // we see one, take the first string element and warn loudly so
+            // the author knows loom requires a single string.
+            const model = modelFromFrontmatter(fm.model, `agent ${entry.file}`, log) ?? legacyAgent?.model;
+            const tools = toolsFromFrontmatter(fm.tools) ?? legacyAgent?.tools;
+            // Per U4.5: per-agent MCPs come from the `mcp-servers:` block in
+            // the agent file's frontmatter (replacing the legacy
+            // `agents/<id>/manifest.yaml` sibling YAML).
+            const mcp = await resolveAgentFrontmatterMcps(fm, mcpRoot, log);
+            byId.set(agentId, {
+                agentId,
+                name,
+                description,
+                model,
+                tools,
                 content,
+                sourcePath,
+                mcp,
             });
+            continue;
         }
+        throw new Error(`Unknown agent entry type: ${JSON.stringify(entry)}`);
     }
-    return results;
+    return Array.from(byId.values());
 }
-async function resolveAgents(entries, templateDir) {
-    return Promise.all(entries.map(async (entry) => {
-        const filePath = resolve(templateDir, entry.file);
-        const raw = await readFile(filePath, 'utf-8');
-        const name = parseFrontmatterField(raw, 'name') ?? '';
-        const description = parseFrontmatterField(raw, 'description') ?? '';
-        // Strip frontmatter from content
-        const content = stripFrontmatter(raw);
-        return {
-            name,
-            description,
-            model: entry.model,
-            tools: entry.tools ?? [],
-            content,
-            sourcePath: entry.file,
+function modelFromFrontmatter(value, label, log) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value) && typeof value[0] === 'string') {
+        log(`  Warning: ${label}: \`model:\` is an array; using first element "${value[0]}". Loom requires a single string.`);
+        return value[0];
+    }
+    return undefined;
+}
+function toolsFromFrontmatter(value) {
+    return Array.isArray(value) ? value.map(String) : undefined;
+}
+/**
+ * Walk each listed directory looking for `<id>/<id>.agent.md` (dobby
+ * convention), `<id>/<basename>.agent.md` (loom convention), or legacy
+ * `<id>/agent.md` with sibling manifest metadata, and return a
+ * ResolvedAgent[] with parsed metadata.
+ *
+ * Within `dirs`, later paths override earlier ones on duplicate agent
+ * ids -- so caller order encodes precedence (consistent with U2). The
+ * subdir name is the canonical agent id; multiple `.agent.md` files in
+ * one dir are ambiguous and trigger a warning (with deterministic
+ * fallback to `<id>.agent.md` if present, else first alphabetically).
+ *
+ * Relative paths are resolved against `baseDir`; absolute paths are
+ * used as-is. Missing directories are silently skipped.
+ *
+ * Per U4.5, per-agent MCPs are read from the agent file's frontmatter
+ * `mcp-servers:` block. Legacy sibling `manifest.yaml` files are still
+ * accepted as a deprecated metadata/content fallback during migration.
+ */
+async function discoverAgentsFromDirs(dirs, baseDir, log, registryRoot) {
+    const byId = new Map();
+    for (const rawDir of dirs) {
+        let agentsRoot;
+        if (isAbsolute(rawDir)) {
+            agentsRoot = rawDir;
+        }
+        else {
+            try {
+                agentsRoot = await safeJoinUnder(baseDir, rawDir);
+            }
+            catch (err) {
+                log(`  Warning: skipping agent discover dir: ${err.message}`);
+                continue;
+            }
+        }
+        let entries;
+        try {
+            entries = (await readdir(agentsRoot, { withFileTypes: true }));
+        }
+        catch {
+            continue; // Directory doesn't exist -- that's fine, just skip
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const id = String(entry.name);
+            if (!isSafePathSegment(id)) {
+                log(`  Warning: skipping agent ${id}: ${unsafePathSegmentMessage('agent id', id, agentsRoot)}`);
+                continue;
+            }
+            const agentDir = join(agentsRoot, id);
+            const agentMdPath = await findAgentFile(agentDir, id, log);
+            if (!agentMdPath)
+                continue;
+            try {
+                const raw = await readFile(agentMdPath, 'utf-8');
+                const fm = parseFrontmatterRaw(raw);
+                const legacy = await readLegacyAgentManifestFromDir(agentDir);
+                const legacyAgent = legacy?.agent;
+                const name = (typeof fm.name === 'string' ? fm.name : undefined) ?? legacyAgent?.name ?? id;
+                if (!isSafePathSegment(name)) {
+                    log(`  Warning: skipping agent ${id}: ${unsafePathSegmentMessage('agent', name, agentMdPath)}`);
+                    continue;
+                }
+                const description = (typeof fm.description === 'string' ? fm.description : undefined) ?? legacyAgent?.description ?? '';
+                const model = modelFromFrontmatter(fm.model, `agent ${id}`, log) ?? legacyAgent?.model;
+                const tools = toolsFromFrontmatter(fm.tools) ?? legacyAgent?.tools;
+                const content = stripFrontmatter(raw);
+                const mcp = await resolveAgentFrontmatterMcps(fm, registryRoot, log);
+                const sourcePath = basename(agentMdPath) === 'agent.md'
+                    ? join(agentDir, `${id}.agent.md`)
+                    : agentMdPath;
+                // Last-write-wins on duplicate ids: later dirs override earlier.
+                byId.set(id, {
+                    agentId: id,
+                    name,
+                    description,
+                    model,
+                    tools,
+                    content,
+                    sourcePath,
+                    mcp,
+                });
+            }
+            catch (err) {
+                log(`  Warning: could not read agent ${id}: ${err.message}`);
+            }
+        }
+    }
+    return Array.from(byId.values());
+}
+/**
+ * Convert an agent file's frontmatter `mcp-servers:` block (a map keyed
+ * by server id) into a `ResolvedMcp[]`. The block uses the same value
+ * shape as a top-level inline MCP entry (type, command, args, url,
+ * env, binary, ...); the map key supplies the `id`. Returns
+ * `undefined` if the block is missing, empty, or malformed -- matching
+ * "no per-agent MCPs declared" semantics.
+ *
+ * Inline-only: `$ref` is not supported inside frontmatter. Per-agent
+ * MCPs that need to live in shared/ should be declared at team level
+ * via the manifest's `mcp:` block instead.
+ */
+async function resolveAgentFrontmatterMcps(fm, registryRoot, log) {
+    const block = fm['mcp-servers'];
+    if (!block || typeof block !== 'object' || Array.isArray(block))
+        return undefined;
+    const raw = block;
+    const mcpEntries = [];
+    for (const [id, value] of Object.entries(raw)) {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            continue;
+        const def = value;
+        const type = def.type === 'http' ? 'http' : 'stdio';
+        const inline = {
+            id,
+            name: typeof def.name === 'string' ? def.name : undefined,
+            description: typeof def.description === 'string' ? def.description : undefined,
+            type,
+            command: typeof def.command === 'string' ? def.command : undefined,
+            args: Array.isArray(def.args) ? def.args.map(String) : undefined,
+            cwd: typeof def.cwd === 'string' ? def.cwd : undefined,
+            url: typeof def.url === 'string' ? def.url : undefined,
+            authType: typeof def.authType === 'string' ? def.authType : undefined,
+            headers: def.headers && typeof def.headers === 'object' && !Array.isArray(def.headers)
+                ? def.headers
+                : undefined,
+            env: def.env && typeof def.env === 'object' && !Array.isArray(def.env)
+                ? def.env
+                : undefined,
+            binary: def.binary && typeof def.binary === 'object' && !Array.isArray(def.binary)
+                ? def.binary
+                : undefined,
         };
-    }));
+        mcpEntries.push(inline);
+    }
+    if (mcpEntries.length === 0)
+        return undefined;
+    return resolveMcpEntries(mcpEntries, registryRoot, log);
+}
+/**
+ * Find the agent markdown file inside an agent directory. Accepts both
+ * the dobby convention (`<id>.agent.md`), the loom convention (a single
+ * `*.agent.md` file with any basename), and legacy `agent.md` fallback.
+ * Multiple `.agent.md` candidates trigger a warning and a deterministic
+ * fallback.
+ */
+async function findAgentFile(agentDir, id, log) {
+    let entries;
+    try {
+        entries = (await readdir(agentDir, { withFileTypes: true }));
+    }
+    catch {
+        return undefined;
+    }
+    const agentFiles = entries
+        .filter((e) => e.isFile() && String(e.name).endsWith('.agent.md'))
+        .map((e) => String(e.name))
+        .sort();
+    if (agentFiles.length === 0) {
+        const legacyAgentMd = join(agentDir, 'agent.md');
+        return (await fileExists(legacyAgentMd)) ? legacyAgentMd : undefined;
+    }
+    if (agentFiles.length === 1)
+        return join(agentDir, agentFiles[0]);
+    // Multiple candidates: prefer <id>.agent.md (no warning -- that's
+    // the dobby convention and the canonical pick). Otherwise warn and
+    // fall back to first alphabetically.
+    const idMatch = `${id}.agent.md`;
+    if (agentFiles.includes(idMatch)) {
+        return join(agentDir, idMatch);
+    }
+    log(`  Warning: agent dir ${agentDir} has multiple .agent.md files ` +
+        `(${agentFiles.join(', ')}); using ${agentFiles[0]} alphabetically. ` +
+        `Rename one to ${idMatch} to make this deterministic.`);
+    return join(agentDir, agentFiles[0]);
 }
-async function resolveMcp(entries, registryRoot) {
+/**
+ * Derive the stable agent identifier from a source file path. This
+ * is the slug callers use to look the agent up at launch time and
+ * the basename of the rendered `.agent.md` file. Two layouts:
+ *
+ * - Loom nested layout: `agents/<id>/agent.md`     -> id = `<id>`
+ * - Dobby / flat layout: `<id>.agent.md`           -> id = `<id>`
+ *
+ * The function picks the parent dir name when it looks like a
+ * loom-nested layout (parent dir is non-trivial and not `agents/`);
+ * otherwise it falls back to the basename without the `.agent.md`
+ * extension.
+ */
+export function deriveAgentIdFromSourcePath(sourcePath) {
+    const stem = basename(sourcePath, '.agent.md').replace(/\.md$/, '');
+    const parentDir = basename(dirname(sourcePath));
+    if (parentDir && parentDir !== '.' && parentDir !== 'agents') {
+        return parentDir;
+    }
+    return stem;
+}
+/**
+ * Resolve a list of MCP entries (shared $ref or inline) into
+ * `ResolvedMcp[]`. Exposed for adapters that resolve per-agent MCP
+ * blocks separately from the team-level ones (loom#127).
+ *
+ * Inline entries with a `binary:` block (and no explicit `command`) are
+ * routed through the binary cache: on first use the asset is fetched
+ * from the GitHub release into ~/.loom/mcp-binaries/ and the absolute
+ * cache path becomes the resolved `command`. If resolution fails the
+ * entry passes through with an undefined command and downstream
+ * launch surfaces a clear error.
+ *
+ * Pure: reads YAML for $ref entries, no provenance tagging, no
+ * dedup. The caller decides how to combine results.
+ */
+export async function resolveMcpEntries(entries, registryRoot, log = () => { }) {
     return Promise.all(entries.map(async (entry) => {
         if (isSharedRef(entry)) {
-            const filePath = resolve(registryRoot, entry.$ref);
+            const filePath = await safeJoinUnder(registryRoot, entry.$ref);
             const content = await readFile(filePath, 'utf-8');
             const parsed = yaml.load(content);
             return {
@@ -155,21 +1016,38 @@ async function resolveMcp(entries, registryRoot) {
                 type: parsed.type,
                 command: parsed.command,
                 args: parsed.args,
+                cwd: parsed.cwd,
                 url: parsed.url,
                 authType: parsed.authType,
+                // U6: forward static auth headers from shared MCP files so a
+                // manifest referencing shared/mcp/foo.yaml with required
+                // headers ends up with a working server definition.
+                headers: parsed.headers,
                 env: parsed.env,
             };
         }
         if (isMcpInlineDef(entry)) {
+            let command = entry.command;
+            // `binary:` resolution: download the release asset (or hit the
+            // cache) and use the absolute cached path as the launch command.
+            // Only fires when no explicit `command` was provided.
+            if (entry.binary && !command) {
+                const cached = await resolveBinaryToCache(entry.binary, log);
+                if (cached) {
+                    command = cached.cachedPath;
+                }
+            }
             return {
                 id: entry.id,
                 name: entry.name,
                 description: entry.description,
                 type: entry.type,
-                command: entry.command,
+                command,
                 args: entry.args,
+                cwd: entry.cwd,
                 url: entry.url,
                 authType: entry.authType,
+                headers: entry.headers,
                 env: entry.env,
             };
         }
@@ -179,7 +1057,7 @@ async function resolveMcp(entries, registryRoot) {
 async function resolveRepos(entries, registryRoot) {
     return Promise.all(entries.map(async (entry) => {
         if (isSharedRef(entry)) {
-            const filePath = resolve(registryRoot, entry.$ref);
+            const filePath = await safeJoinUnder(registryRoot, entry.$ref);
             const content = await readFile(filePath, 'utf-8');
             const parsed = yaml.load(content);
             return {
@@ -215,42 +1093,43 @@ async function resolvePrompts(entries, templateDir, registryRoot) {
         let filePath;
         let sourcePath;
         if (isSharedRef(entry)) {
-            filePath = resolve(registryRoot, entry.$ref);
+            filePath = await safeJoinUnder(registryRoot, entry.$ref);
             sourcePath = entry.$ref;
         }
         else if (isLocalFileRef(entry)) {
-            filePath = resolve(templateDir, entry.file);
+            filePath = await safeJoinUnder(templateDir, entry.file);
             sourcePath = entry.file;
         }
         else {
             throw new Error(`Unknown prompt entry type: ${JSON.stringify(entry)}`);
         }
         const raw = await readFile(filePath, 'utf-8');
-        const name = isLocalFileRef(entry) && entry.name
-            ? entry.name
-            : parseFrontmatterField(raw, 'name')
-                ?? basename(filePath, extname(filePath)).replace(/\.prompt$/, '');
-        const description = isLocalFileRef(entry) && entry.description
-            ? entry.description
-            : parseFrontmatterField(raw, 'description');
-        const localRef = isLocalFileRef(entry) ? entry : {};
+        // Per U4: prompt metadata (name, description, agent, model,
+        // tools) comes from the .prompt.md frontmatter only. The entry
+        // declares routing (file path) and behavior flags (shared,
+        // disableAutoInvoke) -- not metadata.
+        const name = parseFrontmatterField(raw, 'name') ??
+            basename(filePath, extname(filePath)).replace(/\.prompt$/, '');
+        assertSafePathSegment('prompt', name, sourcePath);
+        const description = parseFrontmatterField(raw, 'description');
+        const localRef = isLocalFileRef(entry) ? entry : undefined;
         return {
             name,
             description,
             content: raw,
             sourcePath,
-            agent: localRef.agent ?? parseFrontmatterField(raw, 'agent'),
-            model: localRef.model ?? parseFrontmatterField(raw, 'model'),
-            tools: localRef.tools ?? parseFrontmatterArrayField(raw, 'tools'),
-            shared: localRef.shared ?? false,
-            disableAutoInvoke: localRef.disableAutoInvoke ?? false,
+            agent: parseFrontmatterField(raw, 'agent'),
+            model: parseFrontmatterField(raw, 'model'),
+            tools: parseFrontmatterArrayField(raw, 'tools'),
+            shared: localRef?.shared ?? false,
+            disableAutoInvoke: localRef?.disableAutoInvoke ?? false,
         };
     }));
 }
 async function resolvePrerequisites(entries, registryRoot) {
     return Promise.all(entries.map(async (entry) => {
         if (isSharedRef(entry)) {
-            const filePath = resolve(registryRoot, entry.$ref);
+            const filePath = await safeJoinUnder(registryRoot, entry.$ref);
             const content = await readFile(filePath, 'utf-8');
             const parsed = yaml.load(content);
             return {
@@ -267,120 +1146,15 @@ async function resolvePrerequisites(entries, registryRoot) {
         return inline;
     }));
 }
-// =============================================================================
-// Nested agent support
-// =============================================================================
-/**
- * Parse an agent manifest.yaml file (per-agent within a team template).
- */
-export async function parseAgentManifest(manifestPath) {
-    const content = await readFile(manifestPath, 'utf-8');
-    const raw = yaml.load(content);
-    return raw;
-}
-/**
- * Discover nested agent directories within a template.
- * Returns agent directory names if the template has an agents/ subdirectory
- * where each subdir contains a manifest.yaml.
- */
-export async function discoverNestedAgents(templateDir) {
-    const { readdir, stat } = await import('node:fs/promises');
-    const agentsDir = resolve(templateDir, 'agents');
-    try {
-        const entries = await readdir(agentsDir);
-        const agentIds = [];
-        for (const entry of entries) {
-            const entryPath = resolve(agentsDir, entry);
-            const manifestPath = resolve(entryPath, 'manifest.yaml');
-            const s = await stat(entryPath).catch(() => null);
-            if (s?.isDirectory()) {
-                const hasManifest = await stat(manifestPath).then(() => true).catch(() => false);
-                if (hasManifest) {
-                    agentIds.push(entry);
-                }
-            }
-        }
-        return agentIds.sort();
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Merge a team manifest with one or more agent manifests to produce
- * a combined manifest ready for resolving.
- *
- * Merge rules:
- * - repos: agent only (team repos are NOT included)
- * - mcp, instructions, skills, prompts, prerequisites: union (team + agent)
- * - agents: built from agent.md files in selected agents
- * - targets: inherited from team
- */
-export function mergeTeamAndAgentManifests(teamManifest, agentManifests, agentDirs) {
-    // Build agent entries from the per-agent data
-    const agentEntries = agentManifests.map((am, i) => ({
-        file: `agents/${agentDirs[i]}/agent.md`,
-        model: am.agent.model,
-        tools: am.agent.tools,
-    }));
-    // Collect agent-specific MCP, instructions, skills, prompts, prerequisites
-    const agentMcps = [];
-    const agentInstructions = [];
-    const agentSkills = [];
-    const agentPrompts = [];
-    const agentPrereqs = [];
-    // Repos come ONLY from agents
-    const agentRepos = [];
-    for (const am of agentManifests) {
-        if (am.contents?.mcp)
-            agentMcps.push(...am.contents.mcp);
-        if (am.contents?.instructions)
-            agentInstructions.push(...am.contents.instructions);
-        if (am.contents?.skills)
-            agentSkills.push(...am.contents.skills);
-        if (am.contents?.prompts)
-            agentPrompts.push(...am.contents.prompts);
-        if (am.contents?.repos)
-            agentRepos.push(...am.contents.repos);
-        if (am.prerequisites)
-            agentPrereqs.push(...am.prerequisites);
-    }
-    // Deduplicate MCP by $ref value or id
-    const teamMcps = teamManifest.contents.mcp ?? [];
-    const allMcps = deduplicateEntries([...teamMcps, ...agentMcps], mcpEntryKey);
-    // Deduplicate skills
-    const teamSkills = teamManifest.contents.skills ?? [];
-    const allSkills = deduplicateEntries([...teamSkills, ...agentSkills], skillEntryKey);
-    // Deduplicate prerequisites
-    const teamPrereqs = teamManifest.prerequisites ?? [];
-    const allPrereqs = deduplicateEntries([...teamPrereqs, ...agentPrereqs], prereqEntryKey);
-    // Deduplicate repos
-    const allRepos = deduplicateEntries(agentRepos, repoEntryKey);
-    return {
-        version: teamManifest.version,
-        template: teamManifest.template,
-        targets: teamManifest.targets,
-        contents: {
-            instructions: [...(teamManifest.contents.instructions ?? []), ...agentInstructions],
-            skills: allSkills,
-            agents: agentEntries,
-            mcp: allMcps,
-            repos: allRepos,
-            prompts: [...(teamManifest.contents.prompts ?? []), ...agentPrompts],
-        },
-        prerequisites: allPrereqs,
-    };
-}
-// --- Deduplication helpers ---
 function deduplicateEntries(entries, keyFn) {
     const seen = new Set();
     const result = [];
     for (const entry of entries) {
         const key = keyFn(entry);
-        if (!seen.has(key)) {
-            seen.add(key);
-            result.push(entry);
-        }
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(entry);
     }
     return result;
 }
@@ -394,6 +1168,8 @@ function mcpEntryKey(entry) {
 function skillEntryKey(entry) {
     if (isRegistrySkillRef(entry))
         return `registry:${entry.registry}:${entry.ref}`;
+    if (isDiscoverSkillsRef(entry))
+        return `discover:${entry.discover.join('|')}`;
     if (isLocalFileRef(entry))
         return `file:${entry.file}`;
     return JSON.stringify(entry);
@@ -406,7 +1182,8 @@ function prereqEntryKey(entry) {
 function repoEntryKey(entry) {
     if (isSharedRef(entry))
         return `ref:${entry.$ref}`;
-    return `url:${entry.url}`;
+    const inline = entry;
+    return inline.id ? `id:${inline.id}` : `url:${inline.url ?? JSON.stringify(entry)}`;
 }
 // =============================================================================
 // Frontmatter helpers
@@ -415,40 +1192,18 @@ function repoEntryKey(entry) {
  * Parse a single field from YAML frontmatter (--- delimited).
  */
 function parseFrontmatterField(content, field) {
-    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-    if (!match)
-        return undefined;
-    try {
-        const fm = yaml.load(match[1]);
-        const value = fm[field];
-        return typeof value === 'string' ? value : undefined;
-    }
-    catch {
-        return undefined;
-    }
+    const fm = parseFrontmatterRaw(content);
+    const value = fm[field];
+    return typeof value === 'string' ? value : undefined;
 }
 /**
  * Parse an array field from YAML frontmatter.
  */
 function parseFrontmatterArrayField(content, field) {
-    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-    if (!match)
-        return undefined;
-    try {
-        const fm = yaml.load(match[1]);
-        const value = fm[field];
-        if (Array.isArray(value))
-            return value.map(String);
-        return undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * Strip YAML frontmatter from content, returning only the body.
- */
-function stripFrontmatter(content) {
-    return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n*/, '').trim();
+    const fm = parseFrontmatterRaw(content);
+    const value = fm[field];
+    if (Array.isArray(value))
+        return value.map(String);
+    return undefined;
 }
 //# sourceMappingURL=manifest.js.map