@hongmaple0820/scale-engine 0.40.0 → 0.40.2

package/dist/bootstrap/DependencyBootstrap.js

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { execa, execaSync } from 'execa';
@@ -9,14 +9,22 @@ import { wrapShellCommandWithRtk } from '../tools/RtkRuntime.js';
 import { inspectToolCapabilities } from '../tools/ToolCapabilityRegistry.js';
 const UI_SKILL_INSTALLS = {
     'awesome-design-md': (ctx) => {
-        const installDir = quotePath(join(ctx.homeDir, '.scale', 'vendor', 'awesome-design-md'));
-        return `npx degit VoltAgent/awesome-design-md ${installDir}`;
+        const skillDir = quotePath(join(ctx.homeDir, '.agents', 'skills', 'awesome-design-md'));
+        const vendorDir = quotePath(join(ctx.homeDir, '.scale', 'vendor', 'awesome-design-md'));
+        return `install skill adapter ${skillDir} from VoltAgent/awesome-design-md into ${vendorDir}`;
+    },
+    'ui-ux-pro-max': (ctx) => {
+        const skillDir = quotePath(join(ctx.homeDir, '.agents', 'skills', 'ui-ux-pro-max'));
+        const vendorDir = quotePath(join(ctx.homeDir, '.scale', 'vendor', 'ui-ux-pro-max'));
+        return `install skill adapter ${skillDir} from nextlevelbuilder/ui-ux-pro-max-skill into ${vendorDir}`;
     },
-    'ui-ux-pro-max': 'npx uipro-cli init --ai codex',
     'frontend-design': 'npx skills add anthropics/skills --skill frontend-design',
 };
 const RTK_INSTALL = 'cargo install --git https://github.com/rtk-ai/rtk';
+const RTK_INIT = 'rtk init -g --codex';
 const CODEGRAPH_INSTALL = 'npm install -g @colbymchenry/codegraph';
+const GRAPHIFY_CODEX_INSTALL = 'graphify install --platform codex';
+const GRAPHIFY_HOOK_INSTALL = 'graphify hook install';
 const GRAPHIFY_UV_INSTALL = 'uv tool install graphify && graphify install --platform codex';
 const GRAPHIFY_PIPX_INSTALL = 'pipx install graphify && graphify install --platform codex';
 const GRAPHIFY_PIP_INSTALL = 'pip install graphify && graphify install --platform codex';
