@noodleseed/one 0.72.0 → 0.73.1

package/dist/agent-skills-state.d.ts

@@ -0,0 +1,40 @@
+import { type AgentTarget } from '@noodle-borg/agent-kit';
+export interface ManagedSkillFileInput {
+    readonly path: string;
+    readonly content: string;
+    readonly skill: string;
+    readonly skillVersion: string;
+}
+export interface ManagedSkillFileAction {
+    readonly path: string;
+    readonly target: AgentTarget;
+    readonly action: 'created' | 'unchanged' | 'overwritten' | 'removed' | 'skipped';
+    readonly reason?: 'user-edited-removed-generated-file';
+}
+export interface ManagedSkillStateFile {
+    readonly path: string;
+    readonly sha256: string;
+    readonly skill: string;
+    readonly skillVersion: string;
+}
+export interface ManagedSkillState {
+    readonly schemaVersion: 1;
+    readonly packageVersion: string;
+    readonly target: AgentTarget;
+    readonly files: readonly ManagedSkillStateFile[];
+}
+export declare function managedSkillsStatePath(target: AgentTarget): string;
+export declare function assertManagedSkillFilesSafe(input: {
+    readonly project: string;
+    readonly target: AgentTarget;
+    readonly files: readonly Pick<ManagedSkillFileInput, 'path'>[];
+}): void;
+export declare function reconcileManagedSkillFiles(input: {
+    readonly project: string;
+    readonly target: AgentTarget;
+    readonly packageVersion: string;
+    readonly files: readonly ManagedSkillFileInput[];
+    readonly write: boolean;
+}): readonly ManagedSkillFileAction[];
+export declare function readManagedSkillState(project: string, target: AgentTarget): ManagedSkillState | undefined;
+//# sourceMappingURL=agent-skills-state.d.ts.map

package/dist/agent-skills-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-skills-state.d.ts","sourceRoot":"","sources":["../src/agent-skills-state.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,KAAK,WAAW,EAAiB,MAAM,wBAAwB,CAAC;AAEzE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,GAAG,SAAS,CAAC;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,oCAAoC,CAAC;CACxD;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAClD;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAElE;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,EAAE,CAAC;CAChE,GAAG,IAAI,CASP;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACjD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB,GAAG,SAAS,sBAAsB,EAAE,CAmEpC;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,GAClB,iBAAiB,GAAG,SAAS,CAE/B"}

package/dist/agent-skills-state.js

