ai-runtime-engine 1.1.0

package/dist/cli/commands/info.js

@@ -0,0 +1,53 @@
+/**
+ * `ai-runtime info` — a read-only summary of the runtime: workspace, default mode, context budget,
+ * providers/models, skills, tools, memory + learning stats, and storage paths. Makes NO live calls and
+ * mutates nothing. `--json` prints the structured report.
+ */
+import { Runtime } from '../../runtime/runtime.js';
+import { resolveContextBudget } from '../../context/budget.js';
+import { summarizeWorkspace } from '../../runtime/workspace/workspace.js';
+import { print } from '../render.js';
+/** Gather the read-only info report from a loaded runtime. Pure aside from reading the local store. */
+export async function gatherInfo(rt) {
+    const ws = rt.workspaceInfo();
+    const settings = rt.settings();
+    const env = process.env;
+    const budget = resolveContextBudget({
+        ...(settings.context?.maxTokens !== undefined ? { config: settings.context.maxTokens } : {}),
+        ...(env.AI_CONTEXT_MAX_TOKENS !== undefined ? { env: env.AI_CONTEXT_MAX_TOKENS } : {}),
+    });
+    const providers = rt.ai.providers();
+    const models = await rt.ai.discover().then((m) => m.reduce((n, p) => n + p.models.length, 0)).catch(() => 0);
+    const facts = rt.memory.enabled ? rt.memory.all().filter((r) => !r.supersededBy).length : 0;
+    const learningSnap = rt.learning.enabled ? rt.learning.snapshot() : [];
+    const paths = rt.store.paths();
+    return {
+        ...(ws ? { workspace: { name: ws.name ?? ws.root.split(/[\\/]/).pop() ?? 'workspace', summary: summarizeWorkspace(ws), ...(ws.git.branch ? { branch: ws.git.branch } : {}) } } : {}),
+        defaultMode: settings.defaultMode ?? 'auto',
+        contextBudgetTokens: budget,
+        providers: { total: providers.length, enabled: providers.filter((p) => p.enabled).length },
+        models,
+        skills: rt.skills().map((s) => `${s.id}@${s.version}`),
+        tools: rt.tools().map((t) => t.id),
+        memory: { enabled: rt.memory.enabled, facts },
+        learning: { enabled: rt.learning.enabled, entries: learningSnap.length, preferredProviders: rt.learning.enabled ? rt.learning.preferredProviders() : [] },
+        storage: { home: paths.home, project: paths.project, enabled: rt.store.enabled },
+    };
+}
+export function renderInfo(r) {
+    const lines = ['ai-runtime info', ''];
+    if (r.workspace)
+        lines.push(`workspace:   ${r.workspace.name}${r.workspace.branch ? ` @ ${r.workspace.branch}` : ''}`, `             ${r.workspace.summary}`);
+    else
+        lines.push('workspace:   (none detected)');
+    lines.push(`mode:        ${r.defaultMode}`, `context:     ${r.contextBudgetTokens} token budget`, `providers:   ${r.providers.total} configured (${r.providers.enabled} enabled), ${r.models} models`, `skills:      ${r.skills.length ? r.skills.join(', ') : '(none — register tools to enable)'}`, `tools:       ${r.tools.join(', ')}`, `memory:      ${r.memory.enabled ? `${r.memory.facts} fact(s)` : 'disabled'}`, `learning:    ${r.learning.enabled ? `${r.learning.entries} record(s)${r.learning.preferredProviders.length ? `, prefers ${r.learning.preferredProviders.join(', ')}` : ''}` : 'disabled'}`, `storage:     ${r.storage.enabled ? r.storage.project : 'disabled (stateless)'}`);
+    return lines;
+}
+export async function infoCommand(opts) {
+    const rt = await Runtime.load({ ...(opts.config ? { config: opts.config } : {}) });
+    const report = await gatherInfo(rt);
+    if (opts.json)
+        return print(JSON.stringify(report, null, 2));
+    for (const line of renderInfo(report))
+        print(line);
+}

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `ai-runtime init` — scaffold a config, an env template, and gitignore entries. Never writes secrets;
+ * the config carries only env-var NAMES, and `.env` is added to .gitignore.
+ */
+export declare function initCommand(): void;

