@aiwg/cli 2026.7.18 → 2026.7.20

package/dist/src/artifacts/cli.js

@@ -134,7 +134,7 @@ function parseAiwgVersionFlag(args) {
         return undefined;
     const value = args[indices[0] + 1];
     if (!value || value.startsWith('--')) {
-        console.error('Error: --aiwg-version requires an exact calendar-semver version or channel name');
+        console.error('Error: --aiwg-version requires an exact calendar-semver version, SemVer range, sha256 digest, or channel name');
         process.exit(1);
     }
     try {
@@ -257,6 +257,9 @@ export async function main(args) {
         case 'dedup-report':
             await handleDedup(subcommandArgs);
             break;
+        case 'eval-discovery':
+            await handleEvalDiscovery(subcommandArgs);
+            break;
         case 'watch':
             await handleWatch(subcommandArgs);
             break;
@@ -283,7 +286,7 @@ export async function main(args) {
             break;
         default:
             console.error(`Error: Unknown index subcommand '${subcommand}'`);
-            console.log('Available: build, query, discover, show, export, sync, migrate-legacy, deps, stats, status, list, neighbors, set, embed, similar, dedup-report, watch');
+            console.log('Available: build, query, discover, show, export, sync, migrate-legacy, deps, stats, status, list, neighbors, set, embed, similar, dedup-report, eval-discovery, watch');
             process.exit(1);
     }
 }
@@ -306,6 +309,7 @@ function printIndexUsage() {
     console.log('  embed      Build the semantic embedding index for a graph (opt-in deps)');
     console.log('  similar    Semantic neighbors of a node (requires embed)');
     console.log('  dedup-report  Near-duplicate node pairs above a similarity threshold');
+    console.log('  eval-discovery  Benchmark operational capability discovery relevance');
     console.log('  watch      Start a filesystem watcher for automatic incremental index updates');
     console.log('');
     console.log('Options:');
@@ -332,9 +336,59 @@ function printIndexUsage() {
     console.log('  aiwg index deps .aiwg/requirements/UC-001.md');
     console.log('  aiwg index stats --json');
     console.log('  aiwg index stats --graph project');
+    console.log('  aiwg index eval-discovery --queries test/fixtures/artifacts/discovery-relevance.jsonl --backend local --strategy lexical');
     console.log('  aiwg index neighbors --graph citation-network --node REF-008 --direction in --edge-type cites');
     console.log('  aiwg index set --graph citation-network --op intersection --node-a REF-008 --node-b REF-016 --direction in');
 }
+async function handleEvalDiscovery(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log('Usage: aiwg index eval-discovery --queries <jsonl> --backend <local|fortemi-core> --strategy <lexical|dense|hybrid-rrf|rerank|chunk-multivector> [options]');
+        console.log('');
+        console.log('Options:');
+        console.log('  --queries <path>   Versioned relevance JSONL fixture (required)');
+        console.log('  --backend <name>   local or fortemi-core (required)');
+        console.log('  --strategy <name>  lexical, dense, hybrid-rrf, rerank, or chunk-multivector');
+        console.log('  --out <path>       Write the JSON report to a file');
+        console.log('  --json             Emit JSON instead of the readable summary');
+        return;
+    }
+    const queries = parseFlagValue(args, '--queries', 'Error: --queries requires a JSONL path');
+    if (!queries) {
+        console.error('Error: --queries is required');
+        process.exit(1);
+    }
+    const backend = parseFlagValue(args, '--backend', 'Error: --backend requires local or fortemi-core');
+    if (backend !== 'local' && backend !== 'fortemi-core') {
+        console.error('Error: --backend must be local or fortemi-core');
+        process.exit(1);
+    }
+    const strategy = parseFlagValue(args, '--strategy', 'Error: --strategy requires a value') ?? 'lexical';
+    const { DISCOVERY_EVAL_STRATEGIES, evaluateDiscovery, formatDiscoveryEvalSummary } = await import('./discovery-eval.js');
+    if (!DISCOVERY_EVAL_STRATEGIES.includes(strategy)) {
+        console.error(`Error: --strategy must be ${DISCOVERY_EVAL_STRATEGIES.join(', ')}`);
+        process.exit(1);
+    }
+    try {
+        const report = await evaluateDiscovery({
+            cwd: process.cwd(),
+            fixturePath: path.resolve(queries),
+            backend,
+            strategy: strategy,
+        });
+        const serialized = `${JSON.stringify(report, null, 2)}\n`;
+        const out = parseFlagValue(args, '--out', 'Error: --out requires a path');
+        if (out) {
+            const fs = await import('node:fs');
+            fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
+            fs.writeFileSync(path.resolve(out), serialized);
+        }
+        console.log(args.includes('--json') ? serialized.trimEnd() : formatDiscoveryEvalSummary(report));
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+}
 /**
  * Handle 'index watch' command — filesystem watcher daemon for auto-index updates.
  *
@@ -1308,7 +1362,7 @@ async function handleDiscover(args) {
     if (!phrase) {
         console.error('Error: aiwg index discover requires a search phrase');
         console.log('');
-        console.log('Usage: aiwg index discover "<phrase>" [--type <kinds>] [--limit N] [--json|--format json|text] [--pretty|--compact] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <exact-or-channel>] [--offline]');
+        console.log('Usage: aiwg index discover "<phrase>" [--type <kinds>] [--limit N] [--json|--format json|text] [--pretty|--compact] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <version|range|digest|channel>] [--offline]');
         console.log('');
         console.log('Examples:');
         console.log('  aiwg index discover "create intake"');
@@ -1388,8 +1442,8 @@ async function handleShow(args) {
     }
     const HELP_TEXT = [
         '',
-        'Usage: aiwg show <type> <name> [--json] [--first] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <exact-or-channel>] [--offline]',
-        '       aiwg show metadata <id-or-name-or-path> [--json] [--first] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <exact-or-channel>] [--offline]',
+        'Usage: aiwg show <type> <name> [--json] [--first] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <version|range|digest|channel>] [--offline]',
+        '       aiwg show metadata <id-or-name-or-path> [--json] [--first] [--graph <name>] [--backend local|fortemi-core] [--resource-source local|web|auto] [--aiwg-version <version|range|digest|channel>] [--offline]',
         '       aiwg index show <type> <name> ...',
         '',
         `Types: ${OPERATIONAL_SHOW_TYPES.join(' | ')}`,

package/dist/src/artifacts/discover-facets.js

@@ -108,6 +108,21 @@ export const DISCOVER_FACETS = [
         ],
         capabilities: ['new-project', 'new-bundle'],
     },
+    {
+        facet: 'feature-domain',
+        label: 'Project-local bundle lifecycle',
+        intents: [
+            'project-local bundle',
+            'create project-local bundle',
+            'deploy project-local bundle',
+            'doctor project-local bundle',
+            'promote bundle',
+            'promote project-local',
+            'graduate project-local bundle',
+            'graduate to upstream',
+        ],
+        capabilities: ['new-bundle', 'use', 'aiwg-doctor', 'promote'],
+    },
     {
         facet: 'provider-capability',
         label: 'Provider capability routing (native vs emulated)',

package/dist/src/artifacts/discovery-eval.js

@@ -0,0 +1,290 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { OPERATIONAL_DISCOVERY_TYPES } from './types.js';
+import { loadGraphIndexFile } from './index-reader.js';
+import { loadFortemiCoreExport, loadFortemiCoreMetadataEntries, scoreStaticRecord } from './fortemi-core-query-adapter.js';
+import { discoverCapability } from './query-engine.js';
+export const DISCOVERY_EVAL_SCHEMA = 'aiwg.discovery-relevance.v1';
+export const DISCOVERY_EVAL_REPORT_SCHEMA = 'aiwg.discovery-eval-report.v1';
+export const DISCOVERY_EVAL_STRATEGIES = ['lexical', 'dense', 'hybrid-rrf', 'rerank', 'chunk-multivector'];
+const round = (value, digits = 6) => {
+    const scale = 10 ** digits;
+    return Math.round(value * scale) / scale;
+};
+function percentile(values, p) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.ceil(p * sorted.length) - 1] ?? sorted[sorted.length - 1];
+}
+function stringArray(value, label, line) {
+    if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== 'string' || item.trim() === '')) {
+        throw new Error(`Discovery relevance fixture line ${line}: ${label} must be a non-empty string array`);
+    }
+    return value;
+}
+export function parseDiscoveryRelevanceJsonl(content) {
+    const records = [];
+    const ids = new Set();
+    for (const [offset, raw] of content.split(/\r?\n/).entries()) {
+        if (raw.trim() === '')
+            continue;
+        const line = offset + 1;
+        let value;
+        try {
+            value = JSON.parse(raw);
+        }
+        catch (error) {
+            throw new Error(`Discovery relevance fixture line ${line}: malformed JSON (${error instanceof Error ? error.message : String(error)})`);
+        }
+        if (value.schema !== DISCOVERY_EVAL_SCHEMA)
+            throw new Error(`Discovery relevance fixture line ${line}: unsupported schema`);
+        if (typeof value.id !== 'string' || value.id.trim() === '')
+            throw new Error(`Discovery relevance fixture line ${line}: id must be a non-empty string`);
+        if (ids.has(value.id))
+            throw new Error(`Discovery relevance fixture line ${line}: duplicate query id '${value.id}'`);
+        ids.add(value.id);
+        if (typeof value.query !== 'string' || value.query.trim() === '')
+            throw new Error(`Discovery relevance fixture line ${line}: query must be a non-empty string`);
+        if (!OPERATIONAL_DISCOVERY_TYPES.includes(String(value.target_type))) {
+            throw new Error(`Discovery relevance fixture line ${line}: invalid target_type '${String(value.target_type)}'`);
+        }
+        const classes = ['exact-name', 'capability', 'process-step', 'hard-negative', 'cross-type'];
+        if (!classes.includes(String(value.query_class)))
+            throw new Error(`Discovery relevance fixture line ${line}: invalid query_class '${String(value.query_class)}'`);
+        records.push({
+            schema: DISCOVERY_EVAL_SCHEMA, id: value.id, query: value.query,
+            target_type: value.target_type,
+            relevant_ids: stringArray(value.relevant_ids, 'relevant_ids', line),
+            hard_negative_ids: stringArray(value.hard_negative_ids, 'hard_negative_ids', line),
+            query_class: value.query_class,
+            ...(typeof value.notes === 'string' ? { notes: value.notes } : {}),
+        });
+    }
+    if (records.length === 0)
+        throw new Error('Discovery relevance fixture contains no queries');
+    return records;
+}
+export function validateOperationalCoverage(records, minimum = 10) {
+    for (const type of OPERATIONAL_DISCOVERY_TYPES) {
+        const count = records.filter((record) => record.target_type === type).length;
+        if (count < minimum)
+            throw new Error(`Discovery relevance fixture requires at least ${minimum} '${type}' queries; found ${count}`);
+    }
+}
+function terms(text) {
+    return [...new Set(text.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim().split(/\s+/).filter((term) => term.length > 1))];
+}
+function identity(entry) { return `${entry.type}:${entry.name ?? entry.title}`.toLowerCase(); }
+function matches(item, expected) {
+    const needle = expected.toLowerCase();
+    return item.id.toLowerCase() === needle || `${item.type}:${item.name}`.toLowerCase() === needle;
+}
+function fields(entry) {
+    return [entry.name ?? '', entry.title, entry.capability ?? '', entry.summary, ...(entry.triggers ?? []), ...(entry.searchTerms ?? []), entry.path].filter(Boolean);
+}
+function cosine(left, right) {
+    const a = terms(left);
+    const b = terms(right);
+    if (!a.length || !b.length)
+        return 0;
+    const set = new Set(b);
+    return a.filter((term) => set.has(term)).length / Math.sqrt(a.length * b.length);
+}
+function prototypeRank(entries, query, strategy, limit) {
+    const dense = entries.map((entry) => ({ entry, score: cosine(query, fields(entry).join(' ')) }));
+    const lexical = entries.map((entry) => {
+        const queryTerms = terms(query);
+        const values = fields(entry).map((field) => field.toLowerCase());
+        const hits = queryTerms.filter((term) => values.some((value) => value.includes(term))).length;
+        return { entry, score: (values.some((value) => value === query.toLowerCase()) ? 1 : 0) + (queryTerms.length ? hits / queryTerms.length : 0) };
+    });
+    let ranked;
+    if (strategy === 'dense')
+        ranked = dense;
+    else if (strategy === 'chunk-multivector')
+        ranked = entries.map((entry) => ({ entry, score: Math.max(...fields(entry).map((field) => cosine(query, field)), 0) }));
+    else if (strategy === 'rerank')
+        ranked = [...lexical].sort((a, b) => b.score - a.score).slice(0, 50)
+            .map((candidate) => ({ entry: candidate.entry, score: candidate.score + 0.35 * cosine(query, fields(candidate.entry).join(' ')) }));
+    else {
+        const fused = new Map();
+        for (const list of [lexical, dense]) {
+            [...list].sort((a, b) => b.score - a.score || identity(a.entry).localeCompare(identity(b.entry))).forEach((candidate, rank) => {
+                const key = identity(candidate.entry);
+                const current = fused.get(key) ?? { entry: candidate.entry, score: 0 };
+                current.score += 1 / (61 + rank);
+                fused.set(key, current);
+            });
+        }
+        ranked = [...fused.values()];
+    }
+    return ranked.filter((candidate) => candidate.score > 0)
+        .sort((a, b) => b.score - a.score || identity(a.entry).localeCompare(identity(b.entry))).slice(0, limit)
+        .map(({ entry, score }) => ({ id: identity(entry), type: entry.type, name: entry.name ?? entry.title, score: round(score) }));
+}
+async function currentRank(cwd, query, backend, limit) {
+    const output = [];
+    const original = console.log;
+    console.log = (...args) => output.push(args.map(String).join(' '));
+    try {
+        await discoverCapability(cwd, { phrase: query.query, typeFilter: [query.target_type], graph: 'framework', backend, limit, json: true, jsonPretty: false, includePaths: false });
+    }
+    finally {
+        console.log = original;
+    }
+    const envelope = JSON.parse(output.join(''));
+    return envelope.results.map((item) => ({ id: item.id, type: item.type, name: item.name ?? item.title, score: item.score }));
+}
+function fortemiStaticRank(exported, query, limit) {
+    const queryTerms = query.query.toLowerCase().split(/[^a-z0-9-]+/).map((term) => term.trim()).filter((term) => term.length > 2);
+    return exported.items
+        .filter((record) => (record.search?.type ?? record.type.replace(/^aiwg:/, '')) === query.target_type)
+        .map((record) => ({ record, ...scoreStaticRecord(record, queryTerms) }))
+        .filter((item) => item.score > 0)
+        .sort((a, b) => b.score - a.score || a.record.source.path.localeCompare(b.record.source.path))
+        .slice(0, limit)
+        .map(({ record, score }) => ({
+        id: `${query.target_type}:${record.name ?? record.search?.name ?? record.title}`.toLowerCase(),
+        type: query.target_type,
+        name: record.name ?? record.search?.name ?? record.title,
+        score: round(score),
+    }));
+}
+function loadEntries(cwd, backend) {
+    if (backend === 'fortemi-core') {
+        const loaded = loadFortemiCoreMetadataEntries(cwd, 'framework');
+        if (!loaded.entries.length)
+            throw new Error(loaded.reason ?? 'Fortemi Core framework index is empty');
+        return loaded.entries;
+    }
+    const index = loadGraphIndexFile(cwd, 'metadata.json', 'framework');
+    if (!index)
+        throw new Error('Local framework index is missing; run `aiwg index build --graph framework`');
+    return Object.values(index.entries);
+}
+export function calculateDiscoveryMetrics(records, resultSets) {
+    const ranks = records.map((record, index) => {
+        const rank = (resultSets[index] ?? []).findIndex((item) => record.relevant_ids.some((id) => matches(item, id)));
+        return rank < 0 ? null : rank + 1;
+    });
+    const hit = (k) => ranks.filter((rank) => rank !== null && rank <= k).length / records.length;
+    const perType = {};
+    for (const type of OPERATIONAL_DISCOVERY_TYPES) {
+        const selected = records.map((record, index) => ({ record, index })).filter(({ record }) => record.target_type === type);
+        perType[type] = round(selected.filter(({ index }) => ranks[index] !== null && ranks[index] <= 3).length / selected.length);
+    }
+    return {
+        query_count: records.length, hit_at_1: round(hit(1)), hit_at_3: round(hit(3)), hit_at_5: round(hit(5)),
+        mrr: round(ranks.reduce((sum, rank) => sum + (rank === null ? 0 : 1 / rank), 0) / records.length),
+        ndcg_at_10: round(ranks.reduce((sum, rank) => sum + (rank === null || rank > 10 ? 0 : 1 / Math.log2(rank + 1)), 0) / records.length),
+        per_type_recall_at_3: perType,
+        hard_negative_intrusion_at_5: round(records.filter((record, index) => (resultSets[index] ?? []).slice(0, 5)
+            .some((item) => record.hard_negative_ids.some((id) => matches(item, id)))).length / records.length),
+    };
+}
+function indexBytes(backend) {
+    const root = path.join(process.env.XDG_DATA_HOME ?? path.join(os.homedir(), '.local', 'share'), 'aiwg', 'index', ...(backend === 'local' ? ['framework'] : ['fortemi-core', 'framework']));
+    let total = 0;
+    const visit = (target) => {
+        if (!fs.existsSync(target))
+            return;
+        const stat = fs.statSync(target);
+        if (stat.isFile())
+            total += stat.size;
+        else
+            for (const child of fs.readdirSync(target))
+                visit(path.join(target, child));
+    };
+    visit(root);
+    return total;
+}
+export async function evaluateDiscovery(options) {
+    const records = parseDiscoveryRelevanceJsonl(fs.readFileSync(options.fixturePath, 'utf8'));
+    validateOperationalCoverage(records);
+    const limit = options.limit ?? 10;
+    const entries = loadEntries(options.cwd, options.backend);
+    const fortemiExport = options.backend === 'fortemi-core' && options.strategy === 'lexical'
+        ? loadFortemiCoreExport(options.cwd, 'framework')
+        : null;
+    if (fortemiExport && !fortemiExport.exported) {
+        throw new Error(fortemiExport.reason ?? 'Fortemi Core framework export is unavailable');
+    }
+    const resultSets = [];
+    const latencies = [];
+    let peakRss = process.memoryUsage().rss;
+    for (const record of records) {
+        const start = performance.now();
+        resultSets.push(options.strategy === 'lexical'
+            ? options.backend === 'fortemi-core'
+                ? fortemiStaticRank(fortemiExport.exported, record, limit)
+                : await currentRank(options.cwd, record, options.backend, limit)
+            : prototypeRank(entries.filter((entry) => entry.type === record.target_type), record.query, options.strategy, limit));
+        latencies.push(performance.now() - start);
+        peakRss = Math.max(peakRss, process.memoryUsage().rss);
+    }
+    const metrics = calculateDiscoveryMetrics(records, resultSets);
+    const cpus = os.cpus();
+    let parity;
+    if (options.backend === 'fortemi-core' && options.strategy === 'lexical') {
+        const localSets = [];
+        for (const record of records)
+            localSets.push(await currentRank(options.cwd, record, 'local', limit));
+        const differingQueries = [];
+        let topOneAgreements = 0;
+        let topFiveOverlap = 0;
+        for (let index = 0; index < records.length; index++) {
+            const fortemi = resultSets[index];
+            const local = localSets[index];
+            const key = (item) => item ? `${item.type}:${item.name}`.toLowerCase() : '';
+            if (key(fortemi[0]) === key(local[0]))
+                topOneAgreements++;
+            else
+                differingQueries.push(records[index].id);
+            const localFive = new Set(local.slice(0, 5).map((item) => key(item)));
+            topFiveOverlap += fortemi.slice(0, 5).filter((item) => localFive.has(key(item))).length / Math.max(1, Math.min(5, local.length, fortemi.length));
+        }
+        parity = {
+            compared_to: 'local:lexical',
+            top_1_agreement: round(topOneAgreements / records.length),
+            top_5_overlap: round(topFiveOverlap / records.length),
+            differing_queries: differingQueries,
+        };
+    }
+    return {
+        schema: DISCOVERY_EVAL_REPORT_SCHEMA,
+        corpus: { path: path.relative(options.cwd, options.fixturePath).replace(/\\/g, '/'), schema: DISCOVERY_EVAL_SCHEMA, query_count: records.length },
+        configuration: { backend: options.backend, strategy: options.strategy, limit, graph: 'framework' },
+        hardware: { platform: os.platform(), arch: os.arch(), cpu_model: cpus[0]?.model ?? 'unknown', logical_cpus: cpus.length, total_memory_bytes: os.totalmem(), node: process.version },
+        metrics,
+        performance: { p50_latency_ms: round(percentile(latencies, 0.5), 3), p95_latency_ms: round(percentile(latencies, 0.95), 3), index_bytes: indexBytes(options.backend), peak_resident_memory_bytes: peakRss },
+        ...(parity ? { parity } : {}),
+        adoption_gate: {
+            baseline: 'local:lexical', no_per_type_hit_at_3_regression: null, aggregate_mrr_improvement: null,
+            mrr_95pct_confidence_interval: null, latency_ceiling_ms: options.latencyCeilingMs ?? 250,
+            storage_ceiling_ratio: options.storageCeilingRatio ?? 2, clears_gate: null,
+            decision: 'Run the full strategy matrix and compare against local:lexical before adoption.',
+        },
+        queries: records.map((record, index) => {
+            const rank = resultSets[index].findIndex((item) => record.relevant_ids.some((id) => matches(item, id)));
+            return { id: record.id, target_type: record.target_type, relevant_rank: rank < 0 ? null : rank + 1, reciprocal_rank: rank < 0 ? 0 : round(1 / (rank + 1)), latency_ms: round(latencies[index], 3), results: resultSets[index] };
+        }),
+    };
+}
+export function formatDiscoveryEvalSummary(report) {
+    const m = report.metrics;
+    return [
+        `Discovery evaluation: ${report.configuration.backend}:${report.configuration.strategy}`,
+        `Corpus: ${report.corpus.query_count} queries (${report.corpus.path})`, '',
+        'Metric                Value', `Hit@1                 ${m.hit_at_1.toFixed(4)}`, `Hit@3                 ${m.hit_at_3.toFixed(4)}`,
+        `Hit@5                 ${m.hit_at_5.toFixed(4)}`, `MRR                   ${m.mrr.toFixed(4)}`, `nDCG@10               ${m.ndcg_at_10.toFixed(4)}`,
+        `Hard-negative@5       ${m.hard_negative_intrusion_at_5.toFixed(4)}`, `p50 latency           ${report.performance.p50_latency_ms.toFixed(3)} ms`,
+        `p95 latency           ${report.performance.p95_latency_ms.toFixed(3)} ms`, `Index bytes           ${report.performance.index_bytes}`,
+        `Peak resident memory  ${report.performance.peak_resident_memory_bytes}`, '', 'Per-type Hit@3:',
+        ...Object.entries(m.per_type_recall_at_3).map(([type, value]) => `  ${type.padEnd(10)} ${value.toFixed(4)}`), '',
+        `Decision: ${report.adoption_gate.decision}`,
+    ].join('\n');
+}
+//# sourceMappingURL=discovery-eval.js.map

package/dist/src/artifacts/fortemi-core-query-adapter.js

@@ -19,7 +19,7 @@ function includesAny(text, terms) {
     }
     return matches;
 }
-function scoreStaticRecord(record, terms) {
+export function scoreStaticRecord(record, terms) {
     const fields = [
         { name: "title", text: record.title, weight: 3 },
         { name: "name", text: record.name ?? record.search?.name ?? "", weight: 3 },

package/dist/src/artifacts/fortemi-shard-export.js

@@ -5,7 +5,7 @@ async function loadFortemiShardConverter() {
     let core;
     try {
         core = (await import(
-        /* @vite-ignore */ "@fortemi/core/aiwg-index"));
+        /* @vite-ignore */ "@fortemi/core/aiwg-index-shard"));
     }
     catch {
         throw new Error("Portable Fortemi shard export requires @fortemi/core with aiwgFortemiIndexToKnowledgeShard.");

package/dist/src/artifacts/query-engine.js

@@ -1740,14 +1740,18 @@ export async function showArtifact(cwd, params) {
         try {
             if (!webRelease)
                 throw new Error('verified web release context is unavailable');
-            const { fetchVerifiedRawResource } = await import('../resources/web-release.js');
-            const bytes = await fetchVerifiedRawResource(webRelease, filePath, {
-                baseUrl: params.webReleaseOptions?.baseUrl,
-                fetcher: params.webReleaseOptions?.fetcher,
-                allowInsecureLoopbackHttp: params.webReleaseOptions?.allowInsecureLoopbackHttp,
+            const { logicalIdFromFirstPartyPath, resolveAiwgResourceBytes } = await import('../resources/resolver.js');
+            const logicalId = logicalIdFromFirstPartyPath(entry.path);
+            if (!logicalId)
+                throw new Error(`indexed path is not a first-party AIWG resource: ${entry.path}`);
+            const resolved = await resolveAiwgResourceBytes(logicalId, {
+                source: 'web',
+                frameworkRoot: aiwgRoot ?? cwd,
+                webRelease,
+                webReleaseOptions: params.webReleaseOptions,
                 offline: params.offline,
             });
-            content = bytes.toString('utf8');
+            content = resolved.bytes.toString('utf8');
         }
         catch (error) {
             console.error(`Error: AIWG web resource show failed: ${error instanceof Error ? error.message : String(error)}`);

package/dist/src/cli/handlers/help.js

@@ -80,6 +80,7 @@ function displayHelp() {
     helpGroup('DISCOVERY', [
         ['discover "<phrase>"', 'Find skills/agents/commands/rules by capability'],
         ['show <type> <name>', 'Stream the body of an indexed artifact'],
+        ['versions <list|resolve|show>', 'Browse and resolve signed AIWG web resource releases'],
         ['index <subcommand>', 'Manage the artifact index (build/query/discover/deps/stats)'],
         ['artifacts move --to <path>', 'Move/rename the project AIWG artifact root and reindex'],
     ]);
@@ -120,7 +121,7 @@ function displayHelp() {
         ['doctor', 'Check installation health'],
         ['version', 'Show version and channel info'],
         ['refresh', 'Update AIWG and redeploy frameworks (formerly: sync)'],
-        ['update', 'Check for updates'],
+        ['update', 'Update the active installation and re-deploy installed frameworks (alias: upgrade)'],
         ['help', 'Show this help message'],
     ]);
     helpGroup('CHANNEL', [

package/dist/src/cli/handlers/index.js

@@ -54,6 +54,7 @@ import { cockpitHandler } from './cockpit.js';
 import { commandLogHandler } from './command-log.js';
 import { skillUsageHandler } from './skill-usage.js';
 import { modelsHandler } from './models.js';
+import { versionsHandler } from './resource-versions.js';
 // Re-export individual handlers
 export { 
 // Maintenance
@@ -65,7 +66,7 @@ newBundleHandler, quickrefHandler, newProjectHandler,
 // Workspace
 statusHandler, wizardHandler, migrateWorkspaceHandler, rollbackWorkspaceHandler, 
 // Subcommands
-mcpHandler, catalogHandler, modelsHandler, indexHandler, artifactsHandler, corpusHandler, discoverHandler, showHandler, featuresHandler, skillsHandler, configHandler, opsHandler, storageHandler, activityLogHandler, commandLogHandler, skillUsageHandler, kbHandler, memoryHandler, reflectionsHandler, provenanceHandler, researchStoreHandler, researchQueryHandler, runtimeInfoHandler, agentcardHandler, 
+mcpHandler, catalogHandler, modelsHandler, versionsHandler, indexHandler, artifactsHandler, corpusHandler, discoverHandler, showHandler, featuresHandler, skillsHandler, configHandler, opsHandler, storageHandler, activityLogHandler, commandLogHandler, skillUsageHandler, kbHandler, memoryHandler, reflectionsHandler, provenanceHandler, researchStoreHandler, researchQueryHandler, runtimeInfoHandler, agentcardHandler, 
 // Agentic Tools (RLM)
 chunkHandler, fanoutHandler, rlmPrepHandler, rlmSearchHandler, rlmStatusCliHandler, rlmCacheHandler, 
 // Utilities
@@ -139,6 +140,7 @@ export const allHandlers = [
     mcpHandler,
     catalogHandler,
     modelsHandler,
+    versionsHandler,
     indexHandler,
     artifactsHandler,
     corpusHandler,