@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

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

@@ -0,0 +1,1955 @@
+/**
+ * Artifact Query Engine
+ *
+ * Searches the artifact index by keyword, type, phase, tags, and path pattern.
+ * Returns ranked results in human-readable or JSON format.
+ *
+ * @implements #416
+ * @source @src/artifacts/types.ts
+ * @tests @test/unit/artifacts/query-engine.test.ts
+ */
+import { minimatch } from 'minimatch';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { OPERATIONAL_DISCOVERY_TYPES, OPERATIONAL_SHOW_TYPES, isOperationalShowType, loadGlobalGraphConfigs, } from './types.js';
+import { loadMetadataIndex, loadGraphIndexFile } from './index-reader.js';
+import { bm25Rank } from './fulltext.js';
+import { parseFrontmatter } from './index-builder.js';
+import { applyFacetFusion, diagnoseFacetActivations, } from './discover-facets.js';
+import { recordTypeForEntry, stableRecordId, } from './browser-export.js';
+import { loadProviderModelMetadata } from '../models/provider-models.js';
+import { operationalStateQueryProjection, } from './operational-state.js';
+import { projectAiwgPath } from '../config/project-artifacts.js';
+function normalizeIndexedPath(entryPath) {
+    return entryPath.replace(/\\/g, '/');
+}
+/**
+ * Resolve an index entry's source file path and read its body (frontmatter
+ * stripped). Entry paths are normally relative to the project; framework-graph
+ * entries may be absolute or anchored to $AIWG_ROOT. Returns null when the
+ * file can't be read (stale index entry) so full-text ranking skips it.
+ */
+function readEntryBody(cwd, entryPath) {
+    const candidates = [];
+    if (path.isAbsolute(entryPath))
+        candidates.push(entryPath);
+    else {
+        const normalizedPath = normalizeIndexedPath(entryPath);
+        if (normalizedPath.startsWith('.aiwg/')) {
+            candidates.push(projectAiwgPath(cwd, normalizedPath.slice('.aiwg/'.length)));
+        }
+        candidates.push(path.resolve(cwd, normalizedPath));
+        if (process.env.AIWG_ROOT)
+            candidates.push(path.resolve(process.env.AIWG_ROOT, normalizedPath));
+    }
+    for (const p of candidates) {
+        try {
+            const raw = fs.readFileSync(p, 'utf8');
+            return parseFrontmatter(raw).body;
+        }
+        catch {
+            /* try next candidate */
+        }
+    }
+    return null;
+}
+const DEFAULT_ARTIFACT_SEARCH_BACKEND = 'fortemi-core';
+const DISCOVER_TYPE_ORDER = new Map([...OPERATIONAL_DISCOVERY_TYPES, 'hook', 'doc'].map((type, index) => [type, index]));
+function canonicalLocalityRank(entryPath) {
+    const normalized = entryPath.replace(/\\/g, '/');
+    if (normalized.startsWith('.aiwg/') || normalized.includes('/.aiwg/'))
+        return 0;
+    if (normalized.includes('/plugins/') || normalized.startsWith('agentic/code/plugins/'))
+        return 3;
+    if (normalized.includes('/frameworks/') ||
+        normalized.includes('/addons/') ||
+        normalized.includes('/extensions/') ||
+        normalized.startsWith('agentic/code/frameworks/') ||
+        normalized.startsWith('agentic/code/addons/') ||
+        normalized.startsWith('agentic/code/extensions/')) {
+        return 2;
+    }
+    return 1;
+}
+function graphScope(graph) {
+    if (graph === 'project')
+        return 'project';
+    if (graph === 'user' || graph.startsWith('user-'))
+        return 'user';
+    if (graph === 'framework')
+        return 'packaged';
+    if (graph === 'codebase' || graph === 'source')
+        return 'codebase';
+    return 'custom';
+}
+function withIndexProvenance(entry, graph) {
+    return { ...entry, indexGraph: graph, indexScope: graphScope(graph) };
+}
+function discoveryIdForEntry(entry) {
+    return stableRecordId(recordTypeForEntry(entry, 'v2'), entry.path);
+}
+function logicalDiscoverKey(entry) {
+    const identity = (entry.name ?? entry.title ?? path.basename(entry.path))
+        .toLowerCase()
+        .replace(/[-_\s]+/g, ' ')
+        .trim();
+    return `${entry.type}:${identity}`;
+}
+function dedupeDiscoverResults(results) {
+    const bestByIdentity = new Map();
+    for (const result of results) {
+        const key = logicalDiscoverKey(result.entry);
+        const existing = bestByIdentity.get(key);
+        if (!existing || compareDiscoverResults(result, existing) < 0) {
+            bestByIdentity.set(key, result);
+        }
+    }
+    return Array.from(bestByIdentity.values()).sort(compareDiscoverResults);
+}
+function scopeRank(entry) {
+    const scope = entry.indexScope;
+    if (scope === 'project')
+        return 0;
+    if (scope === 'user')
+        return 1;
+    if (scope === 'custom')
+        return 2;
+    if (scope === 'packaged')
+        return 3;
+    if (scope === 'codebase')
+        return 4;
+    return canonicalLocalityRank(entry.path);
+}
+function compareText(left, right) {
+    return (left ?? '').localeCompare(right ?? '');
+}
+export function compareDiscoverResults(left, right) {
+    const scoreCmp = right.score - left.score;
+    if (scoreCmp !== 0)
+        return scoreCmp;
+    const localityCmp = scopeRank(left.entry) - scopeRank(right.entry);
+    if (localityCmp !== 0)
+        return localityCmp;
+    const typeCmp = (DISCOVER_TYPE_ORDER.get(left.entry.type) ?? 99) -
+        (DISCOVER_TYPE_ORDER.get(right.entry.type) ?? 99);
+    if (typeCmp !== 0)
+        return typeCmp;
+    const nameCmp = compareText(left.entry.name ?? left.entry.title, right.entry.name ?? right.entry.title);
+    if (nameCmp !== 0)
+        return nameCmp;
+    return left.entry.path.localeCompare(right.entry.path);
+}
+/**
+ * Stop-words to drop when tokenizing a discovery phrase. Keep short —
+ * we want the user's verbs and nouns to dominate scoring.
+ */
+// Stopwords stripped from a discover QUERY before scoring (#1581). Two classes:
+//   1. Grammatical filler (articles, prepositions, pronouns, question words,
+//      asking verbs) — a natural-language intent like "Find an AIWG skill that
+//      handles intake forms" carries the same meaning as "intake forms", but the
+//      filler tokens inflate the token count: the strict overlap gate is
+//      ceil(n/2), so a verbose query raises the bar above what the genuinely
+//      relevant short-match artifact can clear, and the (hits/n) term dilutes
+//      every score. Dropping filler collapses the query to its content tokens.
+//   2. AIWG meta-type nouns ('aiwg', 'skill', 'agent', 'command', 'rule',
+//      'flow', 'workflow') — in a discover query these carry zero discriminating
+//      signal (every result IS an aiwg skill/agent/…; the TYPE is filtered via
+//      --type). The content word after them is what matters
+//      ("…skill that handles >intake forms<"). Keeping them surfaces incidental
+//      junk matches (any artifact mentioning "skill"/"aiwg") above the real one.
+// Only the query is tokenized here — entry fields are substring-matched — so this
+// never changes what text an artifact exposes, only how the query is reduced.
+const SCORE_STOPWORDS = new Set([
+    // articles / conjunctions / prepositions / copula
+    'the', 'a', 'an', 'and', 'or', 'of', 'for', 'to', 'in', 'on',
+    'with', 'into', 'from', 'is', 'are', 'be', 'i', 'we', 'my',
+    // pronouns / determiners / fillers
+    'it', 'you', 'me', 'us', 'your', 'our', 'this', 'that', 'these', 'those',
+    'there', 'here', 'some', 'any', 'all', 'also', 'please', 'about',
+    // question words
+    'how', 'what', 'which', 'where', 'when', 'who', 'why',
+    // asking / request verbs ("find a skill that handles …")
+    'find', 'give', 'show', 'need', 'want', 'looking', 'look', 'help',
+    'do', 'does', 'did', 'can', 'could', 'should', 'would', 'will',
+    'handle', 'handles', 'handling',
+    // AIWG meta-type nouns — zero discriminating signal in a discover query
+    'aiwg', 'skill', 'skills', 'agent', 'agents', 'command', 'commands',
+    'rule', 'rules', 'flow', 'flows', 'workflow', 'workflows',
+]);
+/**
+ * Tokenize a query phrase into lowercased keywords for multi-word
+ * scoring. Splits on whitespace and punctuation; drops stopwords and
+ * single-character tokens.
+ */
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9-]+/)
+        .filter(t => t.length > 1 && !SCORE_STOPWORDS.has(t));
+}
+/**
+ * Score a metadata entry against a keyword query.
+ *
+ * Multi-word queries are tokenized; each token contributes its weighted
+ * match across the entry's searchable fields. The full phrase still
+ * earns bonus weight when it appears as a contiguous substring or as
+ * an exact trigger phrase (the most reliable signal).
+ *
+ * For AIWG artifact kinds (skills/agents/commands/rules) the entry
+ * carries `triggers` (declared activation phrases) and `capability`
+ * (one-line description). These get the highest weights so capability
+ * search via `aiwg index discover` ranks the right skill on top
+ * instead of bottoming out on a path-substring match (#1214).
+ */
+/**
+ * Normalize a string for exact-name comparison (#1233) — lowercase and
+ * collapse `-` / `_` / whitespace runs so hyphenated kernel-skill names
+ * like `aiwg-doctor` match queries with spaces ("aiwg doctor") and the
+ * rendered title ("AIWG Doctor") matches the slug query.
+ */
+function normalizeName(s) {
+    return s.toLowerCase().replace(/[-_\s]+/g, ' ').trim();
+}
+function damerauLevenshteinAtMostOne(a, b) {
+    if (a === b)
+        return true;
+    if (Math.abs(a.length - b.length) > 1)
+        return false;
+    if (a.length === b.length) {
+        let firstDiff = -1;
+        let diffCount = 0;
+        for (let i = 0; i < a.length; i++) {
+            if (a[i] !== b[i]) {
+                if (firstDiff < 0)
+                    firstDiff = i;
+                diffCount++;
+            }
+        }
+        if (diffCount === 1)
+            return true;
+        return diffCount === 2
+            && firstDiff + 1 < a.length
+            && a[firstDiff] === b[firstDiff + 1]
+            && a[firstDiff + 1] === b[firstDiff];
+    }
+    const shorter = a.length < b.length ? a : b;
+    const longer = a.length < b.length ? b : a;
+    let i = 0;
+    let j = 0;
+    let edits = 0;
+    while (i < shorter.length && j < longer.length) {
+        if (shorter[i] === longer[j]) {
+            i++;
+            j++;
+        }
+        else {
+            edits++;
+            if (edits > 1)
+                return false;
+            j++;
+        }
+    }
+    return true;
+}
+function nearNameMatch(query, name) {
+    const queryParts = normalizeName(query).split(/\s+/).filter(Boolean);
+    const nameParts = normalizeName(name).split(/\s+/).filter(Boolean);
+    if (queryParts.length !== nameParts.length)
+        return false;
+    return queryParts.every((part, i) => {
+        const target = nameParts[i];
+        if (part === target)
+            return true;
+        if (part.length < 5 || target.length < 5)
+            return false;
+        return damerauLevenshteinAtMostOne(part, target);
+    });
+}
+function scoreEntryDetailed(entry, text, opts = {}) {
+    const tokens = tokenize(text);
+    // Field substring matching uses the stopword-stripped CONTENT phrase, not the
+    // raw query (#1581). Without this, a query that reduces to a single content
+    // token — e.g. "intake skill" or "find an intake skill" → ["intake"] — sets
+    // useMultiToken=false (1 token) and then fails the full-string `.includes()`
+    // checks because the raw phrase ("intake skill") isn't a substring of any
+    // field, while the one meaningful token is never matched. Joining the content
+    // tokens restores the invariant that a single content token IS the phrase, and
+    // for multi-token queries gives a tighter (content-only) phrase to match.
+    // Pure-stopword queries fall back to the raw text.
+    const lower = tokens.length > 0 ? tokens.join(' ') : text.toLowerCase().trim();
+    const rawLower = text.toLowerCase().trim();
+    const personaIdentitySuppressed = diagnoseFacetActivations(text).some((activation) => activation.facet === 'persona-identity' && activation.status === 'suppressed');
+    let score = 0;
+    const matches = [];
+    const finish = (uncappedScore = score, cap = 1) => ({
+        score: Math.min(uncappedScore, cap),
+        diagnostic: {
+            content_tokens: tokens,
+            raw_score: uncappedScore,
+            score: Math.min(uncappedScore, cap),
+            score_cap_applied: uncappedScore > cap,
+            matches,
+        },
+    });
+    const addMatch = (contribution, match) => {
+        score += contribution;
+        matches.push({ ...match, contribution });
+    };
+    // Exact-name floor (#1233) — if the query (normalized) exactly matches
+    // the entry's canonical name, this is the artifact the user is asking
+    // for and it must surface at the top regardless of how cluttered the
+    // rest of the corpus scoring gets. Hyphens, underscores, and whitespace
+    // are interchangeable in the comparison so `aiwg-doctor`, `aiwg doctor`,
+    // and `aiwg_doctor` all match a kernel skill with `name: aiwg-doctor`.
+    //
+    // Returns 1.001 (not 1.0) so an exact-name hit sorts above the many
+    // capped-at-1.0 substring matches that share generic words like "use".
+    // Display rounding (Math.round(score * 100) / 100) hides the offset, so
+    // the user still sees `score: 1.0` while sort order is preserved.
+    if (entry.name) {
+        const queryNorm = normalizeName(text);
+        const nameNorm = normalizeName(entry.name);
+        if (queryNorm === nameNorm) {
+            matches.push({
+                field: 'name',
+                match: 'exact',
+                value: entry.name,
+                contribution: 1.001,
+                matched_tokens: tokens,
+                query_token_coverage: 1,
+            });
+            return finish(1.001, 1.001);
+        }
+        if (nearNameMatch(text, entry.name)) {
+            matches.push({
+                field: 'name',
+                match: 'near-name',
+                value: entry.name,
+                contribution: 0.951,
+                matched_tokens: tokens,
+                query_token_coverage: 1,
+            });
+            return finish(0.951);
+        }
+    }
+    // Searchable text — joined once so per-token includes() is cheap
+    const titleLower = entry.title.toLowerCase();
+    const summaryLower = entry.summary.toLowerCase();
+    const pathLower = entry.path.toLowerCase();
+    const typeLower = entry.type.toLowerCase();
+    const capabilityLower = entry.capability ? entry.capability.toLowerCase() : '';
+    const tagsLower = entry.tags.map(t => t.toLowerCase());
+    const triggersLower = (entry.triggers ?? []).map(trigger => trigger.toLowerCase());
+    const searchTermsLower = (entry.searchTerms ?? []).join(' ').toLowerCase();
+    const kindLower = entry.kind?.toLowerCase() ?? '';
+    const sourceTypeLower = entry.sourceType?.toLowerCase() ?? '';
+    // For multi-token queries, require ≥50% token overlap to count
+    // partial matches. This keeps gibberish queries (e.g.,
+    // `xyzzy_zzqwkjhg_42` after splitting on `_`) from surfacing
+    // incidental single-token hits.
+    const useMultiToken = tokens.length > 1;
+    // #1561 — verbose natural-language queries (e.g. "skill that handles intake
+    // forms") dilute the token hit ratio below the ceil(n/2) overlap gate and
+    // dead-end to zero results. When the strict pass finds nothing, callers
+    // re-score with `relaxOverlap` so a single meaningful token hit (intake /
+    // forms) still surfaces ranked candidates instead of an empty set.
+    const minHits = useMultiToken
+        ? (opts.relaxOverlap ? 1 : Math.ceil(tokens.length / 2))
+        : 1;
+    const overlapOK = (hits) => useMultiToken && hits >= minHits;
+    // Trigger phrase match — highest weight (4x). Exact match on the full
+    // phrase wins big; substring or token-overlap is still strong.
+    if (triggersLower.length > 0) {
+        for (const trigger of triggersLower) {
+            const triggerTokens = tokenize(trigger);
+            const matchedTokens = tokens.filter((token) => triggerTokens.includes(token));
+            const queryCoverage = tokens.length > 0 ? matchedTokens.length / tokens.length : 0;
+            if (trigger === lower || trigger === rawLower) {
+                matches.push({
+                    field: 'trigger',
+                    match: 'exact',
+                    value: trigger,
+                    contribution: 1.0008,
+                    matched_tokens: matchedTokens,
+                    query_token_coverage: 1,
+                });
+                return finish(1.0008, 1.0008);
+            }
+            else if (trigger.includes(lower) ||
+                lower.includes(trigger) ||
+                trigger.includes(rawLower) ||
+                rawLower.includes(trigger)) {
+                const triggerInsideQuery = lower.includes(trigger) || rawLower.includes(trigger);
+                const containedCoverage = triggerInsideQuery
+                    ? queryCoverage
+                    : triggerTokens.length > 0
+                        ? matchedTokens.length / triggerTokens.length
+                        : 0;
+                // A complete multi-word trigger inside a noisier query is a strong
+                // metadata signal. The ambiguous one-word `persona` trigger is
+                // downweighted only when the facet classifier has identified buyer /
+                // audience marketing context; distinctive one-word triggers such as
+                // GRADE retain their established exact-trigger behavior (#1828).
+                const suppressedGenericPersona = personaIdentitySuppressed &&
+                    triggerTokens.length === 1 &&
+                    triggerTokens[0] === 'persona' &&
+                    tokens.length > 1;
+                const contribution = suppressedGenericPersona
+                    ? 0.24 * queryCoverage
+                    : triggerTokens.length > 1
+                        ? Math.min(1, 0.75 + 0.25 * containedCoverage)
+                        : 1;
+                addMatch(contribution, {
+                    field: 'trigger',
+                    match: 'contained-phrase',
+                    value: trigger,
+                    matched_tokens: matchedTokens,
+                    query_token_coverage: queryCoverage,
+                });
+            }
+            else if (useMultiToken) {
+                const hits = tokens.filter(t => trigger.includes(t));
+                if (overlapOK(hits.length)) {
+                    addMatch(0.06 * 4 * (hits.length / tokens.length), {
+                        field: 'trigger',
+                        match: 'token-overlap',
+                        value: trigger,
+                        matched_tokens: hits,
+                        query_token_coverage: hits.length / tokens.length,
+                    });
+                }
+            }
+        }
+    }
+    // Capability description (2x weight) — full phrase first, then tokens
+    if (capabilityLower) {
+        if (capabilityLower.includes(lower)) {
+            addMatch(0.2 * 2, {
+                field: 'capability',
+                match: 'contained-phrase',
+                value: entry.capability,
+            });
+        }
+        else if (useMultiToken) {
+            const hits = tokens.filter(t => capabilityLower.includes(t));
+            if (overlapOK(hits.length)) {
+                addMatch(0.1 * 2 * (hits.length / tokens.length), {
+                    field: 'capability',
+                    match: 'token-overlap',
+                    value: entry.capability,
+                    matched_tokens: hits,
+                    query_token_coverage: hits.length / tokens.length,
+                });
+            }
+        }
+    }
+    // Title (3x weight)
+    if (titleLower.includes(lower)) {
+        addMatch(0.3 * 3, {
+            field: 'title',
+            match: titleLower === lower ? 'exact' : 'contained-phrase',
+            value: entry.title,
+        });
+        if (titleLower === lower) {
+            addMatch(0.2, { field: 'title', match: 'exact', value: entry.title });
+        }
+    }
+    else if (useMultiToken) {
+        const hits = tokens.filter(t => titleLower.includes(t));
+        if (overlapOK(hits.length)) {
+            addMatch(0.08 * 3 * (hits.length / tokens.length), {
+                field: 'title',
+                match: 'token-overlap',
+                value: entry.title,
+                matched_tokens: hits,
+                query_token_coverage: hits.length / tokens.length,
+            });
+        }
+    }
+    // Tags (2x weight)
+    for (const tag of tagsLower) {
+        if (tag.includes(lower)) {
+            addMatch(0.2 * 2, { field: 'tag', match: 'contained-phrase', value: tag });
+        }
+        else if (useMultiToken) {
+            const hits = tokens.filter(t => tag.includes(t));
+            if (overlapOK(hits.length)) {
+                addMatch(0.05 * 2 * (hits.length / tokens.length), {
+                    field: 'tag',
+                    match: 'token-overlap',
+                    value: tag,
+                    matched_tokens: hits,
+                    query_token_coverage: hits.length / tokens.length,
+                });
+            }
+        }
+    }
+    // Structure-aware language terms (1.5x weight). These are deliberately
+    // below declared triggers/capabilities but above generic body summaries.
+    if (searchTermsLower.includes(lower)) {
+        addMatch(0.18 * 1.5, { field: 'search_terms', match: 'contained-phrase' });
+    }
+    else if (useMultiToken) {
+        const hits = tokens.filter(t => searchTermsLower.includes(t));
+        if (overlapOK(hits.length)) {
+            addMatch(0.06 * 1.5 * (hits.length / tokens.length), {
+                field: 'search_terms',
+                match: 'token-overlap',
+                matched_tokens: hits,
+                query_token_coverage: hits.length / tokens.length,
+            });
+        }
+    }
+    // Exact declarative kind and physical source classification are compact,
+    // useful routing signals (e.g. FlowPlaybook vs OpsInventory; runbook that
+    // originated under templates/).
+    if (kindLower.includes(lower)) {
+        addMatch(0.15, { field: 'kind', match: 'contained-phrase', value: entry.kind });
+    }
+    if (sourceTypeLower.includes(lower)) {
+        addMatch(0.08, { field: 'source_type', match: 'contained-phrase', value: entry.sourceType });
+    }
+    // Summary (1x weight)
+    if (summaryLower.includes(lower)) {
+        addMatch(0.15, { field: 'summary', match: 'contained-phrase' });
+    }
+    else if (useMultiToken) {
+        const hits = tokens.filter(t => summaryLower.includes(t));
+        if (overlapOK(hits.length)) {
+            addMatch(0.04 * (hits.length / tokens.length), {
+                field: 'summary',
+                match: 'token-overlap',
+                matched_tokens: hits,
+                query_token_coverage: hits.length / tokens.length,
+            });
+        }
+    }
+    // Path (0.5x weight)
+    if (pathLower.includes(lower)) {
+        addMatch(0.1, { field: 'path', match: 'contained-phrase', value: entry.path });
+    }
+    else if (useMultiToken) {
+        const hits = tokens.filter(t => pathLower.includes(t));
+        if (overlapOK(hits.length)) {
+            addMatch(0.03 * (hits.length / tokens.length), {
+                field: 'path',
+                match: 'token-overlap',
+                value: entry.path,
+                matched_tokens: hits,
+                query_token_coverage: hits.length / tokens.length,
+            });
+        }
+    }
+    // Type (0.5x weight)
+    if (typeLower.includes(lower)) {
+        addMatch(0.1, { field: 'type', match: 'contained-phrase', value: entry.type });
+    }
+    return finish();
+}
+function scoreEntry(entry, text, opts = {}) {
+    return scoreEntryDetailed(entry, text, opts).score;
+}
+/**
+ * Query the artifact index
+ */
+export async function queryIndex(cwd, params, options = {}) {
+    const { graph } = options;
+    const backend = options.backend ?? DEFAULT_ARTIFACT_SEARCH_BACKEND;
+    const startTime = Date.now();
+    let candidates;
+    if (backend === 'fortemi-core') {
+        const { loadFortemiCoreMetadataEntries } = await import('./fortemi-core-query-adapter.js');
+        const loaded = loadFortemiCoreMetadataEntries(cwd, graph ?? 'project');
+        if (loaded.reason) {
+            if (options.json) {
+                console.log(JSON.stringify({
+                    query: { text: params.text, backend: 'fortemi-core', graph: graph ?? 'project' },
+                    results: [],
+                    total: 0,
+                    hint: loaded.reason ?? 'Fortemi Core static index is unavailable.',
+                }, null, 2));
+            }
+            else {
+                console.error('Error: ' + (loaded.reason ?? 'Fortemi Core static index is unavailable.'));
+            }
+            process.exit(1);
+        }
+        candidates = loaded.entries;
+    }
+    else if (graph) {
+        // Single graph mode
+        const index = loadGraphIndexFile(cwd, 'metadata.json', graph);
+        if (!index) {
+            console.error(`Error: No artifact index found for graph '${graph}'.`);
+            console.log("Run 'aiwg index build' first to create the index.");
+            process.exit(1);
+        }
+        candidates = Object.values(index.entries);
+    }
+    else {
+        // No graph specified: search across all project-local graphs
+        const graphTypes = ['project', 'codebase'];
+        const allEntries = [];
+        for (const g of graphTypes) {
+            const idx = loadGraphIndexFile(cwd, 'metadata.json', g);
+            if (idx)
+                allEntries.push(...Object.values(idx.entries));
+        }
+        // Fall back to legacy root index
+        if (allEntries.length === 0) {
+            const legacy = loadMetadataIndex(cwd);
+            if (!legacy) {
+                console.error('Error: No artifact index found.');
+                console.log("Run 'aiwg index build' first to create the index.");
+                process.exit(1);
+            }
+            allEntries.push(...Object.values(legacy.entries));
+        }
+        candidates = allEntries;
+    }
+    // Apply filters
+    if (params.type) {
+        candidates = candidates.filter(e => e.type === params.type);
+    }
+    if (params.phase) {
+        candidates = candidates.filter(e => e.phase === params.phase);
+    }
+    if (params.tags && params.tags.length > 0) {
+        candidates = candidates.filter(e => params.tags.every(tag => e.tags.includes(tag)));
+    }
+    if (params.path) {
+        candidates = candidates.filter(e => minimatch(e.path, params.path));
+    }
+    if (params.updatedAfter) {
+        const cutoff = new Date(params.updatedAfter).getTime();
+        candidates = candidates.filter(e => new Date(e.updated).getTime() >= cutoff);
+    }
+    // Score and rank
+    let results;
+    const matchedById = new Map();
+    const operationalStateById = new Map();
+    if (params.text && params.fulltext && backend === 'fortemi-core') {
+        const { queryFortemiCoreStaticFulltextIndex } = await import('./fortemi-core-query-adapter.js');
+        const queried = queryFortemiCoreStaticFulltextIndex(cwd, {
+            graph: graph ?? 'project',
+            text: params.text,
+            limit: params.limit ?? 20,
+            path: params.path,
+            type: params.type,
+            phase: params.phase,
+            tags: params.tags,
+        });
+        if (queried.reason) {
+            if (options.json) {
+                console.log(JSON.stringify({
+                    query: { text: params.text, backend: 'fortemi-core', graph: graph ?? 'project' },
+                    mode: 'fulltext',
+                    results: [],
+                    total: 0,
+                    hint: queried.reason,
+                }, null, 2));
+            }
+            else {
+                console.error('Error: ' + queried.reason);
+            }
+            process.exit(1);
+        }
+        results = queried.results.map(result => {
+            const entry = {
+                path: result.path,
+                type: result.type,
+                phase: result.phase,
+                title: result.title,
+                tags: result.tags,
+                created: '',
+                updated: '',
+                checksum: '',
+                summary: result.summary,
+                dependencies: [],
+                dependents: [],
+            };
+            matchedById.set(result.path, result.matched);
+            if (result.operational_state) {
+                operationalStateById.set(result.path, result.operational_state);
+            }
+            return { entry, score: result.score };
+        });
+    }
+    else if (params.text && params.fulltext) {
+        // Lexical full-text (#1494): read candidate bodies and BM25-rank. The
+        // index is the candidate set; ranking is over actual body content, not
+        // the metadata/summary the default path scores.
+        const byPath = new Map();
+        const docs = [];
+        for (const entry of candidates) {
+            const body = readEntryBody(cwd, entry.path);
+            if (body === null)
+                continue;
+            byPath.set(entry.path, entry);
+            docs.push({ id: entry.path, text: body });
+        }
+        const hits = bm25Rank(docs, params.text);
+        results = hits
+            .map(h => {
+            matchedById.set(h.id, h.matchedTerms);
+            return { entry: byPath.get(h.id), score: h.score };
+        })
+            .filter(r => r.entry);
+    }
+    else if (params.text) {
+        results = candidates
+            .map(entry => ({ entry, score: scoreEntry(entry, params.text) }))
+            .filter(r => r.score > 0)
+            .sort(compareDiscoverResults);
+    }
+    else {
+        // No keyword — return all filtered results with score 1.0
+        results = candidates.map(entry => ({ entry, score: 1.0 }));
+    }
+    // Apply limit
+    const limit = params.limit ?? 20;
+    results = results.slice(0, limit);
+    const queryTimeMs = Date.now() - startTime;
+    // Output
+    if (options.json) {
+        console.log(JSON.stringify({
+            query: { text: params.text, filters: { type: params.type, phase: params.phase, tags: params.tags, path: params.path }, backend },
+            mode: params.fulltext ? 'fulltext' : 'metadata',
+            results: results.map(r => ({
+                path: r.entry.path,
+                type: r.entry.type,
+                phase: r.entry.phase,
+                title: r.entry.title,
+                score: Math.round(r.score * 100) / 100,
+                summary: r.entry.summary,
+                ...(operationalStateById.has(r.entry.path)
+                    ? { operational_state: operationalStateById.get(r.entry.path) }
+                    : r.entry.operationalState
+                        ? { operational_state: operationalStateQueryProjection(r.entry.operationalState) }
+                        : {}),
+                ...(params.fulltext ? { matched: matchedById.get(r.entry.path) ?? [] } : {}),
+            })),
+            total: results.length,
+            query_time_ms: queryTimeMs,
+        }, null, 2));
+    }
+    else {
+        const queryDesc = params.text ? `"${params.text}"` : 'all';
+        console.log(`Results for ${queryDesc} (${results.length} matches, ${queryTimeMs}ms):`);
+        console.log('');
+        console.log('  #  Score  Type         Phase          Path');
+        for (let i = 0; i < results.length; i++) {
+            const r = results[i];
+            const num = String(i + 1).padStart(3);
+            const score = r.score.toFixed(2).padStart(4);
+            const type = r.entry.type.padEnd(12).slice(0, 12);
+            const phase = r.entry.phase.padEnd(14).slice(0, 14);
+            console.log(`  ${num}  ${score}  ${type} ${phase} ${r.entry.path}`);
+        }
+        if (results.length === 0) {
+            console.log('  No results found.');
+        }
+        console.log('');
+    }
+}
+const DEFAULT_DISCOVER_TYPES = [...OPERATIONAL_DISCOVERY_TYPES];
+const DEFAULT_CAPABILITY_GRAPHS = ['project', 'user', 'framework'];
+function projectAllowsUserIndices(cwd) {
+    try {
+        const configPath = projectAiwgPath(cwd, 'aiwg.config');
+        if (!fs.existsSync(configPath))
+            return true;
+        const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        const index = parsed.index;
+        const userIndices = index?.userIndices;
+        if (userIndices?.enabled === false)
+            return false;
+        const indices = parsed.indices;
+        const user = indices?.user;
+        if (user?.enabled === false)
+            return false;
+    }
+    catch {
+        return true;
+    }
+    return true;
+}
+function defaultCapabilityGraphs(cwd) {
+    if (projectAllowsUserIndices(cwd))
+        return DEFAULT_CAPABILITY_GRAPHS;
+    return DEFAULT_CAPABILITY_GRAPHS.filter((graph) => graph !== 'user' && !graph.startsWith('user-'));
+}
+/**
+ * Resolve the AIWG installation root for path-anchoring discover output.
+ * Discover returns paths anchored to AIWG_ROOT so the agent's `Read`
+ * tool can resolve them from any project working directory (#1217).
+ */
+/**
+ * Build the `run_hint` string for a script-bearing skill entry (#1227).
+ *
+ * Format: `aiwg run skill <name> [-- <argsHint>]`. The skill name is the
+ * basename of its source directory (skills/<name>/SKILL.md), which is
+ * what `aiwg run skill` accepts.
+ */
+function buildRunHint(entry) {
+    // Use the directory basename for slug-layout skills, filename stem otherwise.
+    const lastSlash = entry.path.lastIndexOf('/');
+    const tail = lastSlash >= 0 ? entry.path.slice(lastSlash + 1) : entry.path;
+    let name;
+    if (tail === 'SKILL.md' && lastSlash >= 0) {
+        const dir = entry.path.slice(0, lastSlash);
+        const dirSlash = dir.lastIndexOf('/');
+        name = dirSlash >= 0 ? dir.slice(dirSlash + 1) : dir;
+    }
+    else {
+        name = tail.replace(/\.[^.]+$/, '');
+    }
+    const argsHint = entry.script?.argsHint ? ` -- ${entry.script.argsHint}` : '';
+    return `aiwg run skill ${name}${argsHint}`;
+}
+function showHintForDiscoverResult(entry, id) {
+    if (isOperationalShowType(entry.type)) {
+        return `aiwg show ${entry.type} ${id}`;
+    }
+    return `aiwg show ${id}`;
+}
+async function getAiwgRootForDiscover() {
+    if (process.env.AIWG_ROOT)
+        return process.env.AIWG_ROOT;
+    try {
+        const mod = await import('../channel/manager.mjs');
+        if (typeof mod.getFrameworkRoot === 'function') {
+            const r = await mod.getFrameworkRoot();
+            return r || null;
+        }
+    }
+    catch {
+        // channel manager unavailable — fall through
+    }
+    return null;
+}
+export async function discoverCapability(cwd, params) {
+    loadGlobalGraphConfigs();
+    const startTime = Date.now();
+    const types = params.typeFilter && params.typeFilter.length > 0
+        ? params.typeFilter
+        : DEFAULT_DISCOVER_TYPES;
+    // Default top-K = 5 (Wave A from #1218): peer-reviewed work on tool
+    // retrieval (Semantic Tool Discovery for MCP, arXiv:2603.20313) reports
+    // 97.1% hit@K=3 at scale; K=5 keeps a buffer above K=3 while halving
+    // the prior K=10 default. Operators wanting more breadth can pass
+    // `--limit N` explicitly.
+    const limit = params.limit ?? 5;
+    // For framework-graph entries, anchor returned paths to AIWG_ROOT so
+    // they resolve from any project working directory (#1217).
+    const aiwgRoot = await getAiwgRootForDiscover();
+    // Source: prefer `framework` graph (built post-deploy), fall back to
+    // project / codebase / legacy depending on what's available.
+    let entries = [];
+    const backend = params.backend ?? DEFAULT_ARTIFACT_SEARCH_BACKEND;
+    let fortemiCoreDiscoveryScores = null;
+    let resourceSource = params.resourceSource ?? 'local';
+    let resolvedWebRelease;
+    let verifiedSourcePaths;
+    if (resourceSource === 'auto') {
+        const { loadFortemiCoreMetadataEntries } = await import('./fortemi-core-query-adapter.js');
+        const localGraphs = params.graph ? [params.graph] : defaultCapabilityGraphs(cwd);
+        const localAvailable = localGraphs.some((graph) => loadFortemiCoreMetadataEntries(cwd, graph).entries.length > 0);
+        resourceSource = localAvailable ? 'local' : 'web';
+    }
+    if (resourceSource === 'web') {
+        if (backend !== 'fortemi-core') {
+            console.error('Error: --resource-source web requires the Fortemi Core query backend; --backend local remains available with local resources.');
+            process.exit(1);
+        }
+        if (params.graph && params.graph !== 'framework') {
+            console.error("Error: web-backed capability discovery currently supports only the 'framework' graph.");
+            process.exit(1);
+        }
+        try {
+            const { resolveWebRelease } = await import('../resources/web-release.js');
+            const release = await resolveWebRelease({
+                ...params.webReleaseOptions,
+                selector: params.aiwgVersion ?? 'stable',
+                offline: params.offline,
+            });
+            resolvedWebRelease = release;
+            verifiedSourcePaths = {
+                manifestPath: release.fortemiManifestPath,
+                exportPath: release.fortemiExportPath,
+                manifestSha256: release.fortemiManifestSha256,
+                manifestSize: release.fortemiManifestSize,
+                exportSha256: release.fortemiExportSha256,
+                exportSize: release.fortemiExportSize,
+            };
+        }
+        catch (error) {
+            console.error(`Error: AIWG web resource resolution failed: ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
+    }
+    if (backend === 'fortemi-core') {
+        const graphs = resourceSource === 'web'
+            ? ['framework']
+            : params.graph ? [params.graph] : defaultCapabilityGraphs(cwd);
+        const { loadFortemiCoreMetadataEntries, queryFortemiCoreAiwgDiscovery, } = await import('./fortemi-core-query-adapter.js');
+        let unavailableReason;
+        for (const graph of graphs) {
+            const loaded = loadFortemiCoreMetadataEntries(cwd, graph, verifiedSourcePaths);
+            if (loaded.reason)
+                unavailableReason ??= loaded.reason;
+            entries.push(...loaded.entries.map((entry) => withIndexProvenance(entry, graph)));
+            const discovered = await queryFortemiCoreAiwgDiscovery(cwd, {
+                graph,
+                text: params.phrase,
+                limit: Math.max(limit * 10, 50),
+                types,
+                sourcePaths: verifiedSourcePaths,
+            });
+            if (!discovered.reason) {
+                fortemiCoreDiscoveryScores ??= new Map();
+                for (const result of discovered.results) {
+                    if (result.score <= 0)
+                        continue;
+                    fortemiCoreDiscoveryScores.set(result.entry.path, Math.max(fortemiCoreDiscoveryScores.get(result.entry.path) ?? 0, result.score));
+                }
+            }
+        }
+        if (entries.length === 0 && unavailableReason) {
+            if (params.json) {
+                console.log(JSON.stringify({
+                    query: {
+                        phrase: params.phrase,
+                        types,
+                        limit,
+                        backend: 'fortemi-core',
+                        graph: resourceSource === 'web' ? 'framework' : params.graph ?? 'capability-default',
+                        ...(resourceSource === 'web'
+                            ? {
+                                resource_source: 'web',
+                                aiwg_selector: resolvedWebRelease?.selector,
+                                aiwg_version: resolvedWebRelease?.version,
+                                manifest_sha256: resolvedWebRelease?.manifestDigest,
+                                manifest_url: resolvedWebRelease?.manifestUrl,
+                            }
+                            : {}),
+                    },
+                    results: [],
+                    total: 0,
+                    hint: unavailableReason,
+                }, null, 2));
+            }
+            else {
+                console.error('Error: ' + unavailableReason);
+            }
+            process.exit(1);
+        }
+    }
+    else if (params.graph) {
+        const idx = loadGraphIndexFile(cwd, 'metadata.json', params.graph);
+        if (idx)
+            entries = Object.values(idx.entries).map((entry) => withIndexProvenance(entry, params.graph));
+    }
+    else {
+        // discover is EXCLUSIVELY the agentic-capability surface (#1545): source
+        // the `framework` graph (deployed AIWG capabilities) + project-local
+        // capability artifacts. NEVER `codebase` — source code is not a capability
+        // surface. discover leverages indexing transparently: if the framework
+        // index is missing but its source is present, build it once (incremental
+        // thereafter) so discover Just Works without the operator picking a graph.
+        let fwIdx = loadGraphIndexFile(cwd, 'metadata.json', 'framework');
+        if (!fwIdx) {
+            // The framework graph is shared (XDG) and `defaultBuild: false`, so a bare
+            // `aiwg index build` never (re)builds it — only `aiwg use` or an explicit
+            // `--graph framework` does. When it's absent, build it from wherever the
+            // AIWG source lives: `cwd/agentic/code` when inside the AIWG repo, else
+            // `$AIWG_ROOT/agentic/code` for a USER project (#1541 — opencode users sit
+            // in their own project, not the AIWG repo, so a cwd-only check left
+            // discover unable to find deployed commands like address-issues). buildIndex
+            // scans <root>/agentic/code and writes to the cwd-independent XDG dir, so
+            // reading back via cwd still resolves the freshly-built shared index.
+            const buildRoot = fs.existsSync(path.join(cwd, 'agentic', 'code'))
+                ? cwd
+                : aiwgRoot && fs.existsSync(path.join(aiwgRoot, 'agentic', 'code'))
+                    ? aiwgRoot
+                    : null;
+            if (buildRoot) {
+                const { buildIndex } = await import('./index-builder.js');
+                if (!params.json)
+                    console.error('Building capability index (first run)…');
+                // buildIndex writes progress to stdout. In --json mode that would corrupt
+                // the JSON envelope the caller parses, so silence stdout for the duration
+                // of the auto-build (the build is incidental to the query).
+                const origLog = console.log;
+                if (params.json)
+                    console.log = () => { };
+                try {
+                    await buildIndex(buildRoot, { graph: 'framework', explicit: false });
+                }
+                catch {
+                    /* non-fatal — fall through to whatever index is available */
+                }
+                finally {
+                    console.log = origLog;
+                }
+                fwIdx = loadGraphIndexFile(cwd, 'metadata.json', 'framework');
+            }
+        }
+        const includeUser = projectAllowsUserIndices(cwd);
+        // Project-local operational artifacts authored in this project. The
+        // DEFAULT_DISCOVER_TYPES filter keeps non-capability project artifacts
+        // (requirements, ADRs, …) out of results.
+        const projIdx = loadGraphIndexFile(cwd, 'metadata.json', 'project');
+        if (projIdx)
+            entries.push(...Object.values(projIdx.entries).map((entry) => withIndexProvenance(entry, 'project')));
+        if (includeUser) {
+            const userIdx = loadGraphIndexFile(cwd, 'metadata.json', 'user');
+            if (userIdx)
+                entries.push(...Object.values(userIdx.entries).map((entry) => withIndexProvenance(entry, 'user')));
+        }
+        if (fwIdx)
+            entries.push(...Object.values(fwIdx.entries).map((entry) => withIndexProvenance(entry, 'framework')));
+        if (entries.length === 0) {
+            const legacy = loadMetadataIndex(cwd);
+            if (legacy)
+                entries.push(...Object.values(legacy.entries));
+        }
+    }
+    if (entries.length === 0 && backend !== 'fortemi-core') {
+        // Empty-index case (#1221). Surface a hint that explains the gap rather
+        // than returning a bare zero-result envelope — the latter trains agents
+        // to conclude "AIWG doesn't have a skill for that" when in fact the
+        // index simply hasn't been built in this workspace yet.
+        const hint = 'No artifact index found. Run `aiwg index build --graph framework` (or `aiwg use <framework>`) first.';
+        if (params.json) {
+            console.log(JSON.stringify({
+                query: { phrase: params.phrase, types },
+                results: [],
+                total: 0,
+                hint,
+            }, null, 2));
+        }
+        else {
+            console.error('Error: No artifact index found.');
+            console.log('Run `aiwg index build --graph framework` (or `aiwg use <framework>`) first.');
+        }
+        process.exit(1);
+    }
+    // Filter by type
+    const candidates = entries.filter(e => types.includes(e.type));
+    // Score (strict overlap gate). Keep the full sorted list so the facet
+    // fusion below can inject/lift curated capabilities into the top-K before
+    // truncation — a capability that the lexical pass ranked outside `limit`
+    // (or missed entirely) still surfaces when the query activates its facet.
+    const lexicalDiagnostics = new Map();
+    const legacyStrictScored = candidates
+        .map(entry => {
+        const detailed = scoreEntryDetailed(entry, params.phrase);
+        const legacyScore = detailed.score;
+        const fortemiScore = fortemiCoreDiscoveryScores?.get(entry.path) ?? 0;
+        lexicalDiagnostics.set(entry.path, detailed.diagnostic);
+        return {
+            entry,
+            score: legacyScore > 0 ? legacyScore : fortemiScore * 0.2,
+            legacyScore,
+        };
+    })
+        .filter(r => r.score > 0)
+        .sort(compareDiscoverResults);
+    const strictScored = (legacyStrictScored.some(result => result.legacyScore > 0)
+        ? legacyStrictScored.filter(result => result.legacyScore > 0)
+        : legacyStrictScored).map(({ entry, score }) => ({ entry, score }));
+    // Single-pass facet fusion (#1623 U3): fuse the curated feature→capability
+    // facets (expansion / persona / project / provider-capability) into the
+    // lexical ranking so canonical domain phrases rank their owning capability
+    // top-K instead of being out-scored by artifacts that merely mention the
+    // word. Facet activation can also rescue an otherwise-empty strict pass.
+    let scored = dedupeDiscoverResults(await applyFacetFusion(strictScored, candidates, params.phrase)).slice(0, limit);
+    // #1561 — verbose-query fallback. A wordy full-sentence query
+    // ("find me a skill that handles intake forms") dilutes the token hit ratio
+    // below the strict ceil(n/2) overlap gate and returns nothing, training
+    // agents to conclude "no skill exists" — the exact decline-without-search
+    // failure the skill-discovery rule guards against. When the strict pass
+    // dead-ends, re-score with a relaxed (single-hit) overlap so the meaningful
+    // tokens still surface ranked candidates rather than an empty set.
+    let relaxed = false;
+    if (scored.length === 0) {
+        // Floor the relaxed pass so a single incidental path/summary token hit
+        // (~0.006–0.008) doesn't surface as noise. Capability/title/trigger field
+        // hits land ~0.04+, so this keeps meaningful matches while dropping junk —
+        // if nothing clears the floor, we fall through to the no-match hint, which
+        // is more honest than surfacing a 0.01 path match.
+        const RELAXED_MIN_SCORE = 0.02;
+        const relaxedFull = candidates
+            .map(entry => {
+            const detailed = scoreEntryDetailed(entry, params.phrase, { relaxOverlap: true });
+            lexicalDiagnostics.set(entry.path, detailed.diagnostic);
+            return { entry, score: detailed.score };
+        })
+            .filter(r => r.score >= RELAXED_MIN_SCORE)
+            .sort(compareDiscoverResults);
+        const relaxedScored = dedupeDiscoverResults(await applyFacetFusion(relaxedFull, candidates, params.phrase)).slice(0, limit);
+        if (relaxedScored.length > 0) {
+            scored = relaxedScored;
+            relaxed = true;
+        }
+    }
+    const queryTimeMs = Date.now() - startTime;
+    /**
+     * Resolve a stored framework-graph path to an absolute AIWG_ROOT
+     * path (#1217). Framework-graph entries are stored as paths relative
+     * to the AIWG repo root (e.g. `agentic/code/frameworks/.../SKILL.md`);
+     * anchoring them to `AIWG_ROOT` makes them readable from any project
+     * working directory.
+     *
+     * Kernel skills are anchored the same way (#1230) — `aiwg show` reads
+     * the source corpus, not platform deploy mirrors, so kernel entries
+     * need the same `AIWG_ROOT` anchoring as non-kernel framework entries.
+     * Non-framework entries (project / codebase graphs) keep their stored
+     * paths unchanged.
+     */
+    function resolvePath(entry) {
+        const normalizedPath = normalizeIndexedPath(entry.path);
+        if (!aiwgRoot)
+            return normalizedPath;
+        if (path.isAbsolute(entry.path))
+            return entry.path;
+        if (normalizedPath.startsWith('agentic/code/'))
+            return path.join(aiwgRoot, normalizedPath);
+        return normalizedPath;
+    }
+    // Build a hint string when the index has entries but no scored matches —
+    // this is the second silent-failure mode #1221 calls out. When the workspace
+    // has project-local content (.aiwg/{extensions,addons,frameworks,plugins,providers}/)
+    // surface a project-graph rebuild hint (#1235).
+    // discover-appropriate hint (#1545): never push index/graph mechanics. If
+    // nothing scored, the phrase didn't match an indexed capability — suggest a
+    // broader phrase / type filter, and a capability refresh via `aiwg use`.
+    const emptyResultHint = scored.length === 0
+        ? backend === 'fortemi-core'
+            ? `No capability matched "${params.phrase}" among ${entries.length} Fortemi Core static-cache capabilities. Try a broader phrase or a \`--type\` filter. If the local index changed, refresh the cache with \`aiwg index sync\`, or pass \`--backend local\` to use the legacy local index.`
+            : `No capability matched "${params.phrase}" among ${entries.length} indexed capabilities. Try a broader phrase or a \`--type\` filter. If you just installed or authored capabilities, refresh discovery with \`aiwg use <framework>\` (or \`aiwg index build\`).`
+        : null;
+    const includePaths = params.includePaths ?? true;
+    const facetActivations = diagnoseFacetActivations(params.phrase);
+    const roundDiagnostic = (value) => Math.round(value * 1_000_000) / 1_000_000;
+    const rankingDiagnostic = (entry, finalScore, facetDiagnostics) => {
+        const lexical = lexicalDiagnostics.get(entry.path) ?? {
+            content_tokens: tokenize(params.phrase),
+            raw_score: 0,
+            score: 0,
+            score_cap_applied: false,
+            matches: [],
+        };
+        const scope = entry.indexScope ?? 'unknown';
+        return {
+            lexical_score: roundDiagnostic(lexical.score),
+            lexical_raw_score: roundDiagnostic(lexical.raw_score),
+            final_score: roundDiagnostic(finalScore),
+            score_cap_applied: lexical.score_cap_applied,
+            matches: lexical.matches.map((match) => ({
+                ...match,
+                contribution: roundDiagnostic(match.contribution),
+                ...(match.query_token_coverage === undefined
+                    ? {}
+                    : { query_token_coverage: roundDiagnostic(match.query_token_coverage) }),
+            })),
+            facets: (facetDiagnostics ?? []).map((facet) => ({
+                ...facet,
+                activation_floor: roundDiagnostic(facet.activation_floor),
+                base_score: roundDiagnostic(facet.base_score),
+                rrf_tiebreak: roundDiagnostic(facet.rrf_tiebreak),
+            })),
+            tie_breakers: {
+                scope,
+                scope_rank: scopeRank(entry),
+                type_rank: DISCOVER_TYPE_ORDER.get(entry.type) ?? 99,
+            },
+        };
+    };
+    if (params.json) {
+        const jsonIndent = params.jsonPretty === false ? undefined : 2;
+        console.log(JSON.stringify({
+            query: {
+                phrase: params.phrase,
+                types,
+                limit,
+                aiwg_root: aiwgRoot ?? null,
+                backend,
+                graph: backend === 'fortemi-core'
+                    ? resourceSource === 'web' ? 'framework' : params.graph ?? 'capability-default'
+                    : params.graph,
+                ...(resourceSource === 'web'
+                    ? {
+                        resource_source: 'web',
+                        aiwg_selector: resolvedWebRelease?.selector,
+                        aiwg_version: resolvedWebRelease?.version,
+                        manifest_sha256: resolvedWebRelease?.manifestDigest,
+                        manifest_url: resolvedWebRelease?.manifestUrl,
+                    }
+                    : {}),
+            },
+            results: scored.map(r => ({
+                id: discoveryIdForEntry(r.entry),
+                ...(includePaths ? { path: resolvePath(r.entry) } : {}),
+                type: r.entry.type,
+                name: r.entry.name,
+                title: r.entry.title,
+                score: Math.round(r.score * 100) / 100,
+                ranking: rankingDiagnostic(r.entry, r.score, r.facetDiagnostics),
+                triggers: r.entry.triggers ?? [],
+                capability: r.entry.capability ?? r.entry.summary,
+                kernel: r.entry.kernel ?? false,
+                provenance: {
+                    graph: r.entry.indexGraph ?? null,
+                    scope: r.entry.indexScope ?? null,
+                },
+                // #1227 — surface script-bearing skills so agents know to use
+                // `aiwg run skill <name>` instead of executing instructions
+                // themselves.
+                ...(r.entry.script
+                    ? {
+                        executable: true,
+                        run_hint: buildRunHint(r.entry),
+                    }
+                    : {}),
+            })),
+            total: scored.length,
+            query_time_ms: queryTimeMs,
+            diagnostics: {
+                content_tokens: tokenize(params.phrase),
+                facet_activations: facetActivations,
+                score_tie_break_order: ['score', 'scope', 'type', 'name', 'path'],
+            },
+            ...(relaxed ? { relaxed_overlap: true } : {}),
+            ...(emptyResultHint ? { hint: emptyResultHint } : {}),
+        }, null, jsonIndent));
+        return;
+    }
+    if (scored.length === 0) {
+        console.log(`No discovery matches for "${params.phrase}" in types: ${types.join(',')}.`);
+        console.log('Try a broader phrase or a `--type` filter. If capabilities were just added, refresh with `aiwg use <framework>` (or `aiwg index build`).');
+        return;
+    }
+    const relaxedNote = relaxed ? ' — relaxed match (verbose query)' : '';
+    console.log(`Discovery results for "${params.phrase}" (${scored.length} matches, ${queryTimeMs}ms)${relaxedNote}:`);
+    console.log('');
+    for (const diagnostic of facetActivations) {
+        if (diagnostic.status === 'suppressed' && diagnostic.reason) {
+            console.log(`Routing diagnostic: ${diagnostic.reason}.`);
+            console.log('');
+        }
+    }
+    for (let i = 0; i < scored.length; i++) {
+        const r = scored[i];
+        const ranking = rankingDiagnostic(r.entry, r.score, r.facetDiagnostics);
+        const id = discoveryIdForEntry(r.entry);
+        const score = r.score.toFixed(2);
+        const flags = [
+            r.entry.kernel ? 'kernel' : null,
+            r.entry.script ? 'exec' : null,
+        ].filter(Boolean).join(', ');
+        const locator = includePaths ? resolvePath(r.entry) : id;
+        const topTriggerMatch = ranking.matches
+            .filter((match) => match.field === 'trigger')
+            .reduce((best, match) => !best || match.contribution > best.contribution ? match : best, undefined);
+        const topTrigger = topTriggerMatch?.value ??
+            (r.entry.triggers && r.entry.triggers.length > 0 ? r.entry.triggers[0] : '');
+        console.log(`${i + 1}. ${r.entry.title}`);
+        console.log(`   type: ${r.entry.type}  score: ${score}${flags ? `  flags: ${flags}` : ''}`);
+        console.log(`   ${includePaths ? 'path' : 'id'}: ${locator}`);
+        if (r.entry.name) {
+            console.log(`   name: ${r.entry.name}`);
+        }
+        if (r.entry.capability) {
+            console.log(`   capability: ${r.entry.capability}`);
+        }
+        if (topTrigger) {
+            console.log(`   trigger: "${topTrigger}"`);
+        }
+        const triggerCoverage = topTriggerMatch?.query_token_coverage;
+        const rankingParts = [
+            `lexical ${ranking.lexical_score.toFixed(4)} -> final ${ranking.final_score.toFixed(4)}`,
+            triggerCoverage === undefined
+                ? null
+                : `trigger covers ${Math.round(triggerCoverage * 100)}% of query tokens`,
+            `scope ${ranking.tie_breakers.scope}`,
+        ].filter((part) => Boolean(part));
+        console.log(`   ranking: ${rankingParts.join('; ')}`);
+        if (r.entry.script) {
+            console.log(`   run: ${buildRunHint(r.entry)}`);
+        }
+        else if (!includePaths) {
+            console.log(`   show: ${showHintForDiscoverResult(r.entry, id)}`);
+        }
+        console.log('');
+    }
+    console.log('Use `--format json` for machine-readable output. Use `aiwg show metadata <id>` for paths and full metadata.');
+}
+function resolveMetadataPath(cwd, aiwgRoot, entry) {
+    if (path.isAbsolute(entry.path))
+        return entry.path;
+    const normalizedPath = normalizeIndexedPath(entry.path);
+    if (aiwgRoot && normalizedPath.startsWith('agentic/code/')) {
+        return path.join(aiwgRoot, normalizedPath);
+    }
+    if (entry.indexScope === 'user' && normalizedPath.startsWith('~/.aiwg/')) {
+        return path.join(process.env.HOME ?? '', normalizedPath.slice(2));
+    }
+    if (normalizedPath.startsWith('.aiwg/')) {
+        return projectAiwgPath(cwd, normalizedPath.slice('.aiwg/'.length));
+    }
+    return path.join(cwd, normalizedPath);
+}
+async function loadShowEntries(cwd, params) {
+    const aiwgRoot = await getAiwgRootForDiscover();
+    const backend = params.backend ?? DEFAULT_ARTIFACT_SEARCH_BACKEND;
+    let resourceSource = params.resourceSource ?? 'local';
+    let entries = [];
+    if (resourceSource === 'auto' && backend === 'fortemi-core') {
+        const { loadFortemiCoreMetadataEntries } = await import('./fortemi-core-query-adapter.js');
+        const localGraphs = params.graph ? [params.graph] : defaultCapabilityGraphs(cwd);
+        resourceSource = localGraphs.some((graph) => loadFortemiCoreMetadataEntries(cwd, graph).entries.length > 0) ? 'local' : 'web';
+    }
+    else if (resourceSource === 'auto') {
+        resourceSource = 'local';
+    }
+    if (resourceSource === 'web') {
+        if (backend !== 'fortemi-core') {
+            console.error('Error: --resource-source web requires the Fortemi Core query backend; --backend local remains available with local resources.');
+            process.exit(1);
+        }
+        if (params.graph && params.graph !== 'framework') {
+            console.error("Error: web-backed show currently supports only the 'framework' graph.");
+            process.exit(1);
+        }
+        try {
+            const { resolveWebRelease } = await import('../resources/web-release.js');
+            const webRelease = await resolveWebRelease({
+                ...params.webReleaseOptions,
+                selector: params.aiwgVersion ?? 'stable',
+                offline: params.offline,
+            });
+            const sourcePaths = {
+                manifestPath: webRelease.fortemiManifestPath,
+                exportPath: webRelease.fortemiExportPath,
+                manifestSha256: webRelease.fortemiManifestSha256,
+                manifestSize: webRelease.fortemiManifestSize,
+                exportSha256: webRelease.fortemiExportSha256,
+                exportSize: webRelease.fortemiExportSize,
+            };
+            const { loadFortemiCoreMetadataEntries } = await import('./fortemi-core-query-adapter.js');
+            const loaded = loadFortemiCoreMetadataEntries(cwd, 'framework', sourcePaths);
+            if (loaded.reason)
+                throw new Error(loaded.reason);
+            entries = loaded.entries.map((entry) => withIndexProvenance(entry, 'framework'));
+            return { entries, aiwgRoot, resourceSource: 'web', webRelease, sourcePaths };
+        }
+        catch (error) {
+            console.error(`Error: AIWG web resource resolution failed: ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
+    }
+    // Preserve the direct API's historical local-index behavior when callers
+    // omit `backend`. The CLI always passes its explicit Fortemi default, while
+    // an explicit `auto` source also opts into Fortemi-backed availability.
+    if (params.backend === 'fortemi-core' || params.resourceSource === 'auto') {
+        const { loadFortemiCoreMetadataEntries } = await import('./fortemi-core-query-adapter.js');
+        const graphs = params.graph ? [params.graph] : defaultCapabilityGraphs(cwd);
+        let unavailableReason;
+        for (const graph of graphs) {
+            const loaded = loadFortemiCoreMetadataEntries(cwd, graph);
+            if (loaded.reason)
+                unavailableReason ??= loaded.reason;
+            entries.push(...loaded.entries.map((entry) => withIndexProvenance(entry, graph)));
+        }
+        if (entries.length === 0 && unavailableReason) {
+            if (params.json) {
+                console.log(JSON.stringify({
+                    backend: 'fortemi-core',
+                    name: params.name,
+                    error: unavailableReason,
+                }, null, 2));
+            }
+            else {
+                console.error('Error: ' + unavailableReason);
+            }
+            process.exit(1);
+        }
+    }
+    else if (params.graph) {
+        const idx = loadGraphIndexFile(cwd, 'metadata.json', params.graph);
+        if (idx)
+            entries = Object.values(idx.entries).map((entry) => withIndexProvenance(entry, params.graph));
+    }
+    else {
+        for (const g of defaultCapabilityGraphs(cwd)) {
+            const idx = loadGraphIndexFile(cwd, 'metadata.json', g);
+            if (idx)
+                entries.push(...Object.values(idx.entries).map((entry) => withIndexProvenance(entry, g)));
+        }
+        if (entries.length === 0) {
+            const legacy = loadMetadataIndex(cwd);
+            if (legacy)
+                entries.push(...Object.values(legacy.entries));
+        }
+    }
+    return { entries, aiwgRoot, resourceSource: 'local' };
+}
+function findShowMatches(entries, types, needle) {
+    const needleLower = needle.toLowerCase();
+    const normalizedNeedle = normalizeIndexedPath(needle);
+    const candidates = entries.filter(e => types.includes(e.type));
+    let matches = candidates.filter(e => discoveryIdForEntry(e) === needle);
+    if (matches.length === 0) {
+        matches = candidates.filter(e => e.path === needle || normalizeIndexedPath(e.path) === normalizedNeedle);
+    }
+    if (matches.length === 0) {
+        matches = candidates.filter(e => {
+            const normalizedPath = normalizeIndexedPath(e.path);
+            const dirStem = path.basename(path.dirname(normalizedPath));
+            const basename = path.basename(normalizedPath);
+            const fileStem = basename.replace(/\.[^.]+$/, '');
+            const slugLayoutMatch = ((basename === 'SKILL.md' && e.type === 'skill') ||
+                (basename === 'BEHAVIOR.md' && e.type === 'behavior')) &&
+                dirStem === needle;
+            return slugLayoutMatch || fileStem === needle || e.name === needle;
+        });
+    }
+    if (matches.length === 0) {
+        matches = candidates.filter(e => typeof e.title === 'string' && e.title.toLowerCase() === needleLower);
+    }
+    matches = uniqueEntriesByPath(matches);
+    matches = matches.sort((a, b) => scopeRank(a) - scopeRank(b) || a.path.localeCompare(b.path));
+    if (matches.length > 1) {
+        const sameIdentity = matches.every((entry) => entry.type === matches[0].type &&
+            (entry.name ?? '').toLowerCase() === (matches[0].name ?? '').toLowerCase());
+        if (sameIdentity && scopeRank(matches[0]) < scopeRank(matches[1])) {
+            matches = [matches[0]];
+        }
+    }
+    if (matches.length > 1 && types.includes('skill')) {
+        const frameworkSkillMatches = matches.filter(e => isFrameworkSourceSkillPath(e.path));
+        if (frameworkSkillMatches.length === 1)
+            matches = frameworkSkillMatches;
+    }
+    if (matches.length > 1 && types.includes('skill')) {
+        const sourceSkillMatches = matches.filter(e => isCanonicalSourceSkillPath(e.path));
+        if (sourceSkillMatches.length === 1)
+            matches = sourceSkillMatches;
+    }
+    if (matches.length > 1 && types.includes('agent')) {
+        const canonicalSourceMatches = matches.filter(e => isCanonicalSourceAgentPath(e.path));
+        if (canonicalSourceMatches.length === 1)
+            matches = canonicalSourceMatches;
+    }
+    if (matches.length > 1 && types.includes('agent')) {
+        const canonicalBundleMatches = matches.filter(e => isCanonicalBundleAgentPath(e.path));
+        const canonicalBundlePaths = uniqueEntriesByPath(canonicalBundleMatches);
+        if (canonicalBundlePaths.length === 1)
+            matches = canonicalBundlePaths;
+    }
+    if (matches.length > 1 && types.includes('agent')) {
+        const nonPersonaMatches = matches.filter(e => !isTopLevelPersonaAgentPath(e.path));
+        if (nonPersonaMatches.length === 1)
+            matches = nonPersonaMatches;
+    }
+    return matches;
+}
+async function fortemiRecordForEntry(cwd, entry, sourcePaths) {
+    const graph = (entry.indexGraph ?? 'project');
+    const { loadFortemiCoreExport } = await import('./fortemi-core-query-adapter.js');
+    const loaded = loadFortemiCoreExport(cwd, graph, sourcePaths);
+    if (!loaded.exported)
+        return null;
+    const id = discoveryIdForEntry(entry);
+    return loaded.exported.items.find((record) => record.id === id || record.source.path === entry.path) ?? null;
+}
+/**
+ * Scan the AIWG_ROOT corpus for an artifact matching `name` (#1221).
+ *
+ * Walks the well-known artifact layouts under
+ * `agentic/code/{frameworks,addons,extensions,plugins}/<bundle>/{skills,agents,commands,rules,templates,behaviors,flows}/`
+ * and returns the first match. Used as a fallback in `aiwg show` when an
+ * artifact isn't in any built index — either because the workspace hasn't
+ * been deployed to yet, or because the bundle hasn't been installed.
+ *
+ * Returns the resolved absolute path plus enough metadata for the caller
+ * to surface a useful install hint. Returns null if nothing matches.
+ */
+async function findCorpusArtifact(aiwgRoot, name, typeFilter) {
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const fsp = fs.promises;
+    const groups = [
+        { kind: 'framework', dir: path.join(aiwgRoot, 'agentic/code/frameworks') },
+        { kind: 'addon', dir: path.join(aiwgRoot, 'agentic/code/addons') },
+        { kind: 'extension', dir: path.join(aiwgRoot, 'agentic/code/extensions') },
+        { kind: 'plugin', dir: path.join(aiwgRoot, 'agentic/code/plugins') },
+    ];
+    // (subdir, type, layout) — 'flat' = `<name>.md`, 'slug' = `<name>/SKILL.md`
+    const tries = [
+        { sub: 'skills', type: 'skill', layout: 'slug' },
+        { sub: 'skills', type: 'skill', layout: 'flat' },
+        { sub: 'agents', type: 'agent', layout: 'flat' },
+        { sub: 'commands', type: 'command', layout: 'flat' },
+        { sub: 'rules', type: 'rule', layout: 'flat' },
+        { sub: 'templates', type: 'template', layout: 'flat' },
+        { sub: 'behaviors', type: 'behavior', layout: 'flat' },
+        { sub: 'flows', type: 'flow', layout: 'flat' },
+        { sub: 'runbooks', type: 'runbook', layout: 'flat' },
+    ];
+    for (const group of groups) {
+        let bundles;
+        try {
+            bundles = (await fsp.readdir(group.dir, { withFileTypes: true }))
+                .filter(d => d.isDirectory())
+                .map(d => d.name);
+        }
+        catch {
+            continue;
+        }
+        for (const bundle of bundles) {
+            for (const t of tries) {
+                if (typeFilter.length > 0 && !typeFilter.includes(t.type))
+                    continue;
+                const candidate = t.layout === 'slug'
+                    ? path.join(group.dir, bundle, t.sub, name, 'SKILL.md')
+                    : path.join(group.dir, bundle, t.sub, `${name}.md`);
+                try {
+                    const stat = await fsp.stat(candidate);
+                    if (stat.isFile()) {
+                        return { path: candidate, type: t.type, bundleKind: group.kind, bundleId: bundle };
+                    }
+                }
+                catch {
+                    // not present — continue
+                }
+            }
+        }
+    }
+    // Top-level agents live at `agentic/code/agents/<category>/<name>.md`
+    // (e.g. `personas/aiwg-writer.md`) — a flat-under-category layout the
+    // bundle groups above do not cover. Scan it directly so persona/agent
+    // `show` survives un-indexed (or stale-framework-index) workspaces, where
+    // the corpus fallback is the only resolution path. (#1623 U5)
+    if (typeFilter.length === 0 || typeFilter.includes('agent')) {
+        const agentMatch = await findAgentInCorpus(path.join(aiwgRoot, 'agentic/code/agents'), name);
+        if (agentMatch) {
+            return { path: agentMatch, type: 'agent', bundleKind: null, bundleId: null };
+        }
+    }
+    // Behaviors commonly use a slug layout: `behaviors/<name>/BEHAVIOR.md`.
+    if (typeFilter.length === 0 || typeFilter.includes('behavior')) {
+        for (const group of groups) {
+            let bundles;
+            try {
+                bundles = (await fsp.readdir(group.dir, { withFileTypes: true }))
+                    .filter(d => d.isDirectory())
+                    .map(d => d.name);
+            }
+            catch {
+                continue;
+            }
+            for (const bundle of bundles) {
+                const candidate = path.join(group.dir, bundle, 'behaviors', name, 'BEHAVIOR.md');
+                try {
+                    const stat = await fsp.stat(candidate);
+                    if (stat.isFile()) {
+                        return { path: candidate, type: 'behavior', bundleKind: group.kind, bundleId: bundle };
+                    }
+                }
+                catch {
+                    // not present — continue
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Recursively scan `agentic/code/agents` for a flat `<name>.md` agent file.
+ *
+ * Agents use an `agents/<category>/<name>.md` layout (e.g. `personas/`) that
+ * differs from the bundle `<dir>/<bundle>/<sub>/<name>.md` layout the generic
+ * corpus scan walks, so persona agents are otherwise missed. Bounded depth —
+ * the agents tree is shallow. Returns the first matching absolute path, or
+ * null. Direct files at each level take priority over subdirectories. (#1623)
+ */
+async function findAgentInCorpus(agentsRoot, name, depth = 0) {
+    if (depth > 3)
+        return null;
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const fsp = fs.promises;
+    let entries;
+    try {
+        entries = await fsp.readdir(agentsRoot, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    // Prefer a direct `<name>.md` at this level before descending.
+    for (const entry of entries) {
+        if (entry.isFile() && entry.name === `${name}.md`) {
+            return path.join(agentsRoot, entry.name);
+        }
+    }
+    // Descend into category subdirectories (e.g. personas/).
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            const found = await findAgentInCorpus(path.join(agentsRoot, entry.name), name, depth + 1);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+/**
+ * Read and emit the full text of a specific artifact (typically a
+ * SKILL.md). Consumers don't need to know where AIWG stores skills —
+ * they pass the skill name and the CLI reads the file from the indexed
+ * location.
+ *
+ * Lookup order:
+ *   1. Stable discover/Fortemi id
+ *   2. Exact path match against any indexed entry's stored path
+ *   3. Basename match (e.g. `intake-wizard` matches an entry whose
+ *      directory basename is `intake-wizard`)
+ *   4. Title match (case-insensitive)
+ *   5. Corpus fallback under AIWG_ROOT (#1221)
+ *
+ * On ambiguity, lists all matches and exits with code 2 unless
+ * `--first` is supplied.
+ */
+export async function showArtifact(cwd, params) {
+    loadGlobalGraphConfigs();
+    const { promises: fs } = await import('node:fs');
+    const types = params.typeFilter && params.typeFilter.length > 0
+        ? params.typeFilter
+        : [...OPERATIONAL_SHOW_TYPES];
+    const { entries, aiwgRoot, resourceSource, webRelease, } = await loadShowEntries(cwd, params);
+    if (entries.length === 0 && params.backend !== 'fortemi-core') {
+        console.error('Error: No artifact index found.');
+        console.error('Run `aiwg index build --graph framework` (or `aiwg use <framework>`) first.');
+        process.exit(1);
+    }
+    const needle = params.name.trim();
+    let matches = findShowMatches(entries, types, needle);
+    if (matches.length === 0) {
+        // Corpus fallback (#1221): when the artifact isn't in any indexed graph,
+        // scan the AIWG_ROOT corpus for a likely match and render it with an
+        // "(uninstalled)" banner. This keeps `aiwg show` useful in workspaces
+        // where the operator hasn't run `aiwg use` yet, or where the framework
+        // index is stale, rather than exiting with a misleading "not found".
+        if (resourceSource === 'local' && aiwgRoot && params.backend !== 'fortemi-core') {
+            const corpusMatch = await findCorpusArtifact(aiwgRoot, needle, types);
+            if (corpusMatch) {
+                let content;
+                try {
+                    content = await fs.readFile(corpusMatch.path, 'utf8');
+                }
+                catch (err) {
+                    const e = err;
+                    console.error(`Error reading ${corpusMatch.path}: ${e.message ?? String(err)}`);
+                    process.exit(1);
+                }
+                const installHint = corpusMatch.bundleKind && corpusMatch.bundleId
+                    ? `Run \`aiwg use ${corpusMatch.bundleId}\` to install this ${corpusMatch.bundleKind} into the workspace.`
+                    : 'Run `aiwg index build --graph framework` to refresh the artifact index.';
+                if (params.json) {
+                    console.log(JSON.stringify({
+                        path: corpusMatch.path,
+                        type: corpusMatch.type,
+                        title: needle,
+                        kernel: false,
+                        uninstalled: true,
+                        hint: installHint,
+                        content,
+                    }, null, 2));
+                    return;
+                }
+                // Plain text mode: prepend a banner so consumers see the artifact is
+                // corpus-only, then stream the body.
+                const banner = [
+                    '<!-- AIWG: corpus-only artifact — not in the indexed workspace.',
+                    `     ${installHint}`,
+                    '     Origin: ' + corpusMatch.path,
+                    '-->',
+                    '',
+                ].join('\n');
+                process.stdout.write(banner);
+                process.stdout.write(content);
+                if (!content.endsWith('\n'))
+                    process.stdout.write('\n');
+                return;
+            }
+        }
+        console.error(`Error: no artifact found matching "${needle}".`);
+        console.error('Try `aiwg discover "<phrase>"` to find the right name.');
+        process.exit(1);
+    }
+    // Resolve relative framework-graph paths to absolute paths.
+    // Kernel entries are anchored the same way as non-kernel framework entries
+    // (#1230) — show reads the source corpus, not platform deploy mirrors.
+    const resolvePath = (entry) => resourceSource === 'web'
+        ? `raw/${normalizeIndexedPath(entry.path)}`
+        : resolveMetadataPath(cwd, aiwgRoot, entry);
+    if (matches.length > 1 && !params.first) {
+        if (params.json) {
+            console.log(JSON.stringify({
+                ambiguous: true,
+                name: needle,
+                matches: matches.map(e => ({
+                    id: discoveryIdForEntry(e),
+                    path: resolvePath(e),
+                    type: e.type,
+                    name: e.name,
+                    title: e.title,
+                    kernel: e.kernel ?? false,
+                    provenance: {
+                        graph: e.indexGraph ?? null,
+                        scope: e.indexScope ?? null,
+                        ...(webRelease
+                            ? {
+                                resource_source: 'web',
+                                aiwg_selector: webRelease.selector,
+                                aiwg_version: webRelease.version,
+                                manifest_sha256: webRelease.manifestDigest,
+                                manifest_url: webRelease.manifestUrl,
+                            }
+                            : {}),
+                    },
+                })),
+            }, null, 2));
+        }
+        else {
+            console.error(`Ambiguous: "${needle}" matches ${matches.length} artifacts. Disambiguate with --type or pass the stable id:`);
+            for (const e of matches) {
+                console.error(`  ${e.type.padEnd(7)} ${discoveryIdForEntry(e)} ${e.title}`);
+            }
+            console.error('');
+            console.error('Re-run with `--first` to pick the top match, `--type skill` to filter, or `aiwg show metadata <id>` for paths.');
+        }
+        process.exit(2);
+    }
+    const entry = matches[0];
+    const filePath = resolvePath(entry);
+    let content;
+    if (resourceSource === 'web') {
+        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,
+                offline: params.offline,
+            });
+            content = bytes.toString('utf8');
+        }
+        catch (error) {
+            console.error(`Error: AIWG web resource show failed: ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
+    }
+    else {
+        try {
+            content = await fs.readFile(filePath, 'utf8');
+        }
+        catch (err) {
+            const e = err;
+            console.error(`Error reading ${filePath}: ${e.message ?? String(err)}`);
+            process.exit(1);
+        }
+    }
+    if (params.json) {
+        const providerModels = resourceSource === 'local'
+            ? await loadProviderModelMetadata(cwd, aiwgRoot)
+            : null;
+        console.log(JSON.stringify({
+            id: discoveryIdForEntry(entry),
+            path: filePath,
+            type: entry.type,
+            name: entry.name,
+            title: entry.title,
+            kernel: entry.kernel ?? false,
+            provenance: {
+                graph: entry.indexGraph ?? null,
+                scope: entry.indexScope ?? null,
+                ...(webRelease
+                    ? {
+                        resource_source: 'web',
+                        aiwg_selector: webRelease.selector,
+                        aiwg_version: webRelease.version,
+                        manifest_sha256: webRelease.manifestDigest,
+                        manifest_url: webRelease.manifestUrl,
+                    }
+                    : {}),
+            },
+            // #1227 — surface script-bearing skills so callers can route to
+            // `aiwg run skill <name>` instead of treating SKILL.md as
+            // instructions for the agent to execute itself.
+            ...(entry.script
+                ? { executable: true, run_hint: buildRunHint(entry) }
+                : {}),
+            ...(providerModels ? { providerModels } : {}),
+            content,
+        }, null, 2));
+        return;
+    }
+    // Plain mode: stream the file content unmodified so the consumer
+    // (agent or operator) sees exactly what the source authored.
+    // #1227 — for script-bearing skills, prepend a one-line banner so
+    // agents reading the body immediately see the skill is executable.
+    if (entry.script) {
+        const hint = buildRunHint(entry);
+        process.stdout.write(`<!-- AIWG: executable skill — run via: ${hint} -->\n`);
+    }
+    process.stdout.write(content);
+    if (!content.endsWith('\n'))
+        process.stdout.write('\n');
+}
+export async function showMetadata(cwd, params) {
+    loadGlobalGraphConfigs();
+    const types = params.typeFilter && params.typeFilter.length > 0
+        ? params.typeFilter
+        : [...OPERATIONAL_SHOW_TYPES];
+    const { entries, aiwgRoot, resourceSource, webRelease, sourcePaths, } = await loadShowEntries(cwd, params);
+    if (entries.length === 0 && params.backend !== 'fortemi-core') {
+        console.error('Error: No artifact index found.');
+        console.error('Run `aiwg index build --graph framework` (or `aiwg use <framework>`) first.');
+        process.exit(1);
+    }
+    const needle = params.name.trim();
+    const matches = findShowMatches(entries, types, needle);
+    if (matches.length === 0) {
+        console.error(`Error: no artifact metadata found matching "${needle}".`);
+        console.error('Try `aiwg discover "<phrase>" --json` to find the stable id.');
+        process.exit(1);
+    }
+    const resolvePath = (entry) => resourceSource === 'web'
+        ? `raw/${normalizeIndexedPath(entry.path)}`
+        : resolveMetadataPath(cwd, aiwgRoot, entry);
+    if (matches.length > 1 && !params.first) {
+        if (params.json) {
+            console.log(JSON.stringify({
+                ambiguous: true,
+                name: needle,
+                matches: matches.map((entry) => ({
+                    id: discoveryIdForEntry(entry),
+                    type: entry.type,
+                    name: entry.name,
+                    title: entry.title,
+                    provenance: {
+                        graph: entry.indexGraph ?? null,
+                        scope: entry.indexScope ?? null,
+                        ...(webRelease
+                            ? {
+                                resource_source: 'web',
+                                aiwg_selector: webRelease.selector,
+                                aiwg_version: webRelease.version,
+                                manifest_sha256: webRelease.manifestDigest,
+                                manifest_url: webRelease.manifestUrl,
+                            }
+                            : {}),
+                    },
+                })),
+            }, null, 2));
+        }
+        else {
+            console.error(`Ambiguous: "${needle}" matches ${matches.length} artifacts. Disambiguate with the stable id:`);
+            for (const entry of matches) {
+                console.error(`  ${entry.type.padEnd(7)} ${discoveryIdForEntry(entry)} ${entry.title}`);
+            }
+        }
+        process.exit(2);
+    }
+    const entry = matches[0];
+    const absolutePath = resolvePath(entry);
+    const backend = params.backend ?? DEFAULT_ARTIFACT_SEARCH_BACKEND;
+    const record = backend === 'fortemi-core'
+        ? await fortemiRecordForEntry(cwd, entry, sourcePaths)
+        : null;
+    const payload = {
+        id: discoveryIdForEntry(entry),
+        backend,
+        type: entry.type,
+        name: entry.name,
+        title: entry.title,
+        paths: {
+            absolute: absolutePath,
+            indexed: entry.path,
+            repo_relative: record?.source.repo_relative_path ?? entry.path,
+            locator: record?.source.locator ?? entry.name ?? entry.title,
+        },
+        provenance: {
+            graph: entry.indexGraph ?? null,
+            scope: entry.indexScope ?? null,
+            ...(webRelease
+                ? {
+                    resource_source: 'web',
+                    aiwg_selector: webRelease.selector,
+                    aiwg_version: webRelease.version,
+                    manifest_sha256: webRelease.manifestDigest,
+                    manifest_url: webRelease.manifestUrl,
+                }
+                : {}),
+        },
+        metadata: record ?? entry,
+        providerModels: resourceSource === 'local'
+            ? await loadProviderModelMetadata(cwd, aiwgRoot)
+            : null,
+    };
+    if (params.json) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    console.log(`${payload.type} ${payload.title}`);
+    console.log(`  id: ${payload.id}`);
+    if (payload.name)
+        console.log(`  name: ${payload.name}`);
+    console.log(`  graph: ${payload.provenance.graph ?? 'unknown'}`);
+    console.log(`  scope: ${payload.provenance.scope ?? 'unknown'}`);
+    console.log(`  path: ${payload.paths.absolute}`);
+    console.log(`  indexed_path: ${payload.paths.indexed}`);
+    if (payload.providerModels) {
+        console.log('  provider_models:');
+        for (const [provider, hints] of Object.entries(payload.providerModels.providers)) {
+            console.log(`    ${provider}:`);
+            for (const hint of hints) {
+                console.log(`      ${hint.role}: ${hint.model} (wrapper: ${hint.wrapper}, status: ${hint.status})`);
+            }
+        }
+    }
+    console.log('');
+    console.log(JSON.stringify(payload.metadata, null, 2));
+}
+function isTopLevelPersonaAgentPath(entryPath) {
+    return /(^|[/\\])agentic[/\\]code[/\\]agents[/\\]personas[/\\][^/\\]+\.md$/.test(entryPath);
+}
+function isCanonicalBundleAgentPath(entryPath) {
+    return /(^|[/\\])agentic[/\\]code[/\\](?:frameworks|addons|extensions|plugins)[/\\][^/\\]+[/\\]agents[/\\][^/\\]+\.md$/.test(entryPath);
+}
+function isCanonicalSourceAgentPath(entryPath) {
+    return /(^|[/\\])agentic[/\\]code[/\\](?:frameworks|addons|extensions)[/\\][^/\\]+[/\\]agents[/\\][^/\\]+\.md$/.test(entryPath);
+}
+function isFrameworkSourceSkillPath(entryPath) {
+    return /(^|[/\\])agentic[/\\]code[/\\]frameworks[/\\][^/\\]+[/\\]skills[/\\][^/\\]+[/\\]SKILL\.md$/.test(entryPath);
+}
+function isCanonicalSourceSkillPath(entryPath) {
+    return /(^|[/\\])agentic[/\\]code[/\\](?:frameworks|addons|extensions)[/\\][^/\\]+[/\\]skills[/\\][^/\\]+[/\\]SKILL\.md$/.test(entryPath);
+}
+function uniqueEntriesByPath(entries) {
+    const seen = new Set();
+    const unique = [];
+    for (const entry of entries) {
+        if (seen.has(entry.path))
+            continue;
+        seen.add(entry.path);
+        unique.push(entry);
+    }
+    return unique;
+}
+//# sourceMappingURL=query-engine.js.map