@@ -33,10 +41,20 @@ const DEPENDENCY_BOOTSTRAP_DEFINITIONS = [
         packs: ['ui'],
         source: 'https://github.com/VoltAgent/awesome-design-md',
         detectSkillId: 'awesome-design-md',
-        detectPaths: ctx => [join(ctx.homeDir, '.scale', 'vendor', 'awesome-design-md', 'README.md')],
-        prerequisites: ['npx'],
-        manualReason: 'Requires npm/npx to sync the upstream DESIGN.md catalog that drives brand and visual-language decisions.',
-        installCommand: ctx => ctx.commandExists('npx') ? UI_SKILL_INSTALLS['awesome-design-md'](ctx) : null,
+        prerequisites: ['git|npx'],
+        manualReason: 'Requires Git or npm/npx to sync the upstream DESIGN.md catalog and create a local SCALE skill adapter.',
+        installCommand: ctx => requirementSatisfied('git|npx', ctx.commandExists) ? UI_SKILL_INSTALLS['awesome-design-md'](ctx) : null,
+        install: ctx => installSkillAdapter(ctx, {
+            id: 'awesome-design-md',
+            sourceUrl: 'https://github.com/VoltAgent/awesome-design-md.git',
+            repoSpecifier: 'VoltAgent/awesome-design-md',
+            description: 'Brand, visual language, and DESIGN.md source skill for SCALE UI work.',
+            instructions: [
+                'Use this skill before UI implementation when brand direction, visual language, DESIGN.md, color, typography, layout mood, or product identity must be defined.',
+                'Read the upstream vendor repository under ~/.scale/vendor/awesome-design-md, then create or update the project DESIGN.md with concrete visual decisions.',
+                'Do not use it as the accessibility or responsive QA gate; route those checks to ui-ux-pro-max.',
+            ],
+        }),
     },
     {
         id: 'ui-ux-pro-max',
@@ -45,9 +63,20 @@ const DEPENDENCY_BOOTSTRAP_DEFINITIONS = [
         packs: ['ui'],
         source: 'https://github.com/nextlevelbuilder/ui-ux-pro-max-skill',
         detectSkillId: 'ui-ux-pro-max',
-        prerequisites: ['npx'],
-        manualReason: 'Requires npm/npx so the official uipro-cli installer can configure the UX, state, accessibility, and responsive-review skill.',
-        installCommand: ctx => ctx.commandExists('npx') ? UI_SKILL_INSTALLS['ui-ux-pro-max'] : null,
+        prerequisites: ['git|npx'],
+        manualReason: 'Requires Git or npm/npx to sync the upstream UX skill and create a local SCALE skill adapter.',
+        installCommand: ctx => requirementSatisfied('git|npx', ctx.commandExists) ? UI_SKILL_INSTALLS['ui-ux-pro-max'](ctx) : null,
+        install: ctx => installSkillAdapter(ctx, {
+            id: 'ui-ux-pro-max',
+            sourceUrl: 'https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git',
+            repoSpecifier: 'nextlevelbuilder/ui-ux-pro-max-skill',
+            description: 'UX flow, UI state, accessibility, and responsive acceptance skill for SCALE UI work.',
+            instructions: [
+                'Use this skill after visual direction is selected to review UX flow, state coverage, empty/error/loading behavior, keyboard access, accessibility, and responsive acceptance.',
+                'Read the upstream vendor repository under ~/.scale/vendor/ui-ux-pro-max for the current checklist and apply it as an acceptance gate.',
+                'Do not replace awesome-design-md for brand or visual-language decisions.',
+            ],
+        }),
     },
     {
         id: 'frontend-design',
@@ -70,6 +99,7 @@ const DEPENDENCY_BOOTSTRAP_DEFINITIONS = [
         prerequisites: ['cargo'],
         manualReason: 'RTK currently installs from the official Rust toolchain path and needs Cargo on PATH.',
         installCommand: ctx => ctx.commandExists('cargo') ? RTK_INSTALL : null,
+        initializeCommands: () => [RTK_INIT],
         healthCheck: checkRtkHealth,
     },
     {
@@ -82,6 +112,7 @@ const DEPENDENCY_BOOTSTRAP_DEFINITIONS = [
         prerequisites: ['bun'],
         manualReason: 'The official standalone GBrain install needs Bun and then a configured brain (`gbrain init --pglite`) before cross-session recall is usable.',
         installCommand: ctx => buildGbrainInstallCommand(ctx),
+        initializeCommands: () => ['gbrain init --pglite --no-embedding'],
         healthCheck: checkGbrainHealth,
     },
     {
@@ -94,6 +125,11 @@ const DEPENDENCY_BOOTSTRAP_DEFINITIONS = [
         prerequisites: ['uv|pipx|pip|pip3|python|python3'],
         manualReason: 'Graphify requires Python 3.10+ and a supported installer; uv tool install is preferred to avoid polluting project virtualenvs.',
         installCommand: ctx => buildGraphifyInstallCommand(ctx),
+        initializeCommands: ctx => [
+            GRAPHIFY_CODEX_INSTALL,
+            GRAPHIFY_HOOK_INSTALL,
+            `graphify update ${quotePath(ctx.projectDir)} --no-cluster`,
+        ],
         healthCheck: checkGraphifyHealth,
     },
     {
@@ -106,6 +142,7 @@ const DEPENDENCY_BOOTSTRAP_DEFINITIONS = [
         prerequisites: ['npm'],
         manualReason: 'CodeGraph installs through npm and needs Node.js/npm available on PATH.',
         installCommand: ctx => ctx.commandExists('npm') ? CODEGRAPH_INSTALL : null,
+        initializeCommands: ctx => [codegraphInitCommand(ctx.projectDir)],
         healthCheck: checkCodeGraphHealth,
     },
 ];
@@ -115,7 +152,8 @@ export async function bootstrapDependencies(options = {}) {
     const homeDir = homedir();
     const packIds = normalizePackIds(options.packIds);
     const includeIds = unique((options.includeIds ?? []).map(value => value.trim()).filter(Boolean));
-    const definitions = selectDefinitions(packIds, includeIds);
+    const onlyIds = unique((options.onlyIds ?? []).map(value => value.trim()).filter(Boolean));
+    const definitions = selectDefinitions(packIds, includeIds, onlyIds);
     const context = {
         projectDir,
         homeDir,
@@ -127,10 +165,12 @@ export async function bootstrapDependencies(options = {}) {
         for (const item of reports.filter(entry => entry.status === 'ready')) {
             if (!item.installCommand)
                 continue;
-            const result = await runInstallCommand(item.installCommand);
+            const definition = definitions.find(entry => entry.id === item.id);
+            const result = definition?.install
+                ? await definition.install(context)
+                : await runInstallCommand(item.installCommand, context.projectDir);
             item.output = result.output;
             item.error = result.error;
-            const definition = definitions.find(entry => entry.id === item.id);
             const rechecked = definition ? inspectDefinition(definition, context) : item;
             item.installed = rechecked.installed;
             item.detectedBy = rechecked.detectedBy;
@@ -143,6 +183,7 @@ export async function bootstrapDependencies(options = {}) {
             if (!result.ok)
                 item.installSupported = true;
         }
+        await reconcileDependencyBootstrapItems(definitions, reports, context);
     }
     const postActions = options.apply ? applyDependencyBootstrapPostActions(projectDir, scaleDir, reports) : [];
     const postChecks = options.apply
@@ -151,17 +192,22 @@ export async function bootstrapDependencies(options = {}) {
     return buildReport(projectDir, scaleDir, packIds, includeIds, Boolean(options.apply), runtimeChecks, reports, postActions, postChecks);
 }
 function buildReport(projectDir, scaleDir, packIds, includeIds, apply, runtimeChecks, items, postActions, postChecks) {
+    const nonBlockingItems = new Set(items
+        .filter(item => isNonBlockingOptionalItem(item, postChecks))
+        .map(item => item.id));
     const summary = {
         total: items.length,
         installed: items.filter(item => item.status === 'installed').length,
         ready: items.filter(item => item.status === 'ready').length,
         manualReview: items.filter(item => item.status === 'manual-review').length,
-        needsInit: items.filter(item => item.status === 'needs-init').length,
+        needsInit: items.filter(item => item.status === 'needs-init' && !nonBlockingItems.has(item.id)).length,
         versionDrift: items.filter(item => item.status === 'version-drift').length,
         installedNow: items.filter(item => item.status === 'installed-now').length,
         failed: items.filter(item => item.status === 'failed').length,
     };
-    const complete = items.length > 0 && items.every(item => item.status === 'installed' || item.status === 'installed-now');
+    const complete = items.length > 0 && items.every(item => item.status === 'installed'
+        || item.status === 'installed-now'
+        || nonBlockingItems.has(item.id));
     const postCheckSummary = {
         total: postChecks.length,
         passed: postChecks.filter(item => item.status === 'passed').length,
@@ -463,6 +509,12 @@ export function runDependencyBootstrapPostChecks(input, deps = {}) {
     const inspectCode = deps.inspectCode ?? inspectCodeIntelligence;
     const toolIds = unique(input.items.map(item => item.id).filter(id => ['awesome-design-md', 'ui-ux-pro-max', 'frontend-design', 'rtk', 'gbrain', 'codegraph', 'graphify'].includes(id)));
     const results = [];
+    const memoryReport = input.items.some(item => item.id === 'gbrain')
+        ? inspectMemory({ projectDir: input.projectDir, scaleDir: input.scaleDir })
+        : undefined;
+    const gbrain = memoryReport?.providers.find(provider => provider.id === 'gbrain');
+    const memoryFallback = memoryReport?.providers.find(provider => provider.kind === 'scale-local' && provider.available);
+    const softBlockedGbrain = Boolean(gbrain && !gbrain.available && memoryFallback);
     if (toolIds.length > 0) {
         const toolReport = inspectTools({
             projectDir: input.projectDir,
@@ -470,23 +522,31 @@ export function runDependencyBootstrapPostChecks(input, deps = {}) {
             toolIds,
         });
         const missing = toolReport.tools.filter(tool => !tool.installed).map(tool => tool.id);
+        const degraded = missing.filter(id => id === 'gbrain' && softBlockedGbrain);
+        const blockingMissing = missing.filter(id => !degraded.includes(id));
         results.push({
             id: 'tool-capabilities',
             label: 'Tool Doctor',
             command: `scale tool doctor --tools ${toolIds.join(',')} --json`,
-            status: toolReport.ok ? 'passed' : 'failed',
-            summary: `${toolReport.summary.installed}/${toolReport.summary.total} selected tools are available${missing.length > 0 ? `; missing: ${missing.join(', ')}` : ''}`,
+            status: blockingMissing.length > 0 ? 'failed' : degraded.length > 0 ? 'warn' : 'passed',
+            summary: [
+                `${toolReport.summary.installed}/${toolReport.summary.total} selected tools are available`,
+                blockingMissing.length > 0 ? `missing: ${blockingMissing.join(', ')}` : undefined,
+                degraded.length > 0 ? `degraded: ${degraded.join(', ')} (scale-local fallback active)` : undefined,
+            ].filter(Boolean).join('; '),
             details: {
                 toolIds,
-                missing,
+                missing: blockingMissing,
+                degraded,
+                fallbackProvider: memoryFallback?.id,
             },
         });
     }
-    if (input.items.some(item => item.id === 'gbrain')) {
-        const memoryReport = inspectMemory({ projectDir: input.projectDir, scaleDir: input.scaleDir });
-        const gbrain = memoryReport.providers.find(provider => provider.id === 'gbrain');
+    if (memoryReport) {
         const warnings = [...memoryReport.warnings];
-        const status = !gbrain?.available ? 'failed' : warnings.length > 0 ? 'warn' : 'passed';
+        if (softBlockedGbrain)
+            warnings.push(`gbrain is unavailable in this runtime; falling back to ${memoryFallback.id}`);
+        const status = !gbrain?.available ? (softBlockedGbrain ? 'warn' : 'failed') : warnings.length > 0 ? 'warn' : 'passed';
         results.push({
             id: 'memory-provider',
             label: 'Memory Provider',
@@ -498,6 +558,7 @@ export function runDependencyBootstrapPostChecks(input, deps = {}) {
             details: {
                 warnings,
                 gbrainReason: gbrain?.reason,
+                fallbackProvider: memoryFallback?.id,
             },
         });
     }
@@ -533,6 +594,13 @@ export function runDependencyBootstrapPostChecks(input, deps = {}) {
     }
     return results;
 }
+function isNonBlockingOptionalItem(item, postChecks) {
+    if (item.id !== 'gbrain' || item.status !== 'needs-init')
+        return false;
+    return postChecks.some(check => check.id === 'memory-provider'
+        && check.status === 'warn'
+        && check.details?.fallbackProvider === 'scale-local');
+}
 function inspectDefinition(definition, context) {
     const detectedBy = detectDefinition(definition, context.projectDir, context.homeDir);
     const installed = detectedBy !== 'missing';
@@ -607,7 +675,25 @@ function buildGbrainInstallCommand(context) {
         return null;
     return GBRAIN_INSTALL;
 }
-function checkRtkHealth() {
+function codegraphInitCommand(projectDir) {
+    const command = `codegraph init -i ${quotePath(projectDir)}`;
+    return process.platform === 'win32' ? `cmd /d /c ${command}` : command;
+}
+export function hasCodexRtkInstructions(homeDir) {
+    const codexDir = join(homeDir, '.codex');
+    const rtkPath = join(codexDir, 'RTK.md');
+    const agentsPath = join(codexDir, 'AGENTS.md');
+    if (!existsSync(rtkPath) || !existsSync(agentsPath))
+        return false;
+    try {
+        const agents = readFileSync(agentsPath, 'utf-8');
+        return /RTK\.md/i.test(agents);
+    }
+    catch {
+        return false;
+    }
+}
+function checkRtkHealth(context) {
     const gain = runHealthCommand('rtk', ['gain']);
     if (!gain.ok) {
         return {
@@ -619,11 +705,15 @@ function checkRtkHealth() {
     }
     const output = `${gain.stdout}\n${gain.stderr}`;
     if (/no hook installed/i.test(output)) {
+        if (hasCodexRtkInstructions(context.homeDir)) {
+            return {
+                status: 'ok',
+                reason: 'rtk gain evidence is available; Codex mode uses RTK.md instructions instead of an automatic shell hook.',
+            };
+        }
         return {
-            status: 'warn',
-            bootstrapStatus: 'needs-init',
-            reason: 'rtk CLI is installed, but the shell hook is not installed so command-output compression is not automatic yet.',
-            nextCommands: ['rtk init -g --codex', 'rtk gain'],
+            status: 'ok',
+            reason: 'rtk gain evidence is available; automatic hook installation is not active, so SCALE should keep using the explicit `rtk <command>` proxy path.',
         };
     }
     return { status: 'ok', reason: 'rtk CLI and gain evidence are available.' };
@@ -633,7 +723,6 @@ function checkGbrainHealth() {
     if (health.available) {
         return {
             status: health.degraded ? 'warn' : 'ok',
-            bootstrapStatus: health.degraded ? 'manual-review' : undefined,
             reason: health.degraded
                 ? `${health.reason}; provider can still be used for read-only recall.`
                 : 'gbrain doctor passed; provider can be used for default memory routing.',
@@ -648,9 +737,52 @@ function checkGbrainHealth() {
         nextCommands: ['gbrain init --pglite', 'gbrain doctor --json', 'scale memory provider status --json'],
     };
 }
-function checkGraphifyHealth() {
-    const version = runHealthCommand('graphify', ['--version']);
-    const hook = runHealthCommand('graphify', ['hook', 'status'], 10_000);
+async function reconcileDependencyBootstrapItems(definitions, reports, context) {
+    const definitionsById = new Map(definitions.map(definition => [definition.id, definition]));
+    for (const item of reports) {
+        if (item.status !== 'needs-init' && item.status !== 'version-drift')
+            continue;
+        const definition = definitionsById.get(item.id);
+        const commands = definition?.initializeCommands?.(context) ?? [];
+        if (commands.length === 0)
+            continue;
+        const outputs = [item.output].filter(Boolean);
+        const errors = [item.error].filter(Boolean);
+        let ok = true;
+        for (const command of commands) {
+            const result = await runInstallCommand(command, context.projectDir);
+            if (result.output)
+                outputs.push(result.output);
+            if (result.error)
+                errors.push(result.error);
+            if (!result.ok) {
+                ok = false;
+                if (!result.error)
+                    errors.push(`Initialization command failed: ${command}`);
+                break;
+            }
+        }
+        item.output = outputs.join('\n') || undefined;
+        item.error = errors.join('\n') || undefined;
+        if (!ok) {
+            const rechecked = definition ? inspectDefinition(definition, context) : item;
+            item.installed = rechecked.installed;
+            item.detectedBy = rechecked.detectedBy;
+            item.health = rechecked.health;
+            item.status = definition?.id === 'gbrain' && rechecked.installed ? rechecked.status : 'failed';
+            continue;
+        }
+        const rechecked = definition ? inspectDefinition(definition, context) : item;
+        item.installed = rechecked.installed;
+        item.detectedBy = rechecked.detectedBy;
+        item.health = rechecked.health;
+        item.status = rechecked.status === 'installed' ? 'installed-now' : rechecked.status;
+    }
+}
+function checkGraphifyHealth(context) {
+    const graphPath = join(context.projectDir, 'graphify-out', 'graph.json');
+    const version = runHealthCommand('graphify', ['--version'], 5_000, context.projectDir);
+    const hook = runHealthCommand('graphify', ['hook', 'status'], 10_000, context.projectDir);
     const output = `${version.stdout}\n${version.stderr}\n${hook.stdout}\n${hook.stderr}`;
     if (/skill.*version|package.*version|drift|outdated/i.test(output)) {
         return {
@@ -668,7 +800,15 @@ function checkGraphifyHealth() {
             nextCommands: ['graphify install --platform codex', 'graphify hook status'],
         };
     }
-    return { status: 'ok', reason: 'graphify CLI and hook status are available.' };
+    if (!existsSync(graphPath)) {
+        return {
+            status: 'warn',
+            bootstrapStatus: 'needs-init',
+            reason: 'graphify CLI is installed but graphify-out/graph.json is not present yet.',
+            nextCommands: [`graphify update ${quotePath(context.projectDir)} --no-cluster`, 'scale codegraph status --json'],
+        };
+    }
+    return { status: 'ok', reason: 'graphify CLI, hooks, and graph artifact are available.' };
 }
 function checkCodeGraphHealth(context) {
     const indexPath = join(context.projectDir, '.codegraph');
@@ -691,11 +831,12 @@ function checkCodeGraphHealth(context) {
     }
     return { status: 'ok', reason: 'codegraph CLI and project index are available.' };
 }
-function runHealthCommand(command, args, timeout = 5_000) {
+function runHealthCommand(command, args, timeout = 5_000, cwd) {
     try {
         const result = execaSync(command, args, {
             reject: false,
             timeout,
+            cwd,
         });
         return {
             ok: (result.exitCode ?? 1) === 0,
@@ -718,17 +859,85 @@ function firstLine(value) {
 function quotePath(path) {
     return `"${path.replace(/"/g, '\\"')}"`;
 }
-async function runInstallCommand(shellCommand) {
+async function runInstallCommand(shellCommand, cwd) {
     const wrapped = wrapShellCommandWithRtk(shellCommand);
     const result = wrapped
-        ? await execa(wrapped.command, wrapped.args, { reject: false, timeout: 300_000, all: false })
-        : await execa(shellCommand, { shell: true, reject: false, timeout: 300_000, all: false });
+        ? await execa(wrapped.command, wrapped.args, { reject: false, timeout: 300_000, all: false, cwd })
+        : await execa(shellCommand, { shell: true, reject: false, timeout: 300_000, all: false, cwd });
     return {
         ok: (result.exitCode ?? 1) === 0,
         output: result.stdout ?? '',
         error: result.stderr ?? '',
     };
 }
+async function installSkillAdapter(context, input) {
+    const vendorDir = join(context.homeDir, '.scale', 'vendor', input.id);
+    const skillDir = join(context.homeDir, '.agents', 'skills', input.id);
+    const outputs = [];
+    const errors = [];
+    mkdirSync(join(context.homeDir, '.scale', 'vendor'), { recursive: true });
+    mkdirSync(skillDir, { recursive: true });
+    if (!existsSync(vendorDir) || isEmptyDirectory(vendorDir)) {
+        if (context.commandExists('git')) {
+            const clone = await execa('git', ['clone', '--depth', '1', input.sourceUrl, vendorDir], { reject: false });
+            outputs.push(clone.stdout ?? '');
+            errors.push(clone.stderr ?? '');
+            if ((clone.exitCode ?? 1) !== 0)
+                return { ok: false, output: outputs.join('\n'), error: errors.join('\n') };
+        }
+        else if (context.commandExists('npx')) {
+            const degit = await execa('npx', ['degit', input.repoSpecifier, vendorDir], { reject: false });
+            outputs.push(degit.stdout ?? '');
+            errors.push(degit.stderr ?? '');
+            if ((degit.exitCode ?? 1) !== 0)
+                return { ok: false, output: outputs.join('\n'), error: errors.join('\n') };
+        }
+        else {
+            return { ok: false, error: 'Git or npx is required to install third-party skills.' };
+        }
+    }
+    else if (existsSync(join(vendorDir, '.git')) && context.commandExists('git')) {
+        const pull = await execa('git', ['-C', vendorDir, 'pull', '--ff-only'], { reject: false });
+        outputs.push(pull.stdout ?? '');
+        errors.push(pull.stderr ?? '');
+        if ((pull.exitCode ?? 1) !== 0)
+            return { ok: false, output: outputs.join('\n'), error: errors.join('\n') };
+    }
+    else {
+        outputs.push(`Reused existing vendor directory: ${vendorDir}`);
+    }
+    writeFileSync(join(skillDir, 'SKILL.md'), renderSkillAdapter(input, vendorDir), 'utf-8');
+    outputs.push(`Wrote skill adapter: ${join(skillDir, 'SKILL.md')}`);
+    return { ok: true, output: outputs.filter(Boolean).join('\n'), error: errors.filter(Boolean).join('\n') };
+}
+function isEmptyDirectory(path) {
+    return existsSync(path) && readdirSync(path).length === 0;
+}
+function renderSkillAdapter(input, vendorDir) {
+    const lines = [
+        '---',
+        `name: ${input.id}`,
+        `description: ${input.description}`,
+        '---',
+        '',
+        `# ${input.id}`,
+        '',
+        `Source: ${input.sourceUrl}`,
+        `Vendor path: ${vendorDir}`,
+        '',
+        '## When To Use',
+        '',
+        ...input.instructions.map(item => `- ${item}`),
+        '',
+        '## Operating Rules',
+        '',
+        '- Prefer concrete project artifacts over generic advice.',
+        '- If the vendor directory is missing or outdated, run `scale setup --pack ui --apply` again.',
+        '- Keep generated project outputs, such as DESIGN.md, inside the target project rather than this skill directory.',
+        '',
+    ];
+    return `${lines.join('\n')}\n`;
+}
 export function applyDependencyBootstrapPostActions(projectDir, scaleDir, items, deps = {}) {
     const writeMemoryConfig = deps.writeMemoryConfig ?? writeMemoryProvidersConfig;
     const switchMemoryProvider = deps.switchMemoryProvider ?? useMemoryProvider;
@@ -751,10 +960,12 @@ export function applyDependencyBootstrapPostActions(projectDir, scaleDir, items,
     }
     return actions;
 }
-function selectDefinitions(packIds, includeIds) {
+function selectDefinitions(packIds, includeIds, onlyIds = []) {
     const selectedPacks = new Set(packIds.includes('full') ? ['ui', 'memory', 'knowledge', 'external-cli'] : packIds);
     const selectedIds = new Set(includeIds);
-    return DEPENDENCY_BOOTSTRAP_DEFINITIONS.filter(definition => definition.packs.some(pack => selectedPacks.has(pack)) || selectedIds.has(definition.id));
+    const only = new Set(onlyIds);
+    return DEPENDENCY_BOOTSTRAP_DEFINITIONS.filter(definition => (only.size === 0 || only.has(definition.id)) &&
+        (definition.packs.some(pack => selectedPacks.has(pack)) || selectedIds.has(definition.id)));
 }
 function buildPostCheckCommands(packIds, items) {
     const commands = new Set();