@guidobuilds/forge-ai 0.3.0 → 0.6.0

package/dist/src/adapters/grok.js

@@ -0,0 +1,41 @@
+import { stringifyYaml } from '../frontmatter.js';
+import { diagnostic } from '../diagnostics.js';
+import { isKnownGrokModel, isKnownGrokTool } from './grok-known.js';
+import { isRecord, patternList, stringList } from './shared.js';
+export function renderGrokAgent(artifact) {
+    const diagnostics = [];
+    const fm = { name: artifact.name, description: artifact.description };
+    if (artifact.grok?.model) {
+        fm.model = artifact.grok.model;
+        if (!isKnownGrokModel(artifact.grok.model)) {
+            diagnostics.push(diagnostic('warning', 'GROK_UNKNOWN_MODEL', `Unknown Grok model "${artifact.grok.model}" for ${artifact.name}`, { platform: 'grok' }));
+        }
+    }
+    const permissions = artifact.grok?.permissions;
+    const tools = isRecord(permissions) ? stringList(permissions.tools) : stringList(permissions);
+    if (tools) {
+        fm.tools = tools; // YAML sequence — Grok expects tools as a list, not comma-joined
+        for (const tool of tools) {
+            if (!isKnownGrokTool(tool)) {
+                diagnostics.push(diagnostic('warning', 'GROK_UNKNOWN_TOOL', `Unknown Grok tool "${tool}" for ${artifact.name}`, { platform: 'grok' }));
+            }
+        }
+    }
+    else if (permissions !== undefined) {
+        diagnostics.push(diagnostic('info', 'GROK_AGENT_TOOLS_IGNORED', `Grok agent permissions must be a tools string list for ${artifact.name}`, { platform: 'grok' }));
+    }
+    const disallowedTools = isRecord(permissions) ? patternList(permissions['disallowedTools']) : undefined;
+    if (disallowedTools)
+        fm.disallowedTools = disallowedTools;
+    return { content: `${stringifyYaml(fm)}${artifact.body}\n`, diagnostics };
+}
+export function renderGrokSkill(artifact) {
+    const diagnostics = [];
+    if (artifact.grok?.permissions !== undefined) {
+        diagnostics.push(diagnostic('info', 'GROK_SKILL_PERMISSIONS_IGNORED', `Grok skill permissions are not emitted for ${artifact.name}`, { platform: 'grok' }));
+    }
+    if (artifact.grok?.model) {
+        diagnostics.push(diagnostic('info', 'GROK_SKILL_MODEL_IGNORED', `Grok skill model is not emitted for ${artifact.name}`, { platform: 'grok' }));
+    }
+    return { content: `${stringifyYaml({ name: artifact.name, description: artifact.description })}${artifact.body}\n`, diagnostics };
+}

package/dist/src/cli.js

@@ -8,6 +8,8 @@ import { fileURLToPath } from 'node:url';
 import { formatDiagnostic, hasErrors } from './diagnostics.js';
 import { buildManifest, classifyPruneEntries, loadManifest, pruneEntries, resolveBackupPath, resolveBackupRoot, resolveManifestLocation, saveManifest, staleEntries } from './manifest.js';
 import { buildWritePlan, parsePlatform, parseScope } from './processor.js';
+import { runSelfUpdate } from './self-update.js';
+import { checkLatestVersion, formatVersionNotice } from './version-check.js';
 import { writeOutputs } from './writer.js';
 import { hasPendingDecisions } from './model.js';
 const emptyPrunePlan = { deletable: [], modifiedWithConsent: [], skippedMissing: [] };
@@ -32,108 +34,129 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
         showUsage();
         return 1;
     }