@@ -0,0 +1,184 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { contentSha256 } from '@noodle-borg/agent-kit';
+export function managedSkillsStatePath(target) {
+    return `${skillRoot(target)}/.noodle-managed.json`;
+}
+export function assertManagedSkillFilesSafe(input) {
+    assertManagedPathSafe(input.project, skillRoot(input.target));
+    assertManagedPathSafe(input.project, managedSkillsStatePath(input.target));
+    for (const file of input.files) {
+        if (!isOwnedPath(input.target, file.path)) {
+            throw new Error(`invalid managed skill path: ${file.path}`);
+        }
+        assertManagedPathSafe(input.project, file.path);
+    }
+}
+export function reconcileManagedSkillFiles(input) {
+    const files = validateInputs(input.target, input.files);
+    if (input.write) {
+        assertManagedSkillFilesSafe({
+            project: input.project,
+            target: input.target,
+            files,
+        });
+    }
+    const nextPaths = new Set(files.map((file) => file.path));
+    const previous = readState(input.project, input.target);
+    if (input.write && previous !== undefined) {
+        for (const file of previous.files)
+            assertManagedPathSafe(input.project, file.path);
+    }
+    const actions = files.map((file) => {
+        const full = join(input.project, file.path);
+        const existing = existsSync(full) ? readFileSync(full, 'utf8') : undefined;
+        return {
+            path: file.path,
+            target: input.target,
+            action: existing === undefined
+                ? 'created'
+                : existing === file.content
+                    ? 'unchanged'
+                    : 'overwritten',
+        };
+    });
+    const removable = [];
+    for (const file of previous?.files ?? []) {
+        if (nextPaths.has(file.path) || !isOwnedPath(input.target, file.path))
+            continue;
+        const full = join(input.project, file.path);
+        if (!existsSync(full))
+            continue;
+        if (contentSha256(readFileSync(full, 'utf8')) === file.sha256) {
+            removable.push(file.path);
+            actions.push({ path: file.path, target: input.target, action: 'removed' });
+        }
+        else {
+            actions.push({
+                path: file.path,
+                target: input.target,
+                action: 'skipped',
+                reason: 'user-edited-removed-generated-file',
+            });
+        }
+    }
+    if (!input.write)
+        return actions;
+    for (const file of files) {
+        const action = actions.find((candidate) => candidate.path === file.path)?.action;
+        if (action !== 'unchanged')
+            atomicWrite(join(input.project, file.path), file.content);
+    }
+    for (const path of removable)
+        rmSync(join(input.project, path), { force: true });
+    const state = {
+        schemaVersion: 1,
+        packageVersion: input.packageVersion,
+        target: input.target,
+        files: files.map((file) => ({
+            path: file.path,
+            sha256: contentSha256(file.content),
+            skill: file.skill,
+            skillVersion: file.skillVersion,
+        })),
+    };
+    atomicWrite(join(input.project, managedSkillsStatePath(input.target)), `${JSON.stringify(state, null, 2)}\n`);
+    return actions;
+}
+export function readManagedSkillState(project, target) {
+    return readState(project, target);
+}
+function validateInputs(target, files) {
+    const paths = new Set();
+    for (const file of files) {
+        if (!isOwnedPath(target, file.path) || paths.has(file.path)) {
+            throw new Error(`invalid or duplicate managed skill path: ${file.path}`);
+        }
+        if (!file.path.startsWith(`${skillRoot(target)}/${file.skill}/`)) {
+            throw new Error(`managed skill identity does not match path: ${file.path}`);
+        }
+        paths.add(file.path);
+    }
+    return files;
+}
+function readState(project, target) {
+    try {
+        const value = JSON.parse(readFileSync(join(project, managedSkillsStatePath(target)), 'utf8'));
+        if (!isRecord(value) || value.schemaVersion !== 1 || value.target !== target)
+            return undefined;
+        if (typeof value.packageVersion !== 'string' || !Array.isArray(value.files))
+            return undefined;
+        const files = [];
+        const paths = new Set();
+        for (const file of value.files) {
+            if (!isRecord(file) ||
+                typeof file.path !== 'string' ||
+                typeof file.sha256 !== 'string' ||
+                typeof file.skill !== 'string' ||
+                typeof file.skillVersion !== 'string' ||
+                !/^[a-f0-9]{64}$/.test(file.sha256) ||
+                !isOwnedPath(target, file.path) ||
+                paths.has(file.path)) {
+                return undefined;
+            }
+            paths.add(file.path);
+            files.push({
+                path: file.path,
+                sha256: file.sha256,
+                skill: file.skill,
+                skillVersion: file.skillVersion,
+            });
+        }
+        return { schemaVersion: 1, packageVersion: value.packageVersion, target, files };
+    }
+    catch {
+        return undefined;
+    }
+}
+function atomicWrite(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+    writeFileSync(temporary, content);
+    renameSync(temporary, path);
+}
+function assertManagedPathSafe(project, relativePath) {
+    const absoluteProject = resolve(project);
+    const segments = relativePath.split('/');
+    let current = absoluteProject;
+    for (let index = 0; index <= segments.length; index += 1) {
+        const stats = lstatIfPresent(current);
+        if (stats?.isSymbolicLink()) {
+            throw new Error(`refusing managed skill path with symbolic link: ${current}`);
+        }
+        if (index < segments.length && stats !== undefined && !stats.isDirectory()) {
+            throw new Error(`refusing managed skill path with non-directory ancestor: ${current}`);
+        }
+        if (index < segments.length)
+            current = join(current, segments[index] ?? '');
+    }
+}
+function lstatIfPresent(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function skillRoot(target) {
+    return target === 'codex' ? '.agents/skills' : '.claude/skills';
+}
+function isOwnedPath(target, path) {
+    const prefix = `${skillRoot(target)}/`;
+    return (path.startsWith(prefix) &&
+        !path.includes('\\') &&
+        path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..') &&
+        path !== managedSkillsStatePath(target));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=agent-skills-state.js.map

package/dist/agent-skills-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-skills-state.js","sourceRoot":"","sources":["../src/agent-skills-state.ts"],"names":[],"mappings":"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"}

package/dist/agents.d.ts

@@ -1,4 +1,4 @@
-import { type AgentTarget } from '@noodle-borg/agent-kit';
+import { type AgentTarget, type SkillRegistry } from '@noodle-borg/agent-kit';
 import { type JsonError } from './commands/output.js';
 import { type ConfigLocation } from './config.js';
 interface AgentArgs {
@@ -14,13 +14,24 @@ interface AgentArgs {
 type ResolvedAgentArgs = AgentArgs & {
     readonly agents: readonly AgentTarget[];
 };
-type AgentSetupInput = Omit<ResolvedAgentArgs, 'action' | 'refresh'> & {
-    readonly skillsOverride?: ReadonlyMap<string, string>;
+export type AgentSetupInput = Omit<ResolvedAgentArgs, 'action' | 'refresh'> & {
+    readonly skillsOverride?: ResolvedSkillsSnapshot;
+    readonly registry?: SkillRegistry;
 };
+export interface ResolvedSkillsSnapshot {
+    readonly packageVersion: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly content: string;
+        readonly target: AgentTarget;
+        readonly skill: string;
+        readonly skillVersion: string;
+    }[];
+}
 export interface AgentFileAction {
     readonly path: string;
     readonly target: AgentTarget;
-    readonly action: 'created' | 'unchanged' | 'updated' | 'skipped' | 'overwritten';
+    readonly action: 'created' | 'unchanged' | 'updated' | 'skipped' | 'overwritten' | 'removed';
     readonly reason?: string;
 }
 export interface AgentSetupReport {

package/dist/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,WAAW,EAMjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,SAAS,EAAiC,MAAM,sBAAsB,CAAC;AACrF,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,aAAa,CAAC;AAYzE,UAAU,SAAS;IACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,wGAAwG;IACxG,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,KAAK,iBAAiB,GAAG,SAAS,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAA;CAAE,CAAC;AAEjF,KAAK,eAAe,GAAG,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,SAAS,CAAC,GAAG;IACrE,QAAQ,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvD,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,gGAAgG;AAChG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,CAOrF;AAED,wBAAsB,SAAS,CAC7B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,cAAc,CAAC,EAAE,cAAc,GAC9B,OAAO,CAAC,MAAM,CAAC,CAajB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,gBAAgB,CAkFnE;AAED,qFAAqF;AACrF,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,IAAI,CAAC,eAAe,EAAE,gBAAgB,CAAC,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,EAC9E,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,cAAc,CAAC,EAAE,cAAc,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAmB3B"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}

package/dist/agents.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { delimiter, dirname, join, resolve } from 'node:path';
-import { AGENT_KIT_VERSION, contentSha256, parseAgentTargets, reconcileManagedBlock, renderAgentFiles, skillFileMappings, } from '@noodle-borg/agent-kit';
+import { AGENT_KIT_VERSION, contentSha256, parseAgentTargets, reconcileManagedBlock, renderAgentFiles, } from '@noodle-borg/agent-kit';
+import { assertManagedSkillFilesSafe, readManagedSkillState, reconcileManagedSkillFiles, } from './agent-skills-state.js';
 import { printJsonFailure, printJsonOk } from './commands/output.js';
 import { configDir, readConfig } from './config.js';
 import { readPluginCompatibility } from './plugin-mode/compatibility.js';
@@ -35,27 +36,28 @@ export async function runAgents(rest, env = process.env, configLocation) {
     return 2;
 }
 export function setupAgents(args) {
-    const projectDefaults = readResolvedProjectConfig(args.project);
-    const link = readProjectLink(args.project);
-    const org = link?.org ?? projectDefaults.org;
-    const app = link?.app ?? projectDefaults.app;
     const planned = renderAgentFiles({
         targets: args.agents,
-        project: Object.assign({}, projectDefaults.name !== undefined ? { name: projectDefaults.name } : {}, projectDefaults.entrypoint !== undefined ? { entrypoint: projectDefaults.entrypoint } : {}, projectDefaults.env !== undefined ? { env: projectDefaults.env } : {}, projectDefaults.accessMode !== undefined ? { accessMode: projectDefaults.accessMode } : {}, projectDefaults.template !== undefined ? { template: projectDefaults.template } : {}, org !== undefined ? { org } : {}, app !== undefined ? { app } : {}),
+        ...(args.registry !== undefined ? { registry: args.registry } : {}),
+        project: resolveAgentProjectMetadata(args.project),
     });
-    // Remote (registry-fresh) skills override the bundled skill files, keyed by installed path so each
-    // SKILL.md and reference is replaced by its own registry-verified content. The managed block stays
-    // bundled because it is project-specific and rendered with the user's metadata.
-    const override = args.skillsOverride;
-    for (const file of planned) {
-        if (file.mode === 'generated-file' && override !== undefined) {
-            const content = override.get(file.path);
-            if (content !== undefined)
-                file.content = content;
+    // A registry-fresh snapshot replaces the bundled generated tree as one complete unit. The managed
+    // host block stays bundled because it is project-specific.
+    const generatedFiles = args.skillsOverride === undefined
+        ? planned.filter((file) => file.mode === 'generated-file')
+        : args.skillsOverride.files.filter((file) => args.agents.includes(file.target));
+    validateResolvedSkillsSnapshot(args.agents, generatedFiles);
+    if (args.write) {
+        for (const target of args.agents) {
+            assertManagedSkillFilesSafe({
+                project: args.project,
+                target,
+                files: generatedFiles.filter((file) => file.target === target),
+            });
         }
     }
     const files = [];
-    for (const file of planned) {
+    for (const file of planned.filter((candidate) => candidate.mode === 'managed-block')) {
         const full = join(args.project, file.path);
         const existing = existsSync(full) ? readFileSync(full, 'utf8') : undefined;
         if (!args.write) {
@@ -66,35 +68,38 @@ export function setupAgents(args) {
             });
             continue;
         }
-        if (file.mode === 'managed-block') {
-            const result = reconcileManagedBlock({
-                ...(existing !== undefined ? { existing } : {}),
-                block: file.content,
-                force: args.force,
-            });
-            if (result.action !== 'unchanged' && result.action !== 'skipped') {
+        const result = reconcileManagedBlock({
+            ...(existing !== undefined ? { existing } : {}),
+            block: file.content,
+            force: args.force,
+        });
+        if (result.action !== 'unchanged' && result.action !== 'skipped') {
+            if (args.write) {
                 mkdirSync(dirname(full), { recursive: true });
                 writeFileSync(full, result.content);
             }
-            files.push({
-                path: file.path,
-                target: file.target,
-                action: result.action,
-                ...(result.reason !== undefined ? { reason: result.reason } : {}),
-            });
-        }
-        else {
-            const action = existing === undefined
-                ? 'created'
-                : existing === file.content
-                    ? 'unchanged'
-                    : 'overwritten';
-            if (action !== 'unchanged') {
-                mkdirSync(dirname(full), { recursive: true });
-                writeFileSync(full, file.content);
-            }
-            files.push({ path: file.path, target: file.target, action });
         }
+        files.push({
+            path: file.path,
+            target: file.target,
+            action: result.action,
+            ...(result.reason !== undefined ? { reason: result.reason } : {}),
+        });
+    }
+    for (const target of args.agents) {
+        const generated = generatedFiles.filter((file) => file.target === target);
+        files.push(...reconcileManagedSkillFiles({
+            project: args.project,
+            target,
+            packageVersion: args.skillsOverride?.packageVersion ?? AGENT_KIT_VERSION,
+            files: generated.map((file) => ({
+                path: file.path,
+                content: file.content,
+                skill: file.skill ?? failMissingSkillIdentity(file.path),
+                skillVersion: file.skillVersion ?? failMissingSkillIdentity(file.path),
+            })),
+            write: args.write,
+        }));
     }
     return {
         ok: true,
@@ -107,6 +112,44 @@ export function setupAgents(args) {
             : [],
     };
 }
+function resolveAgentProjectMetadata(project) {
+    const projectDefaults = readResolvedProjectConfig(project);
+    const link = readProjectLink(project);
+    const org = link?.org ?? projectDefaults.org;
+    const app = link?.app ?? projectDefaults.app;
+    return Object.assign({}, projectDefaults.name !== undefined ? { name: projectDefaults.name } : {}, projectDefaults.entrypoint !== undefined ? { entrypoint: projectDefaults.entrypoint } : {}, projectDefaults.env !== undefined ? { env: projectDefaults.env } : {}, projectDefaults.accessMode !== undefined ? { accessMode: projectDefaults.accessMode } : {}, projectDefaults.template !== undefined ? { template: projectDefaults.template } : {}, org !== undefined ? { org } : {}, app !== undefined ? { app } : {});
+}
+function validateResolvedSkillsSnapshot(targets, files) {
+    const paths = new Set();
+    for (const file of files) {
+        const expectedRoot = `${file.target === 'codex' ? '.agents' : '.claude'}/skills/${file.skill ?? ''}/`;
+        if (file.skill === undefined ||
+            !file.path.startsWith(expectedRoot) ||
+            file.path.includes('\\') ||
+            file.path
+                .split('/')
+                .some((segment) => segment === '' || segment === '.' || segment === '..') ||
+            paths.has(file.path)) {
+            throw new Error(`resolved skill snapshot has invalid or duplicate path: ${file.path}`);
+        }
+        paths.add(file.path);
+    }
+    for (const target of targets) {
+        const targetFiles = files.filter((file) => file.target === target);
+        if (targetFiles.length === 0)
+            throw new Error(`resolved skill snapshot is missing ${target}`);
+        const skills = new Set(targetFiles.map((file) => file.skill));
+        for (const skill of skills) {
+            if (skill === undefined ||
+                !targetFiles.some((file) => file.skill === skill && file.path.endsWith(`/skills/${skill}/SKILL.md`))) {
+                throw new Error(`resolved skill snapshot is missing SKILL.md for ${target}/${skill ?? '?'}`);
+            }
+        }
+    }
+}
+function failMissingSkillIdentity(path) {
+    throw new Error(`generated skill file is missing registry identity: ${path}`);
+}
 /** Resolve the active Agent Kit profile before rendering any project agent files. */
 export async function setupAgentsWithResolvedSkills(args, env = process.env, configLocation) {
     // Interactive writes may fetch registry-latest, while plugin mode resolves the exact compatibility pin.
@@ -175,17 +218,20 @@ async function resolveSkillsOverride(refresh, configLocation, pluginRequiredVers
     });
     if (result.status !== 'ready' || result.kit === undefined)
         return undefined;
-    // Map each publishable file (e.g. `skills/codex/references/cli-commands.md`) to its installed
-    // destination so the override replaces every file in the tree, not just the SKILL.md.
-    const installedByPublish = new Map(skillFileMappings().map((m) => [m.publishPath, m.installedPath]));
-    const override = new Map();
+    const files = [];
     for (const file of result.kit.manifest.files) {
         const content = result.kit.files.get(file.path);
-        const installedPath = installedByPublish.get(file.path);
-        if (content !== undefined && installedPath !== undefined)
-            override.set(installedPath, content);
+        if (content === undefined)
+            return undefined;
+        files.push({
+            path: file.installedPath,
+            content,
+            target: file.agentTarget,
+            skill: file.skill,
+            skillVersion: file.skillVersion,
+        });
     }
-    return override;
+    return { packageVersion: result.kit.version, files };
 }
 async function runAgentDoctor(args, env, configLocation) {
     const pluginRequiredVersion = pluginRequiredAgentKitVersion(env);
@@ -197,26 +243,64 @@ async function runAgentDoctor(args, env, configLocation) {
             version: pluginRequiredVersion,
         })
         : undefined;
-    const installedByPublish = new Map(skillFileMappings().map((mapping) => [mapping.publishPath, mapping.installedPath]));
-    const pinnedExpectedByPath = new Map();
-    if (pluginPinnedKit !== undefined) {
-        for (const file of pluginPinnedKit.manifest.files) {
-            const installedPath = installedByPublish.get(file.path);
-            const content = pluginPinnedKit.files.get(file.path);
-            if (installedPath !== undefined && content !== undefined) {
-                pinnedExpectedByPath.set(installedPath, content);
-            }
-        }
-    }
+    const projectMetadata = resolveAgentProjectMetadata(args.project);
     const checks = args.agents.flatMap((target) => {
-        const files = renderAgentFiles({ targets: [target] });
-        const expectedByPath = pluginPinnedKit !== undefined
-            ? pinnedExpectedByPath
-            : new Map(files.map((file) => [file.path, file.content]));
-        const installedSkillVersion = readInstalledSkillVersion(join(args.project, target === 'codex'
-            ? '.agents/skills/noodle-seed/SKILL.md'
-            : '.claude/skills/noodle-seed/SKILL.md'));
-        const shouldHashCheckReferences = installedSkillVersion === (pluginRequiredVersion ?? AGENT_KIT_VERSION);
+        const bundled = renderAgentFiles({ targets: [target], project: projectMetadata });
+        const state = readManagedSkillState(args.project, target);
+        const useOwnedSnapshot = pluginPinnedKit === undefined &&
+            state !== undefined &&
+            state.packageVersion !== AGENT_KIT_VERSION;
+        const generatedBase = pluginPinnedKit !== undefined
+            ? pluginPinnedKit.manifest.files
+                .filter((file) => file.agentTarget === target)
+                .map((file) => ({
+                path: file.installedPath,
+                mode: 'generated-file',
+                skill: file.skill,
+                skillVersion: file.skillVersion,
+                expectedSha256: file.sha256,
+            }))
+            : useOwnedSnapshot
+                ? state.files.map((file) => ({
+                    path: file.path,
+                    mode: 'generated-file',
+                    skill: file.skill,
+                    skillVersion: file.skillVersion,
+                    expectedSha256: file.sha256,
+                }))
+                : bundled
+                    .filter((file) => file.mode === 'generated-file')
+                    .map((file) => ({
+                    path: file.path,
+                    mode: file.mode,
+                    skill: file.skill ?? failMissingSkillIdentity(file.path),
+                    skillVersion: file.skillVersion ?? failMissingSkillIdentity(file.path),
+                    expectedSha256: contentSha256(file.content),
+                }));
+        const generated = pluginPinnedKit === undefined && state !== undefined && !useOwnedSnapshot
+            ? [
+                ...generatedBase,
+                ...state.files
+                    .filter((file) => !generatedBase.some((candidate) => candidate.path === file.path))
+                    .map((file) => ({
+                    path: file.path,
+                    mode: 'generated-file',
+                    skill: file.skill,
+                    skillVersion: file.skillVersion,
+                    expectedSha256: file.sha256,
+                })),
+            ]
+            : generatedBase;
+        const files = [
+            ...bundled
+                .filter((file) => file.mode === 'managed-block')
+                .map((file) => ({
+                path: file.path,
+                mode: file.mode,
+                expectedContent: file.content,
+            })),
+            ...generated,
+        ];
         const referenceBaselineAvailable = pluginRequiredVersion === undefined ||
             pluginRequiredVersion === AGENT_KIT_VERSION ||
             pluginPinnedKit !== undefined;
@@ -236,27 +320,64 @@ async function runAgentDoctor(args, env, configLocation) {
                         message: 'run noodle agents setup --write',
                     };
                 }
-                // Only the router SKILL.md carries version frontmatter; bundled-version references are hash-checked.
+                if (file.mode === 'managed-block' && file.expectedContent !== undefined) {
+                    const reconciliation = reconcileManagedBlock({
+                        existing: readFileSync(path, 'utf8'),
+                        block: file.expectedContent.trimEnd(),
+                    });
+                    if (reconciliation.action !== 'unchanged') {
+                        return {
+                            name: file.path,
+                            level: 'WARN',
+                            message: 'modified or stale; run noodle agents setup --write',
+                        };
+                    }
+                }
+                const skillVersion = file.mode === 'generated-file' && file.skill !== undefined
+                    ? readInstalledSkillVersion(join(args.project, `${target === 'codex' ? '.agents' : '.claude'}/skills/${file.skill}/SKILL.md`))
+                    : undefined;
                 if (file.mode === 'generated-file' && file.path.endsWith('/SKILL.md')) {
-                    const pluginVersionMismatch = pluginRequiredVersion !== undefined && installedSkillVersion !== pluginRequiredVersion;
+                    const comparisonVersion = pluginRequiredVersion ?? expectedSkillsVersion;
+                    const pluginVersionMismatch = pluginRequiredVersion !== undefined && skillVersion !== pluginRequiredVersion;
                     const staleness = pluginVersionMismatch
                         ? 'stale'
-                        : skillStaleness(installedSkillVersion, expectedSkillsVersion);
+                        : skillStaleness(skillVersion, comparisonVersion);
                     const expectedVersionLabel = pluginRequiredVersion !== undefined ? 'plugin-required' : 'registry';
+                    if (staleness !== 'stale' && file.expectedSha256 !== undefined) {
+                        const current = contentSha256(readFileSync(path, 'utf8')) === file.expectedSha256;
+                        if (!current) {
+                            return {
+                                name: file.path,
+                                level: 'WARN',
+                                message: 'modified; run noodle agents setup --write',
+                            };
+                        }
+                    }
                     return {
                         name: file.path,
                         level: staleness === 'stale' ? 'WARN' : 'PASS',
                         message: staleness === 'stale'
                             ? pluginVersionMismatch
-                                ? `installed v${installedSkillVersion ?? '?'} does not match ${expectedVersionLabel} v${expectedSkillsVersion}`
-                                : `installed v${installedSkillVersion ?? '?'} is older than ${expectedVersionLabel} v${expectedSkillsVersion}`
+                                ? `installed v${skillVersion ?? '?'} does not match ${expectedVersionLabel} v${comparisonVersion}`
+                                : `installed v${skillVersion ?? '?'} is older than ${expectedVersionLabel} v${comparisonVersion}`
                             : staleness === 'current'
                                 ? `current`
                                 : 'present',
                     };
                 }
                 if (file.mode === 'generated-file' &&
-                    shouldHashCheckReferences &&
+                    !file.path.endsWith('/SKILL.md') &&
+                    pluginRequiredVersion !== undefined &&
+                    pluginPinnedKit === undefined &&
+                    skillVersion === pluginRequiredVersion) {
+                    return {
+                        name: file.path,
+                        level: 'WARN',
+                        message: `plugin-required v${pluginRequiredVersion} cache unavailable; run noodle agents setup --write`,
+                    };
+                }
+                if (file.mode === 'generated-file' &&
+                    skillVersion === file.skillVersion &&
                     !file.path.endsWith('/SKILL.md')) {
                     if (!referenceBaselineAvailable) {
                         return {
@@ -265,9 +386,8 @@ async function runAgentDoctor(args, env, configLocation) {
                             message: `plugin-required v${pluginRequiredVersion} cache unavailable; run noodle agents setup --write`,
                         };
                     }
-                    const expected = expectedByPath.get(file.path);
                     const actual = readFileSync(path, 'utf8');
-                    const current = expected !== undefined && contentSha256(actual) === contentSha256(expected);
+                    const current = file.expectedSha256 !== undefined && contentSha256(actual) === file.expectedSha256;
                     return {
                         name: file.path,
                         level: current ? 'PASS' : 'WARN',