package/dist/cli/commands/init.js

@@ -0,0 +1,75 @@
+/**
+ * `ai-runtime init` — scaffold a config, an env template, and gitignore entries. Never writes secrets;
+ * the config carries only env-var NAMES, and `.env` is added to .gitignore.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { print } from '../render.js';
+const EXAMPLE_YAML = `# ai-runtime configuration. Secret VALUES live in .env (gitignored); this file names env vars only.
+strategy: best
+
+providers:
+  - id: gemini
+    kind: gemini
+    apiKeyEnv: GEMINI_API_KEY
+
+  - id: groq
+    kind: groq
+    apiKeyEnv: GROQ_API_KEY
+
+  - id: anthropic
+    kind: anthropic
+    apiKeyEnv: ANTHROPIC_API_KEY
+
+  # Local — no key required. Remove if you do not run Ollama.
+  - id: ollama
+    kind: ollama
+
+# Example of an unknown OpenAI-compatible provider that self-declares its capabilities:
+# - id: internal
+#   kind: openai-compatible
+#   baseUrl: https://ai.internal.example/v1
+#   apiKeyEnv: INTERNAL_AI_API_KEY
+#   models: [internal-large]
+#   capabilities:
+#     intelligence: [reasoning, code_generation]
+#     output: [text, code, json]
+#     contextWindow: 128000
+`;
+const EXAMPLE_ENV = `# Fill in the values you have. Leave the rest blank — the router adapts to whatever is configured.
+GEMINI_API_KEY=
+GROQ_API_KEY=
+ANTHROPIC_API_KEY=
+`;
+const GITIGNORE_ENTRIES = ['.env', '.env.*', '!.env.example', '.ai-runtime/'];
+function writeIfAbsent(file, contents) {
+    const full = resolve(process.cwd(), file);
+    if (existsSync(full)) {
+        print(`  • ${file} already exists — left unchanged`);
+        return;
+    }
+    writeFileSync(full, contents);
+    print(`  ✓ wrote ${file}`);
+}
+function ensureGitignore() {
+    const full = resolve(process.cwd(), '.gitignore');
+    const existing = existsSync(full) ? readFileSync(full, 'utf8') : '';
+    const missing = GITIGNORE_ENTRIES.filter((e) => !existing.split('\n').includes(e));
+    if (missing.length === 0) {
+        print('  • .gitignore already covers secrets');
+        return;
+    }
+    const block = `${existing && !existing.endsWith('\n') ? '\n' : ''}\n# ai-runtime secrets\n${missing.join('\n')}\n`;
+    writeFileSync(full, existing + block);
+    print(`  ✓ added ${missing.length} entr${missing.length === 1 ? 'y' : 'ies'} to .gitignore`);
+}
+export function initCommand() {
+    print('Initializing ai-runtime...');
+    writeIfAbsent('ai-runtime.yaml', EXAMPLE_YAML);
+    writeIfAbsent('.env.example', EXAMPLE_ENV);
+    ensureGitignore();
+    print('\nNext steps:');
+    print('  1. Copy .env.example to .env and fill in the keys you have');
+    print('  2. Run `ai-runtime doctor` to verify configuration');
+    print('  3. Run `ai-runtime route <task>` to route a task');
+}

package/dist/cli/commands/inspect.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `ai-runtime providers` / `models` / `capabilities` — read-only inspection of the configured fleet.
+ * All go through the key-free facade views and redacted output.
+ */
+export declare function providersCommand(opts: {
+    config?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function modelsCommand(opts: {
+    config?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function capabilitiesCommand(opts: {
+    config?: string;
+    json?: boolean;
+}): Promise<void>;

package/dist/cli/commands/inspect.js

@@ -0,0 +1,60 @@
+/**
+ * `ai-runtime providers` / `models` / `capabilities` — read-only inspection of the configured fleet.
+ * All go through the key-free facade views and redacted output.
+ */
+import { loadAI } from '../context.js';
+import { print } from '../render.js';
+export async function providersCommand(opts) {
+    const { ai, hasProviders } = loadAI(opts.config);
+    if (!hasProviders)
+        return print('No providers configured.');
+    const health = await ai.checkHealth();
+    const healthById = new Map(health.map((h) => [h.providerId, h]));
+    const list = ai.providers();
+    if (opts.json)
+        return print(JSON.stringify(list, null, 2));
+    print('Providers:');
+    for (const p of list) {
+        const h = healthById.get(p.id);
+        print(`  ${p.enabled ? '●' : '○'} ${p.id.padEnd(14)} ${p.kind.padEnd(18)} ${p.privacyClass.padEnd(6)} ${h?.state ?? 'UNKNOWN'}`);
+    }
+}
+export async function modelsCommand(opts) {
+    const { ai, hasProviders } = loadAI(opts.config);
+    if (!hasProviders)
+        return print('No providers configured.');
+    const metas = await ai.discover();
+    if (opts.json)
+        return print(JSON.stringify(metas.flatMap((m) => m.models), null, 2));
+    print('Models:');
+    for (const meta of metas) {
+        for (const model of meta.models) {
+            const ctx = model.contextWindow ? `${Math.round(model.contextWindow / 1000)}k` : '?';
+            const tier = model.quality?.tier ?? '—';
+            print(`  ${meta.id.padEnd(12)} ${model.id.padEnd(24)} ctx=${ctx.padEnd(6)} quality=${tier.padEnd(9)} source=${model.source}`);
+        }
+    }
+}
+const GROUPS = ['input', 'output', 'intelligence', 'agent'];
+export async function capabilitiesCommand(opts) {
+    const { ai, hasProviders } = loadAI(opts.config);
+    if (!hasProviders)
+        return print('No providers configured.');
+    const metas = await ai.discover();
+    if (opts.json)
+        return print(JSON.stringify(metas.flatMap((m) => m.models.map((mo) => ({ provider: m.id, model: mo.id, capabilities: mo.capabilities }))), null, 2));
+    print('Capabilities (supported keys, by model):');
+    for (const meta of metas) {
+        for (const model of meta.models) {
+            print(`\n  ${meta.id}/${model.id}`);
+            for (const group of GROUPS) {
+                const bucket = model.capabilities[group];
+                const keys = Object.entries(bucket).filter(([, cap]) => cap.value).map(([k, cap]) => `${k}(${cap.evidence[0]})`);
+                if (keys.length)
+                    print(`    ${group.padEnd(13)} ${keys.join(', ')}`);
+            }
+            const ctx = model.capabilities.context.contextWindow;
+            print(`    context       ${ctx.value} (${ctx.evidence})`);
+        }
+    }
+}

package/dist/cli/commands/phase2.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Phase-2 CLI commands: probe (verify capabilities), discover (analyze an OpenAPI spec),
+ * benchmark (compare providers on representative tasks), telemetry (recent routing events).
+ */
+export declare function probeCommand(providerId: string, model: string, opts: {
+    config?: string;
+}): Promise<void>;
+export declare function discoverCommand(specFile: string, opts: {
+    json?: boolean;
+}): void;
+export declare function benchmarkCommand(opts: {
+    config?: string;
+    samples?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function telemetryCommand(opts: {
+    config?: string;
+    limit?: string;
+}): void;
+export declare function presetsCommand(opts: {
+    json?: boolean;
+}): void;

package/dist/cli/commands/phase2.js

@@ -0,0 +1,83 @@
+/**
+ * Phase-2 CLI commands: probe (verify capabilities), discover (analyze an OpenAPI spec),
+ * benchmark (compare providers on representative tasks), telemetry (recent routing events).
+ */
+import { loadAI } from '../context.js';
+import { print, printError } from '../render.js';
+import { analyzeOpenApiFile } from '../../discovery/openapi.js';
+import { benchmark } from '../../benchmark/benchmark.js';
+import { listPresets } from '../../marketplace/presets.js';
+export async function probeCommand(providerId, model, opts) {
+    const { ai, hasProviders } = loadAI(opts.config);
+    if (!hasProviders)
+        return print('No providers configured.');
+    print(`Probing ${providerId}/${model} (live calls)...`);
+    try {
+        const report = await ai.probe(providerId, model);
+        for (const r of report.results)
+            print(`  ${r.status === 'verified' ? '✓' : '·'} ${r.probe.padEnd(18)} ${r.status}${r.detail ? ` (${r.detail})` : ''}`);
+        const verified = report.results.filter((r) => r.status === 'verified').length;
+        print(`\n${verified}/${report.results.length} capabilities verified and applied to the routing overlay.`);
+    }
+    catch (e) {
+        printError(`probe failed: ${e instanceof Error ? e.message : String(e)}`);
+        process.exitCode = 1;
+    }
+}
+export function discoverCommand(specFile, opts) {
+    const analysis = analyzeOpenApiFile(specFile);
+    if (opts.json)
+        return print(JSON.stringify(analysis, null, 2));
+    print(`OpenAPI analysis: ${analysis.title ?? specFile}${analysis.version ? ` v${analysis.version}` : ''}`);
+    print(`  baseUrl:    ${analysis.baseUrl ?? '(not found)'}`);
+    print(`  auth:       ${analysis.authMode}${analysis.authHeaderName ? ` (${analysis.authHeaderName})` : ''}`);
+    print(`  wireShape:  ${analysis.wireShape}`);
+    print(`  chat:       ${analysis.chatEndpoint ?? '(none detected)'}`);
+    print(`  endpoints:  ${analysis.endpoints.length}`);
+    if (analysis.suggestedProviderConfig) {
+        print('\nSuggested provider config (review before use):');
+        print(JSON.stringify(analysis.suggestedProviderConfig, null, 2).split('\n').map((l) => `  ${l}`).join('\n'));
+    }
+    print('\nNotes:');
+    for (const n of analysis.notes)
+        print(`  - ${n}`);
+}
+const DEFAULT_BENCH_TASKS = [
+    { task: 'generate-playwright-tests', input: 'A login form with email, password, and remember-me.' },
+    { task: 'jira-to-test', input: 'As a user I can reset my password via an emailed link.' },
+];
+export async function benchmarkCommand(opts) {
+    const { ai, hasProviders } = loadAI(opts.config);
+    if (!hasProviders)
+        return print('No providers configured.');
+    const samples = opts.samples ? Number(opts.samples) : 3;
+    print(`Benchmarking ${DEFAULT_BENCH_TASKS.length} tasks × ${samples} samples per provider...\n`);
+    const results = await benchmark(ai, DEFAULT_BENCH_TASKS, { samples });
+    if (opts.json)
+        return print(JSON.stringify(results, null, 2));
+    print(`${'Provider'.padEnd(16)}${'Success'.padEnd(10)}${'AvgLatency'.padEnd(12)}Runs`);
+    for (const r of results) {
+        print(`${r.providerId.padEnd(16)}${`${Math.round(r.successRate * 100)}%`.padEnd(10)}${`${Math.round(r.avgLatencyMs)}ms`.padEnd(12)}${r.runs}`);
+    }
+}
+export function telemetryCommand(opts) {
+    const { ai } = loadAI(opts.config);
+    const events = ai.telemetryEvents();
+    const limit = opts.limit ? Number(opts.limit) : 20;
+    const recent = events.slice(-limit);
+    if (recent.length === 0)
+        return print('No telemetry recorded in this session.');
+    for (const e of recent)
+        print(JSON.stringify(e));
+}
+export function presetsCommand(opts) {
+    const presets = listPresets();
+    if (opts.json)
+        return print(JSON.stringify(presets, null, 2));
+    print('Provider marketplace presets:');
+    for (const p of presets) {
+        print(`  ${p.id.padEnd(14)} ${p.kind.padEnd(18)} ${p.apiKeyEnv ?? '(no key)'}`);
+        print(`  ${''.padEnd(14)} ${p.description}`);
+    }
+    print('\nAdd one in config with `kind` + `apiKeyEnv`, or programmatically via `ai.addPreset(id)`.');
+}

package/dist/cli/commands/route.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `ai-runtime route <task>` — run a task through the router and print the decision + result.
+ * Routes over the providers built from config; when none are configured it falls back to the offline
+ * demo providers (no keys). All output passes through redact().
+ */
+export interface RouteOptions {
+    input?: string;
+    strategy?: string;
+    provider?: string;
+    model?: string;
+    json?: boolean;
+    config?: string;
+}
+export declare function routeCommand(task: string, options: RouteOptions): Promise<void>;

package/dist/cli/commands/route.js

@@ -0,0 +1,49 @@
+/**
+ * `ai-runtime route <task>` — run a task through the router and print the decision + result.
+ * Routes over the providers built from config; when none are configured it falls back to the offline
+ * demo providers (no keys). All output passes through redact().
+ */
+import { buildDemoAI } from '../../providers/mock/demo.js';
+import { loadAI } from '../context.js';
+import { print } from '../render.js';
+export async function routeCommand(task, options) {
+    const loaded = loadAI(options.config);
+    const ai = loaded.hasProviders ? loaded.ai : buildDemoAI();
+    if (!loaded.hasProviders)
+        print('(no providers configured — routing against offline demo providers)\n');
+    const request = { task, input: options.input ?? `demo input for ${task}` };
+    if (options.strategy)
+        request.strategy = options.strategy;
+    if (options.provider)
+        request.provider = options.provider;
+    if (options.model)
+        request.model = options.model;
+    const result = await ai.run(request);
+    if (options.json) {
+        print(JSON.stringify(result, null, 2));
+        return;
+    }
+    print(`Task: ${task}`);
+    print(`Result: ${result.ok ? 'OK' : 'FAILED'}   confidence: ${result.confidence.toFixed(2)}`);
+    if (result.routing.selected)
+        print(`Selected: ${result.routing.selected.providerId}/${result.routing.selected.model}`);
+    print('\nRanked candidates:');
+    for (const r of result.routing.ranked)
+        print(`  ${r.score.toFixed(3)}  ${r.providerId}/${r.model}`);
+    if (result.routing.filteredOut.length) {
+        print('\nExcluded:');
+        for (const f of result.routing.filteredOut)
+            print(`  ${f.providerId}/${f.model}: ${f.reason}`);
+    }
+    if (result.routing.attempts.length) {
+        print('\nAttempts:');
+        for (const a of result.routing.attempts)
+            print(`  ${a.providerId}/${a.model}: ${a.outcome}${a.category ? ` (${a.category})` : ''} ${a.latencyMs}ms`);
+    }
+    if (!result.ok && result.error)
+        print(`\nError [${result.error.category}]: ${result.error.message}`);
+    else if (result.response?.text)
+        print(`\nResponse: ${result.response.text}`);
+    else if (result.response?.json)
+        print(`\nResponse (json): ${JSON.stringify(result.response.json)}`);
+}

package/dist/cli/commands/run.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `ai-runtime run "<input>"` — one-shot Runtime invocation for CI/scripts. Shares the exact Runtime
+ * the interactive REPL uses. Prints the response (or a structured result with --json).
+ */
+export interface RunOptions {
+    mode?: string;
+    config?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}
+export declare function runCommand(input: string, options: RunOptions): Promise<void>;

package/dist/cli/commands/run.js

@@ -0,0 +1,37 @@
+/**
+ * `ai-runtime run "<input>"` — one-shot Runtime invocation for CI/scripts. Shares the exact Runtime
+ * the interactive REPL uses. Prints the response (or a structured result with --json).
+ */
+import { Runtime } from '../../runtime/runtime.js';
+import { print } from '../render.js';
+import { RUNTIME_MODES } from '../../runtime/types.js';
+export async function runCommand(input, options) {
+    const rt = await Runtime.load({ ...(options.config ? { config: options.config } : {}) });
+    const req = { input };
+    if (options.dryRun)
+        req.dryRun = true;
+    if (options.mode) {
+        if (!RUNTIME_MODES.includes(options.mode)) {
+            print(`invalid mode '${options.mode}'. valid: ${RUNTIME_MODES.join(', ')}`);
+            process.exitCode = 1;
+            return;
+        }
+        req.mode = options.mode;
+    }
+    const result = await rt.run(req);
+    if (options.json)
+        return print(JSON.stringify(result, null, 2));
+    if (result.response?.text)
+        print(result.response.text);
+    else if (result.response?.json !== undefined)
+        print(JSON.stringify(result.response.json, null, 2));
+    if (result.mode.executed !== result.mode.selected)
+        print(`(mode: ${result.mode.selected} → ${result.mode.executed})`);
+    if (result.clarification)
+        print(`? ${result.clarification.question}`);
+    if (result.error)
+        print(`[${result.error.category}] ${result.error.message}`);
+    // Any un-ok result (a router error OR a failed plan/execute/orchestrate) is a non-zero exit for CI.
+    if (!result.ok)
+        process.exitCode = 1;
+}

package/dist/cli/commands/setup.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `ai-runtime setup` — guided bootstrap. Detects the workspace and which provider keys are already in the
+ * environment, then generates `.ai-runtime/config.yaml`, a commented `.env.example`, and .gitignore
+ * entries — ASKING before every disk mutation. It never installs anything, never creates accounts, and
+ * never writes a secret VALUE (config names env vars only). With no keys present it prints onboarding
+ * recommendations instead. The detection half is pure and unit-tested; the command half drives it with
+ * confirmations.
+ */
+export interface Candidate {
+    id: string;
+    kind: string;
+    apiKeyEnv?: string;
+    local?: boolean;
+    link: string;
+}
+/** The providers setup recommends. Cloud ones need a key (env-var name only); Ollama is local/no-key. */
+export declare const SETUP_CANDIDATES: Candidate[];
+export interface SetupDetection {
+    workspaceSummary: string;
+    configFile?: string;
+    /** Providers usable now: a cloud provider whose key is set, plus local ones. */
+    ready: Candidate[];
+    /** Cloud providers whose key is absent (shown as onboarding recommendations). */
+    missing: Candidate[];
+}
+/** Detect what setup would configure. Pure: reads the filesystem + env, writes nothing. */
+export declare function detectSetup(cwd: string, env: NodeJS.ProcessEnv): SetupDetection;
+/** Generate `.ai-runtime/config.yaml` naming only the ready providers (env-var names, never values). */
+export declare function generateConfigYaml(ready: Candidate[]): string;
+/** Generate a commented `.env.example` for the recommended cloud providers. */
+export declare function generateEnvExample(): string;
+export declare function setupCommand(opts?: {
+    yes?: boolean;
+}): Promise<void>;

package/dist/cli/commands/setup.js

@@ -0,0 +1,104 @@
+/**
+ * `ai-runtime setup` — guided bootstrap. Detects the workspace and which provider keys are already in the
+ * environment, then generates `.ai-runtime/config.yaml`, a commented `.env.example`, and .gitignore
+ * entries — ASKING before every disk mutation. It never installs anything, never creates accounts, and
+ * never writes a secret VALUE (config names env vars only). With no keys present it prints onboarding
+ * recommendations instead. The detection half is pure and unit-tested; the command half drives it with
+ * confirmations.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { detectWorkspace, summarizeWorkspace } from '../../runtime/workspace/workspace.js';
+import { findRuntimeConfigFile } from '../../runtime/config.js';
+import { findConfigFile } from '../../config/load.js';
+import { confirm } from '../prompt.js';
+import { print } from '../render.js';
+/** The providers setup recommends. Cloud ones need a key (env-var name only); Ollama is local/no-key. */
+export const SETUP_CANDIDATES = [
+    { id: 'gemini', kind: 'gemini', apiKeyEnv: 'GEMINI_API_KEY', link: 'https://aistudio.google.com/apikey' },
+    { id: 'groq', kind: 'groq', apiKeyEnv: 'GROQ_API_KEY', link: 'https://console.groq.com/keys' },
+    { id: 'anthropic', kind: 'anthropic', apiKeyEnv: 'ANTHROPIC_API_KEY', link: 'https://console.anthropic.com/settings/keys' },
+    { id: 'openrouter', kind: 'openrouter', apiKeyEnv: 'OPENROUTER_API_KEY', link: 'https://openrouter.ai/keys' },
+    { id: 'ollama', kind: 'ollama', local: true, link: 'https://ollama.com' },
+];
+/** Detect what setup would configure. Pure: reads the filesystem + env, writes nothing. */
+export function detectSetup(cwd, env) {
+    const ws = detectWorkspace(cwd);
+    const configFile = findRuntimeConfigFile(cwd) ?? findConfigFile(cwd);
+    const ready = SETUP_CANDIDATES.filter((c) => c.local || (c.apiKeyEnv && (env[c.apiKeyEnv] ?? '') !== ''));
+    const missing = SETUP_CANDIDATES.filter((c) => c.apiKeyEnv && (env[c.apiKeyEnv] ?? '') === '');
+    return { workspaceSummary: ws ? summarizeWorkspace(ws) : '(no workspace traits detected)', ...(configFile ? { configFile } : {}), ready, missing };
+}
+/** Generate `.ai-runtime/config.yaml` naming only the ready providers (env-var names, never values). */
+export function generateConfigYaml(ready) {
+    const blocks = ready.map((c) => (c.local ? `  - id: ${c.id}\n    kind: ${c.kind}` : `  - id: ${c.id}\n    kind: ${c.kind}\n    apiKeyEnv: ${c.apiKeyEnv}`));
+    const body = blocks.length ? blocks.join('\n\n') : '  # No providers detected yet. Add one, e.g.:\n  # - id: gemini\n  #   kind: gemini\n  #   apiKeyEnv: GEMINI_API_KEY';
+    return `# ai-runtime configuration. Secret VALUES live in .env (gitignored); this file names env vars only.\nruntime:\n  defaultMode: auto\n\nproviders:\n${body}\n`;
+}
+/** Generate a commented `.env.example` for the recommended cloud providers. */
+export function generateEnvExample() {
+    const lines = ['# Fill in the keys you have; leave the rest blank. The runtime adapts to whatever is configured.'];
+    for (const c of SETUP_CANDIDATES)
+        if (c.apiKeyEnv)
+            lines.push(`${c.apiKeyEnv}=`);
+    return lines.join('\n') + '\n';
+}
+const GITIGNORE_ENTRIES = ['.env', '.env.*', '!.env.example', '.ai-runtime/'];
+function missingGitignore(cwd) {
+    const full = resolve(cwd, '.gitignore');
+    const existing = existsSync(full) ? readFileSync(full, 'utf8').split('\n') : [];
+    return GITIGNORE_ENTRIES.filter((e) => !existing.includes(e));
+}
+function renderOnboarding(missing) {
+    const lines = ['', 'To add a provider, get a key and set its env var (or install Ollama for a local, no-key option):'];
+    for (const c of missing)
+        lines.push(`  • ${c.id.padEnd(11)} ${c.apiKeyEnv ? `${c.apiKeyEnv}  →  ` : ''}${c.link}`);
+    lines.push(`  • ollama      local, no key       →  https://ollama.com`);
+    return lines;
+}
+export async function setupCommand(opts = {}) {
+    const cwd = process.cwd();
+    const env = process.env;
+    const det = detectSetup(cwd, env);
+    print('ai-runtime setup\n');
+    print(`workspace: ${det.workspaceSummary}`);
+    print(det.ready.length ? `ready:     ${det.ready.map((c) => c.id).join(', ')}` : 'ready:     (no providers configured yet)');
+    const ask = async (q) => opts.yes || (await confirm(q));
+    // 1) config file
+    const configTarget = join(cwd, '.ai-runtime', 'config.yaml');
+    if (existsSync(configTarget))
+        print(`\n• ${configTarget} exists — left unchanged`);
+    else if (await ask(`\nWrite ${configTarget}?`)) {
+        mkdirSync(join(cwd, '.ai-runtime'), { recursive: true });
+        writeFileSync(configTarget, generateConfigYaml(det.ready));
+        print(`  ✓ wrote .ai-runtime/config.yaml`);
+    }
+    else
+        print('  • skipped config');
+    // 2) .env.example
+    const envTarget = join(cwd, '.env.example');
+    if (existsSync(envTarget))
+        print(`• ${envTarget} exists — left unchanged`);
+    else if (await ask(`Write ${envTarget}?`)) {
+        writeFileSync(envTarget, generateEnvExample());
+        print('  ✓ wrote .env.example');
+    }
+    else
+        print('  • skipped .env.example');
+    // 3) .gitignore
+    const missing = missingGitignore(cwd);
+    if (!missing.length)
+        print('• .gitignore already covers secrets + local state');
+    else if (await ask(`Add ${missing.length} entr${missing.length === 1 ? 'y' : 'ies'} to .gitignore?`)) {
+        const full = resolve(cwd, '.gitignore');
+        const existing = existsSync(full) ? readFileSync(full, 'utf8') : '';
+        writeFileSync(full, existing + `${existing && !existing.endsWith('\n') ? '\n' : ''}\n# ai-runtime\n${missing.join('\n')}\n`);
+        print(`  ✓ updated .gitignore`);
+    }
+    else
+        print('  • skipped .gitignore');
+    if (det.missing.length)
+        for (const line of renderOnboarding(det.missing))
+            print(line);
+    print('\nNext: copy .env.example to .env, fill in a key, then run `ai-runtime doctor`.');
+}

package/dist/cli/commands/skills.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `ai-runtime skills` — list the skills the runtime has (built-in + auto-loaded from `.ai-runtime/skills/`
+ * and configured paths). `--discover` scans the rest of the workspace for skill-looking files and REPORTS
+ * them without loading — the user enables one by moving it into `.ai-runtime/skills/` or adding its path to
+ * `skills.paths` in config (loading a module runs its code, so it is never implicit).
+ */
+import { Runtime } from '../../runtime/runtime.js';
+export interface SkillsReport {
+    loaded: Array<{
+        id: string;
+        version: string;
+        source?: string;
+    }>;
+    sourceErrors: Array<{
+        path: string;
+        detail: string;
+    }>;
+    candidates: Array<{
+        relative: string;
+        kind: string;
+    }>;
+}
+export declare function gatherSkills(rt: Runtime, discover: boolean): Promise<SkillsReport>;
+export declare function skillsCommand(opts: {
+    config?: string;
+    discover?: boolean;
+    json?: boolean;
+}): Promise<void>;

package/dist/cli/commands/skills.js

@@ -0,0 +1,48 @@
+/**
+ * `ai-runtime skills` — list the skills the runtime has (built-in + auto-loaded from `.ai-runtime/skills/`
+ * and configured paths). `--discover` scans the rest of the workspace for skill-looking files and REPORTS
+ * them without loading — the user enables one by moving it into `.ai-runtime/skills/` or adding its path to
+ * `skills.paths` in config (loading a module runs its code, so it is never implicit).
+ */
+import { Runtime } from '../../runtime/runtime.js';
+import { print } from '../render.js';
+export async function gatherSkills(rt, discover) {
+    const sources = rt.skillSources();
+    const sourceById = new Map();
+    for (const s of sources)
+        for (const sk of s.skills)
+            sourceById.set(sk.id, s.source.relative);
+    return {
+        loaded: rt.skills().map((s) => ({ id: s.id, version: s.version, ...(sourceById.get(s.id) ? { source: sourceById.get(s.id) } : {}) })),
+        sourceErrors: sources.filter((s) => s.status === 'error').map((s) => ({ path: s.source.relative, detail: s.detail ?? 'unknown error' })),
+        candidates: discover ? rt.discoverSkillCandidates().map((c) => ({ relative: c.relative, kind: c.kind })) : [],
+    };
+}
+function renderSkills(r, discover) {
+    const lines = ['Skills:'];
+    if (!r.loaded.length)
+        lines.push('  (none available — a skill needs its tools registered)');
+    for (const s of r.loaded)
+        lines.push(`  ${s.id.padEnd(20)} v${s.version}${s.source ? `  (from ${s.source})` : '  (built-in)'}`);
+    if (r.sourceErrors.length) {
+        lines.push('', 'Skipped (could not load):');
+        for (const e of r.sourceErrors)
+            lines.push(`  ✗ ${e.path} — ${e.detail}`);
+    }
+    if (discover) {
+        lines.push('', r.candidates.length ? `Discovered ${r.candidates.length} candidate(s) elsewhere in the workspace (not loaded):` : 'No other skill files found in the workspace.');
+        for (const c of r.candidates)
+            lines.push(`  • ${c.relative}  [${c.kind}]`);
+        if (r.candidates.length)
+            lines.push('', 'To enable one: move it into .ai-runtime/skills/, or add its path to `skills.paths` in .ai-runtime/config.yaml.');
+    }
+    return lines;
+}
+export async function skillsCommand(opts) {
+    const rt = await Runtime.load({ ...(opts.config ? { config: opts.config } : {}) });
+    const report = await gatherSkills(rt, !!opts.discover);
+    if (opts.json)
+        return print(JSON.stringify(report, null, 2));
+    for (const line of renderSkills(report, !!opts.discover))
+        print(line);
+}