-    const install = command === 'install' || command === 'update';
-    if (install && !options.sourceExplicit)
-        options.source = bundledSourceRoot();
-    if (command === 'update' || options.yes)
-        options.force = true;
-    const interactive = install && isInteractivePrompt(promptIO);
-    if (interactive)
-        p.intro(`${pc.bold('Forge AI')} ${pc.dim(command === 'update' ? 'updater' : 'installer')}`, clackIO(promptIO));
-    if (install) {
-        const prompted = await promptForMissingInstallOptions(options, promptIO);
-        if (!prompted) {
-            if (interactive)
-                p.cancel('Cancelled', clackIO(promptIO));
-            return 1;
-        }
-    }
-    const cwd = process.cwd();
-    const home = resolveHome(promptIO);
-    const now = new Date();
-    let manifestLocation;
-    let oldManifest;
-    let backupRoot;
-    if (install) {
-        manifestLocation = await resolveManifestLocation(options.scope, cwd, home);
-        oldManifest = await loadManifest(manifestLocation.manifestPath);
-        backupRoot = resolveBackupRoot(manifestLocation, now);
-    }
-    const plan = await buildWritePlan({
-        source: options.source,
-        platform: options.platform,
-        scope: options.scope,
-        cwd,
-        home,
-        manifest: oldManifest,
-        backupRoot,
-        checkCollisions: install,
-    });
-    let prunePlan = emptyPrunePlan;
-    if (install && command === 'update' && options.prune) {
-        prunePlan = await classifyPrune(oldManifest, plan.files, backupRoot, options.scope, cwd, home);
+    if (command === 'self-update') {
+        return runSelfUpdate({
+            binaryPath: process.argv[1] ?? bundledSourceRoot(),
+            version: options.targetVersion,
+            dryRun: options.dryRun,
+            skipSpecUpdate: options.skipSpecUpdate,
+        });
     }
-    const needsConfirm = install && !options.force && (hasPendingDecisions(plan.pending) || prunePlan.modifiedWithConsent.length > 0);
-    if (install && !options.dryRun && needsConfirm) {
-        if (!interactive) {
-            printPlan(command, plan.sourceCount, plan.files, plan.diagnostics, prunePlan);
-            console.error('Forge needs your decision on edited or untracked files; re-run with --yes or --force to accept overwrites + backups.');
-            return 1;
+    const versionCheckPromise = shouldCheckForUpdates(options, promptIO)
+        ? checkLatestVersion({ current: readPackageVersion(), cachePath: path.join(resolveHome(promptIO), '.forge-ai', 'version-check.json') }).catch(() => undefined)
+        : Promise.resolve(undefined);
+    try {
+        const install = command === 'install' || command === 'update';
+        if (install && !options.sourceExplicit)
+            options.source = bundledSourceRoot();
+        if (command === 'update' || options.yes)
+            options.force = true;
+        const interactive = install && isInteractivePrompt(promptIO);
+        if (interactive)
+            p.intro(`${pc.bold('Forge AI')} ${pc.dim(command === 'update' ? 'updater' : 'installer')}`, clackIO(promptIO));
+        if (install) {
+            const prompted = await promptForMissingInstallOptions(options, promptIO);
+            if (!prompted) {
+                if (interactive)
+                    p.cancel('Cancelled', clackIO(promptIO));
+                return 1;
+            }
         }
-        const accepted = await promptForUpdate(plan, prunePlan, backupRoot, promptIO);
-        if (accepted === undefined) {
-            p.cancel('Cancelled', clackIO(promptIO));
-            return 1;
+        const cwd = process.cwd();
+        const home = resolveHome(promptIO);
+        const now = new Date();
+        let manifestLocation;
+        let oldManifest;
+        let backupRoot;
+        if (install) {
+            manifestLocation = await resolveManifestLocation(options.scope, cwd, home);
+            oldManifest = await loadManifest(manifestLocation.manifestPath);
+            backupRoot = resolveBackupRoot(manifestLocation, now);
         }
-        if (!accepted) {
-            p.outro(pc.yellow('Forge was not installed.'), clackIO(promptIO));
+        const plan = await buildWritePlan({
+            source: options.source,
+            platform: options.platform,
+            scope: options.scope,
+            cwd,
+            home,
+            manifest: oldManifest,
+            backupRoot,
+            checkCollisions: install,
+        });
+        let prunePlan = emptyPrunePlan;
+        if (install && command === 'update' && options.prune) {
+            prunePlan = await classifyPrune(oldManifest, plan.files, backupRoot, options.scope, cwd, home);
+        }
+        const needsConfirm = install && !options.force && (hasPendingDecisions(plan.pending) || prunePlan.modifiedWithConsent.length > 0);
+        if (install && !options.dryRun && needsConfirm) {
+            if (!interactive) {
+                printPlan(command, plan.sourceCount, plan.files, plan.diagnostics, prunePlan);
+                console.error('Forge needs your decision on edited or untracked files; re-run with --yes or --force to accept overwrites + backups.');
+                return 1;
+            }
+            const accepted = await promptForUpdate(plan, prunePlan, backupRoot, promptIO);
+            if (accepted === undefined) {
+                p.cancel('Cancelled', clackIO(promptIO));
+                return 1;
+            }
+            if (!accepted) {
+                p.outro(pc.yellow('Forge was not installed.'), clackIO(promptIO));
+                return 1;
+            }
+        }
+        printPlan(command, plan.sourceCount, plan.files, plan.diagnostics, prunePlan);
+        if (hasErrors(plan.diagnostics)) {
+            if (interactive)
+                p.outro(pc.red('Forge was not installed.'), clackIO(promptIO));
             return 1;
         }
-    }
-    printPlan(command, plan.sourceCount, plan.files, plan.diagnostics, prunePlan);
-    if (hasErrors(plan.diagnostics)) {
-        if (interactive)
-            p.outro(pc.red('Forge was not installed.'), clackIO(promptIO));
-        return 1;
-    }
-    if (install && !options.dryRun) {
-        if (interactive) {
-            const spinner = p.spinner(clackIO(promptIO));
-            spinner.start(options.force ? 'Updating Forge files' : 'Installing Forge files');
-            try {
+        if (install && !options.dryRun) {
+            if (interactive) {
+                const spinner = p.spinner(clackIO(promptIO));
+                spinner.start(options.force ? 'Updating Forge files' : 'Installing Forge files');
+                try {
+                    await writeOutputs(plan.files);
+                    if (command === 'update' && options.prune)
+                        await pruneEntries([...prunePlan.deletable, ...prunePlan.modifiedWithConsent]);
+                    await saveManifest(manifestLocation.manifestPath, await buildManifest(manifestLocation, plan.files));
+                    spinner.stop(`Wrote ${plan.files.length} file(s).`);
+                }
+                catch (error) {
+                    spinner.error('Failed to write Forge files');
+                    throw error;
+                }
+            }
+            else {
                 await writeOutputs(plan.files);
                 if (command === 'update' && options.prune)
                     await pruneEntries([...prunePlan.deletable, ...prunePlan.modifiedWithConsent]);
                 await saveManifest(manifestLocation.manifestPath, await buildManifest(manifestLocation, plan.files));
-                spinner.stop(`Wrote ${plan.files.length} file(s).`);
-            }
-            catch (error) {
-                spinner.error('Failed to write Forge files');
-                throw error;
+                console.log(`Wrote ${plan.files.length} file(s).`);
+                const totalDeleted = prunePlan.deletable.length + prunePlan.modifiedWithConsent.length;
+                if (command === 'update' && options.prune && totalDeleted > 0)
+                    console.log(`Deleted ${totalDeleted} stale file(s).`);
+                console.log(`Updated manifest ${manifestLocation.manifestPath}.`);
             }
         }
-        else {
-            await writeOutputs(plan.files);
-            if (command === 'update' && options.prune)
-                await pruneEntries([...prunePlan.deletable, ...prunePlan.modifiedWithConsent]);
-            await saveManifest(manifestLocation.manifestPath, await buildManifest(manifestLocation, plan.files));
-            console.log(`Wrote ${plan.files.length} file(s).`);
-            const totalDeleted = prunePlan.deletable.length + prunePlan.modifiedWithConsent.length;
-            if (command === 'update' && options.prune && totalDeleted > 0)
-                console.log(`Deleted ${totalDeleted} stale file(s).`);
-            console.log(`Updated manifest ${manifestLocation.manifestPath}.`);
+        else if (install && interactive) {
+            p.log.info(`Dry run only. ${plan.files.length} file(s) would be written.`, clackIO(promptIO));
         }
+        if (install && interactive) {
+            p.outro(options.dryRun ? pc.cyan('Dry run complete.') : pc.green('Forge is ready.'), clackIO(promptIO));
+        }
+        return 0;
     }
-    else if (install && interactive) {
-        p.log.info(`Dry run only. ${plan.files.length} file(s) would be written.`, clackIO(promptIO));
-    }
-    if (install && interactive) {
-        p.outro(options.dryRun ? pc.cyan('Dry run complete.') : pc.green('Forge is ready.'), clackIO(promptIO));
+    finally {
+        const result = await versionCheckPromise;
+        if (result) {
+            const notice = formatVersionNotice(result);
+            if (notice)
+                console.log(notice);
+        }
     }
-    return 0;
 }
 function parseArgs(argv) {
-    const options = { command: argv[0], platform: 'all', scope: 'user', source: '.', dryRun: false, force: false, prune: true, yes: false, platformExplicit: false, scopeExplicit: false, sourceExplicit: false };
+    const options = { command: argv[0], platform: 'all', scope: 'user', source: '.', dryRun: false, force: false, prune: true, yes: false, noUpdateCheck: false, skipSpecUpdate: false, platformExplicit: false, scopeExplicit: false, sourceExplicit: false };
     for (let index = 1; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === '--dry-run')
@@ -144,6 +167,16 @@ function parseArgs(argv) {
             options.prune = false;
         else if (arg === '--yes' || arg === '-y')
             options.yes = true;
+        else if (arg === '--no-update-check')
+            options.noUpdateCheck = true;
+        else if (arg === '--skip-spec-update')
+            options.skipSpecUpdate = true;
+        else if (arg === '--to') {
+            const value = argv[++index];
+            if (!value)
+                return { error: 'Missing --to value' };
+            options.targetVersion = value;
+        }
         else if (arg === '--platform') {
             const value = argv[++index];
             const platform = value ? parsePlatform(value) : undefined;
@@ -176,6 +209,10 @@ function parseArgs(argv) {
         return { error: '--no-prune is only accepted for update' };
     if (command === 'validate' && (options.dryRun || options.force || options.yes || options.scopeExplicit))
         return { error: 'validate only accepts --platform and --source' };
+    if (command !== 'self-update' && (options.targetVersion !== undefined || options.skipSpecUpdate))
+        return { error: '--to and --skip-spec-update are only accepted for self-update' };
+    if (command === 'self-update' && (options.platformExplicit || options.scopeExplicit || options.sourceExplicit || options.force || options.yes))
+        return { error: 'self-update only accepts --to, --dry-run, --skip-spec-update' };
     return { options };
 }
 async function classifyPrune(oldManifest, files, backupRoot, scope, cwd, home) {
@@ -205,10 +242,11 @@ async function promptForMissingInstallOptions(options, promptIO) {
             message: 'Install Forge for which coding agent?',
             initialValue: 'all',
             options: [
-                { value: 'all', label: 'All supported agents', hint: 'OpenCode, Codex, and Claude Code' },
+                { value: 'all', label: 'All supported agents', hint: 'OpenCode, Codex, Claude Code, and Grok Build' },
                 { value: 'opencode', label: 'OpenCode' },
                 { value: 'codex', label: 'Codex' },
-                { value: 'claude', label: 'Claude Code' }
+                { value: 'claude', label: 'Claude Code' },
+                { value: 'grok', label: 'Grok Build' }
             ],
             ...io
         });
@@ -265,8 +303,23 @@ function normalizeCommand(command) {
         return 'update';
     if (command === 'validate')
         return 'validate';
+    if (command === 'self-update')
+        return 'self-update';
     return undefined;
 }
+function shouldCheckForUpdates(options, promptIO) {
+    if (options.noUpdateCheck)
+        return false;
+    const env = promptIO.env ?? process.env;
+    if (env.CI === 'true')
+        return false;
+    if (env.FORGE_NO_UPDATE_CHECK === '1' || env.FORGE_NO_UPDATE_CHECK === 'true')
+        return false;
+    // Skip in non-interactive runs (pipes, CI, scripts): the notice is a UX nudge for terminal users.
+    if (!isInteractivePrompt(promptIO))
+        return false;
+    return true;
+}
 function isInteractivePrompt(promptIO) {
     const env = promptIO.env ?? process.env;
     const interactive = promptIO.isInteractive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -291,9 +344,12 @@ function readPackageVersion() {
     }
 }
 function showUsage() {
-    console.log('Usage: forge-ai install [--platform opencode|claude|codex|all] [--scope user|project] [--source <dir>] [--dry-run] [--force] [--yes]');
-    console.log('       forge-ai update [--platform opencode|claude|codex|all] [--scope user|project] [--source <dir>] [--dry-run] [--no-prune] [--yes]');
-    console.log('       forge-ai validate [--platform opencode|claude|codex|all] [--source <dir>]');
+    console.log('Usage: forge-ai install [--platform opencode|claude|codex|grok|all] [--scope user|project] [--source <dir>] [--dry-run] [--force] [--yes]');
+    console.log('       forge-ai update [--platform opencode|claude|codex|grok|all] [--scope user|project] [--source <dir>] [--dry-run] [--no-prune] [--yes]');
+    console.log('       forge-ai validate [--platform opencode|claude|codex|grok|all] [--source <dir>]');
+    console.log('       forge-ai self-update [--to <version>] [--dry-run] [--skip-spec-update]');
+    console.log('');
+    console.log('Global flags: --no-update-check (also FORGE_NO_UPDATE_CHECK=1 or CI=true)');
 }
 function printPlan(command, sourceCount, files, diagnostics, prunePlan) {
     console.log(`${command}: ${sourceCount} source(s), ${files.length} output(s)`);

package/dist/src/model.js

@@ -1,4 +1,4 @@
-export const platforms = ['opencode', 'claude', 'codex'];
+export const platforms = ['opencode', 'claude', 'codex', 'grok'];
 export function isPlatform(value) {
     return platforms.includes(value);
 }

package/dist/src/paths.js

@@ -13,6 +13,8 @@ function userBase(platform, kind, home) {
         return path.join(home, '.config', 'opencode', kind === 'agent' ? 'agents' : 'skills');
     if (platform === 'claude')
         return path.join(home, '.claude', kind === 'agent' ? 'agents' : 'skills');
+    if (platform === 'grok')
+        return path.join(home, '.grok', kind === 'agent' ? 'agents' : 'skills');
     return kind === 'agent' ? path.join(home, '.codex', 'agents') : path.join(home, '.agents', 'skills');
 }
 function projectBase(platform, kind, cwd) {
@@ -20,5 +22,7 @@ function projectBase(platform, kind, cwd) {
         return path.join(cwd, '.opencode', kind === 'agent' ? 'agents' : 'skills');
     if (platform === 'claude')
         return path.join(cwd, '.claude', kind === 'agent' ? 'agents' : 'skills');
+    if (platform === 'grok')
+        return path.join(cwd, '.grok', kind === 'agent' ? 'agents' : 'skills');
     return kind === 'agent' ? path.join(cwd, '.codex', 'agents') : path.join(cwd, '.agents', 'skills');
 }

package/dist/src/processor.js

@@ -3,6 +3,7 @@ import { constants } from 'node:fs';
 import path from 'node:path';
 import { renderClaudeAgent, renderClaudeSkill } from './adapters/claude.js';
 import { renderCodexAgent, renderCodexSkill } from './adapters/codex.js';
+import { renderGrokAgent, renderGrokSkill } from './adapters/grok.js';
 import { renderOpenCodeAgent, renderOpenCodeSkill } from './adapters/opencode.js';
 import { diagnostic } from './diagnostics.js';
 import { discoverSources } from './discovery.js';
@@ -10,12 +11,15 @@ import { lookupEntryByPath, resolveBackupPath, sha256 } from './manifest.js';
 import { resolveOutputPath } from './paths.js';
 import { isPlatform, platforms } from './model.js';
 const namePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const platformKeys = new Set(['claude', 'opencode', 'codex']);
-const allowedTopLevel = new Set(['name', 'description', 'kind', 'claude', 'opencode', 'codex']);
+const platformKeys = new Set(['claude', 'opencode', 'codex', 'grok']);
+const allowedTopLevel = new Set(['name', 'description', 'kind', 'claude', 'opencode', 'codex', 'grok']);
 const allowedProductKeys = new Set(['permissions', 'model', 'kind']);
 const allowedOpenCodeKeys = new Set([...allowedProductKeys, 'mode']);
+const allowedClaudeKeys = new Set([...allowedProductKeys, 'when_to_use', 'user-invocable']);
 const openCodeModes = new Set(['primary', 'subagent', 'all']);
 const artifactKinds = new Set(['agent', 'skill']);
+const defaultBodyBudget = 200;
+const bodyLineBudgets = { forge: 90, 'using-forge': 240, 'forge-worker': 340, 'forge-worker-leaf': 280, 'forge-grill': 120, 'forge-adversary': 200 };
 export function resolvePlatforms(platform) {
     return platform === 'all' ? platforms : [platform];
 }
@@ -78,7 +82,7 @@ function convertSource(source, sourceRoot) {
         }
         const record = config;
         for (const key of Object.keys(record)) {
-            const allowedKeys = platform === 'opencode' ? allowedOpenCodeKeys : allowedProductKeys;
+            const allowedKeys = platform === 'opencode' ? allowedOpenCodeKeys : platform === 'claude' ? allowedClaudeKeys : allowedProductKeys;
             if (!allowedKeys.has(key))
                 diagnostics.push(diagnostic('error', 'UNSUPPORTED_PLATFORM_FIELD', `${platform}.${key} is not supported in the MVP`, { sourcePath: source.sourcePath, platform: platform }));
         }
@@ -88,6 +92,12 @@ function convertSource(source, sourceRoot) {
         if ('kind' in record && !artifactKinds.has(record.kind)) {
             diagnostics.push(diagnostic('error', 'INVALID_PLATFORM_KIND', `${platform}.kind must be one of agent, skill`, { sourcePath: source.sourcePath, platform: platform }));
         }
+        if (platform === 'claude' && 'when_to_use' in record && typeof record.when_to_use !== 'string') {
+            diagnostics.push(diagnostic('error', 'INVALID_CLAUDE_WHEN_TO_USE', 'claude.when_to_use must be a string', { sourcePath: source.sourcePath, platform: 'claude' }));
+        }
+        if (platform === 'claude' && 'user-invocable' in record && typeof record['user-invocable'] !== 'boolean') {
+            diagnostics.push(diagnostic('error', 'INVALID_CLAUDE_USER_INVOCABLE', 'claude.user-invocable must be a boolean', { sourcePath: source.sourcePath, platform: 'claude' }));
+        }
         if (platform === 'opencode' && 'mode' in record) {
             if (!openCodeModes.has(record.mode)) {
                 diagnostics.push(diagnostic('error', 'INVALID_OPENCODE_MODE', 'opencode.mode must be one of primary, subagent, all', { sourcePath: source.sourcePath, platform: 'opencode' }));
@@ -112,6 +122,10 @@ function convertSource(source, sourceRoot) {
         diagnostics.push(diagnostic('error', 'INVALID_KIND', 'artifact kind must be one of agent, skill', { sourcePath: source.sourcePath }));
     if (!source.body.trim())
         diagnostics.push(diagnostic('error', 'EMPTY_BODY', 'artifact body is required', { sourcePath: source.sourcePath }));
+    const bodyLines = source.body.split('\n').length;
+    const bodyBudget = bodyLineBudgets[name ?? source.expectedName] ?? defaultBodyBudget;
+    if (bodyLines > bodyBudget)
+        diagnostics.push(diagnostic('info', 'BODY_OVER_BUDGET', `artifact body is ${bodyLines} lines (soft budget ${bodyBudget}); keep always-loaded harness files small`, { sourcePath: source.sourcePath }));
     if (!name || !description || !artifactKinds.has(kind) || !source.body.trim() || diagnostics.some((item) => item.severity === 'error'))
         return { diagnostics };
     return {
@@ -124,17 +138,20 @@ function convertSource(source, sourceRoot) {
             sourcePath: path.relative(path.resolve(sourceRoot), source.sourcePath),
             claude: productConfig(data.claude),
             opencode: productConfig(data.opencode),
-            codex: productConfig(data.codex)
+            codex: productConfig(data.codex),
+            grok: productConfig(data.grok)
         }
     };
 }
 function productConfig(value) {
-    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
 }
 function renderFile(platform, kind, artifact, options, diagnostics) {
     const rendered = kind === 'agent'
-        ? platform === 'opencode' ? renderOpenCodeAgent(artifact) : platform === 'claude' ? renderClaudeAgent(artifact) : renderCodexAgent(artifact)
-        : platform === 'opencode' ? renderOpenCodeSkill(artifact) : platform === 'claude' ? renderClaudeSkill(artifact) : renderCodexSkill(artifact);
+        ? platform === 'opencode' ? renderOpenCodeAgent(artifact) : platform === 'claude' ? renderClaudeAgent(artifact) : platform === 'grok' ? renderGrokAgent(artifact) : renderCodexAgent(artifact)
+        : platform === 'opencode' ? renderOpenCodeSkill(artifact) : platform === 'claude' ? renderClaudeSkill(artifact) : platform === 'grok' ? renderGrokSkill(artifact) : renderCodexSkill(artifact);
     diagnostics.push(...rendered.diagnostics);
     return { platform, kind, scope: options.scope, name: artifact.name, sourcePath: artifact.sourcePath, path: resolveOutputPath(platform, kind, options.scope, artifact.name, options.cwd, options.home), content: rendered.content };
 }

package/dist/src/self-update.js

@@ -0,0 +1,70 @@
+import { realpathSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+const PACKAGE = '@guidobuilds/forge-ai';
+export function detectInstallMethod(realPath) {
+    if (/[/\\]\.npm[/\\]_npx[/\\]/.test(realPath))
+        return 'npx';
+    if (/[/\\]pnpm[/\\]/.test(realPath))
+        return 'pnpm-global';
+    if (/[/\\]homebrew[/\\]/i.test(realPath) && /[/\\]node_modules[/\\]/.test(realPath))
+        return 'npm-global-homebrew';
+    if (/[/\\]node_modules[/\\]/.test(realPath))
+        return 'npm-global';
+    return 'unknown';
+}
+export function buildUpdateCommand(method, version = 'latest') {
+    const target = `${PACKAGE}@${version}`;
+    switch (method) {
+        case 'pnpm-global':
+            return { command: 'pnpm', args: ['add', '-g', target, '--prefer-online'], description: 'pnpm global' };
+        case 'npm-global':
+            return { command: 'npm', args: ['install', '-g', target], description: 'npm global' };
+        case 'npm-global-homebrew':
+            return { command: '/opt/homebrew/bin/npm', args: ['install', '-g', target], description: 'npm global (Homebrew)' };
+        case 'npx':
+            return { command: '', args: [], description: 'npx (no global install)', instructions: `No global install to update. Re-run with: npx ${target} update` };
+        case 'unknown':
+            return { command: '', args: [], description: 'unknown install method', instructions: `Could not detect install method. Update manually: pnpm add -g ${target} --prefer-online` };
+    }
+}
+export async function runSelfUpdate(options) {
+    const log = options.log ?? ((message) => console.log(message));
+    const resolver = options.realPathResolver ?? ((p) => realpathSync(p));
+    const spawner = options.spawner ?? defaultSpawner;
+    let realPath;
+    try {
+        realPath = resolver(options.binaryPath);
+    }
+    catch {
+        realPath = options.binaryPath;
+    }
+    // Try the symlink path first (catches `pnpm link --global` and similar dev setups);
+    // fall back to the resolved real path (catches standard global installs whose bin dir is generic).
+    const symlinkMethod = detectInstallMethod(options.binaryPath);
+    const method = symlinkMethod !== 'unknown' ? symlinkMethod : detectInstallMethod(realPath);
+    const cmd = buildUpdateCommand(method, options.version ?? 'latest');
+    log(`Detected install: ${cmd.description} at ${realPath}`);
+    if (cmd.instructions) {
+        log(cmd.instructions);
+        return 1;
+    }
+    log(`Running: ${cmd.command} ${cmd.args.join(' ')}`);
+    if (options.dryRun) {
+        log('(dry-run, not executing)');
+        return 0;
+    }
+    const updateResult = spawner(cmd.command, cmd.args);
+    if (updateResult.status !== 0) {
+        log(`CLI update failed with exit code ${updateResult.status}`);
+        return updateResult.status ?? 1;
+    }
+    if (options.skipSpecUpdate)
+        return 0;
+    log('\nApplying spec kit with the updated CLI...');
+    const specResult = spawner('forge-ai', ['update']);
+    return specResult.status ?? 1;
+}
+function defaultSpawner(command, args) {
+    const result = spawnSync(command, args, { stdio: 'inherit' });
+    return { status: result.status };
+}

package/dist/src/version-check.js

@@ -0,0 +1,75 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const REGISTRY_URL = 'https://registry.npmjs.org/@guidobuilds/forge-ai/latest';
+const DEFAULT_TTL_MS = 60 * 60 * 1000;
+const DEFAULT_FETCH_TIMEOUT_MS = 1500;
+export async function checkLatestVersion(options) {
+    const ttl = options.ttlMs ?? DEFAULT_TTL_MS;
+    const now = options.now ?? new Date();
+    const cached = await readCache(options.cachePath);
+    if (cached && now.getTime() - new Date(cached.checkedAt).getTime() < ttl) {
+        return makeResult(options.current, cached.latest);
+    }
+    const fetched = await fetchLatest(options.registryUrl ?? REGISTRY_URL, options.fetcher ?? fetch, options.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS);
+    if (fetched === undefined)
+        return cached ? makeResult(options.current, cached.latest) : undefined;
+    await writeCache(options.cachePath, { checkedAt: now.toISOString(), latest: fetched });
+    return makeResult(options.current, fetched);
+}
+export function formatVersionNotice(result) {
+    if (!result.isOutdated)
+        return '';
+    return `forge-ai v${result.current} (v${result.latest} available — run \`forge-ai self-update\` to upgrade)`;
+}
+export function compareSemver(a, b) {
+    const pa = a.split('.').map((part) => parseInt(part, 10) || 0);
+    const pb = b.split('.').map((part) => parseInt(part, 10) || 0);
+    for (let index = 0; index < Math.max(pa.length, pb.length); index += 1) {
+        const diff = (pa[index] ?? 0) - (pb[index] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+function makeResult(current, latest) {
+    return { current, latest, isOutdated: compareSemver(current, latest) < 0 };
+}
+async function fetchLatest(url, fetcher, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetcher(url, { signal: controller.signal });
+        if (!response.ok)
+            return undefined;
+        const json = await response.json();
+        return typeof json.version === 'string' ? json.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function readCache(cachePath) {
+    try {
+        const content = await readFile(cachePath, 'utf8');
+        const parsed = JSON.parse(content);
+        if (typeof parsed.checkedAt === 'string' && typeof parsed.latest === 'string') {
+            return { checkedAt: parsed.checkedAt, latest: parsed.latest };
+        }
+    }
+    catch {
+        // Cache missing or malformed; treat as no cache.
+    }
+    return undefined;
+}
+async function writeCache(cachePath, data) {
+    try {
+        await mkdir(path.dirname(cachePath), { recursive: true });
+        await writeFile(cachePath, `${JSON.stringify(data)}\n`, 'utf8');
+    }
+    catch {
+        // Cache write failures are non-fatal.
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidobuilds/forge-ai",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "Forge AI framework",
   "license": "MIT",
   "type": "module",