@aiwg/cli 2026.8.18 → 2026.8.20

package/dist/src/artifacts/index-builder.js

@@ -2,7 +2,7 @@
  * Artifact Index Builder
  *
  * Scans .aiwg/ directories, extracts metadata from artifact frontmatter,
- * computes checksums, extracts @-mention dependencies, and builds a
+ * computes checksums, extracts @-mention and Markdown-link dependencies, and builds a
  * structured index at .aiwg/.index/.
  *
  * @implements #415
@@ -68,6 +68,57 @@ export function extractMentions(content) {
     }
     return Array.from(mentions);
 }
+/**
+ * Extract relative Markdown links that may resolve to graph-local artifacts.
+ *
+ * External URLs, absolute paths, and anchor-only links are intentionally absent
+ * from the accepted pattern. Resolution still happens later against indexed
+ * nodes, so a parsed link outside the active graph cannot create an edge.
+ */
+export function extractMarkdownLinks(content) {
+    const links = new Set();
+    const pattern = /(!?)\[[^\]]+\]\((\.\/?[^)#\s]+)(?:#[^)]+)?\)/g;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        if (match[1] === '!')
+            continue;
+        links.add(match[2]);
+    }
+    return Array.from(links);
+}
+function resolveMarkdownLinkDependency(cwd, sourcePath, rawLink, entries, graph) {
+    const target = rawLink.split('#')[0]?.trim();
+    if (!target)
+        return null;
+    const sourceFullPath = absoluteEntryPath(cwd, sourcePath, graph);
+    const targetFullPath = path.resolve(path.dirname(sourceFullPath), target);
+    let stat;
+    try {
+        stat = fs.statSync(targetFullPath);
+    }
+    catch {
+        return null;
+    }
+    if (!stat.isFile())
+        return null;
+    const indexedPath = indexPathFor(cwd, targetFullPath, graph);
+    return entries[indexedPath] ? indexedPath : null;
+}
+function addDependencyEdge(depGraph, entries, sourcePath, targetPath, type) {
+    if (sourcePath === targetPath)
+        return false;
+    if (!depGraph[sourcePath])
+        depGraph[sourcePath] = { upstream: [], downstream: [] };
+    if (!depGraph[targetPath])
+        depGraph[targetPath] = { upstream: [], downstream: [] };
+    if (depGraph[sourcePath].upstream.some(edge => edge.path === targetPath))
+        return false;
+    depGraph[sourcePath].upstream.push({ path: targetPath, type });
+    depGraph[targetPath].downstream.push({ path: sourcePath, type });
+    if (entries[targetPath])
+        entries[targetPath].dependents.push(sourcePath);
+    return true;
+}
 /**
  * Extract title from content (first # heading or frontmatter title)
  */
@@ -846,6 +897,7 @@ export async function buildIndex(cwd, options = {}) {
             const tags = flow ? flow.tags : (Array.isArray(data.tags) ? data.tags.map(String) : []);
             const summary = flow?.description ?? schemaDoc?.capability ?? runbook?.capability ?? extractSummary(data, body);
             const dependencies = extractMentions(content);
+            const markdownLinks = extractMarkdownLinks(content);
             // Discovery metadata (#1214, #1540, #1792) — meaningful for operational
             // AIWG artifact kinds. Kept undefined on document types so the index file
             // stays small for the common case.
@@ -879,6 +931,7 @@ export async function buildIndex(cwd, options = {}) {
                 checksum,
                 summary,
                 dependencies,
+                ...(markdownLinks.length > 0 ? { markdownLinks } : {}),
                 dependents: [], // Computed after all entries are processed
                 ...(name ? { name } : {}),
                 ...(triggers && triggers.length > 0 ? { triggers } : {}),
@@ -915,6 +968,7 @@ export async function buildIndex(cwd, options = {}) {
         }
     }
     // Build dependency graph and compute dependents
+    let markdownLinkEdgeCount = 0;
     for (const entry of Object.values(entries)) {
         if (!depGraph[entry.path]) {
             depGraph[entry.path] = { upstream: [], downstream: [] };
@@ -923,17 +977,13 @@ export async function buildIndex(cwd, options = {}) {
             // Normalize: check if referenced path exists in the index
             const normalizedDep = Object.keys(entries).find(p => p === dep || p.endsWith(dep));
             if (normalizedDep && normalizedDep !== entry.path) {
-                const upEdge = { path: normalizedDep, type: 'depends-on' };
-                depGraph[entry.path].upstream.push(upEdge);
-                if (!depGraph[normalizedDep]) {
-                    depGraph[normalizedDep] = { upstream: [], downstream: [] };
-                }
-                const downEdge = { path: entry.path, type: 'depends-on' };
-                depGraph[normalizedDep].downstream.push(downEdge);
-                // Also update the dependents field on the target entry
-                if (entries[normalizedDep]) {
-                    entries[normalizedDep].dependents.push(entry.path);
-                }
+                addDependencyEdge(depGraph, entries, entry.path, normalizedDep, 'depends-on');
+            }
+        }
+        for (const link of entry.markdownLinks ?? []) {
+            const normalizedDep = resolveMarkdownLinkDependency(cwd, entry.path, link, entries, graph);
+            if (normalizedDep && addDependencyEdge(depGraph, entries, entry.path, normalizedDep, 'markdown-link')) {
+                markdownLinkEdgeCount++;
             }
         }
     }
@@ -1027,6 +1077,20 @@ export async function buildIndex(cwd, options = {}) {
     writeIndexFile(effectiveOutputCwd, 'metadata.json', index, indexOutputDir);
     writeIndexFile(effectiveOutputCwd, 'tags.json', tagIndex, indexOutputDir);
     writeIndexFile(effectiveOutputCwd, 'dependencies.json', depGraph, indexOutputDir);
+    // Materialize the configured backend and always retain dependencies.json as
+    // the stable compatibility/export contract.
+    const { createGraphBackend } = await import('./graph-backend.js');
+    const { resolveGraphBackendType } = await import('./types.js');
+    const backendType = resolveGraphBackendType(graph);
+    const persistentPath = backendType === 'sqlite' ? path.join(indexOutputDir, 'graph.db') : undefined;
+    let selectedBackend;
+    try {
+        selectedBackend = await createGraphBackend(backendType, persistentPath);
+        selectedBackend.deserialize(depGraph);
+    }
+    finally {
+        await selectedBackend?.close?.();
+    }
     // Update and persist the checksum manifest for faster future builds (#794).
     // The next manifest contains entries for every file we processed this build.
     // Files that disappeared from disk are pruned; the resulting manifest is
@@ -1068,7 +1132,9 @@ export async function buildIndex(cwd, options = {}) {
         byType,
         tagDistribution: tagDist,
         graphMetrics: {
+            backend: backendType,
             totalEdges,
+            markdownLinkEdges: markdownLinkEdgeCount,
             ...(citationMetrics ? {
                 canonicalEdges: citationMetrics.canonicalEdges,
                 outgoingDeclarations: citationMetrics.outgoingDeclarations,

package/dist/src/artifacts/index-files.js

@@ -31,22 +31,40 @@ export function indexPathFor(cwd, fullPath, graph) {
         return toPosixPath(relative);
     return fullPath;
 }
-/** Recursively find indexable files, excluding hidden directories such as .index. */
 export function findArtifactFiles(dir, extensions = DEFAULT_INDEX_EXTENSIONS) {
+    return walkArtifactFiles(dir, extensions, new Set());
+}
+/** Recursively find indexable files, excluding hidden directories such as .index. */
+function walkArtifactFiles(dir, extensions, seenRealDirs) {
     const results = [];
     if (!fs.existsSync(dir))
         return results;
+    let realDir;
+    try {
+        realDir = fs.realpathSync(dir);
+    }
+    catch {
+        return results;
+    }
+    if (seenRealDirs.has(realDir))
+        return results;
+    seenRealDirs.add(realDir);
     const entries = fs.readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
         const fullPath = path.join(dir, entry.name);
-        if (entry.isSymbolicLink() && !fs.existsSync(fullPath))
+        let stat;
+        try {
+            stat = fs.statSync(fullPath);
+        }
+        catch {
             continue;
-        if (entry.isDirectory()) {
+        }
+        if (stat.isDirectory()) {
             if (entry.name.startsWith('.'))
                 continue;
-            results.push(...findArtifactFiles(fullPath, extensions));
+            results.push(...walkArtifactFiles(fullPath, extensions, seenRealDirs));
         }
-        else if (extensions.some(extension => entry.name.endsWith(extension))) {
+        else if (stat.isFile() && extensions.some(extension => entry.name.endsWith(extension))) {
             results.push(fullPath);
         }
     }
@@ -55,6 +73,9 @@ export function findArtifactFiles(dir, extensions = DEFAULT_INDEX_EXTENSIONS) {
 /** Return the exact current source-file set used by a standard graph build. */
 export async function collectGraphIndexFiles(cwd, graph) {
     const config = graph ? GRAPH_CONFIGS[graph] : undefined;
+    if (graph && !config) {
+        throw new Error(`Unknown graph: ${graph}`);
+    }
     const scanDirs = config
         ? config.scanDirs.map(directory => resolveGraphScanDir(cwd, directory))
         : [resolveProjectAiwgDir(cwd)];

package/dist/src/artifacts/index-status.js

@@ -18,7 +18,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { GRAPH_CONFIGS, BUILTIN_GRAPH_CONFIGS, getGraphIndexDir, getProjectIndexRoot, loadGlobalGraphConfigs, loadUserGraphConfigs, } from './types.js';
+import { GRAPH_CONFIGS, BUILTIN_GRAPH_CONFIGS, getGraphIndexDir, getProjectIndexRoot, loadGlobalGraphConfigs, loadUserGraphConfigs, resolveGraphBackendType, } from './types.js';
 import { getFortemiCoreSyncStatus, } from './fortemi-core-sync.js';
 function readBuiltMeta(indexDir) {
     try {
@@ -62,6 +62,7 @@ export function collectIndexStatus(cwd, nowMs) {
         }
         graphs.push({
             name,
+            backend: resolveGraphBackendType(name),
             origin: name in BUILTIN_GRAPH_CONFIGS ? 'builtin' : 'registered',
             shared: config.shared,
             defaultBuild: config.defaultBuild,
@@ -131,6 +132,7 @@ export async function showIndexStatus(cwd, opts = {}) {
         'GRAPH'.padEnd(22) +
         'ORIGIN'.padEnd(12) +
         'STATE'.padEnd(10) +
+        'BACKEND'.padEnd(12) +
         'ENTRIES'.padEnd(9) +
         'AGE'.padEnd(10) +
         'LOCATION');
@@ -145,6 +147,7 @@ export async function showIndexStatus(cwd, opts = {}) {
             g.name.padEnd(22) +
             g.origin.padEnd(12) +
             state.padEnd(10) +
+            g.backend.padEnd(12) +
             String(g.entries ?? '—').padEnd(9) +
             age.padEnd(10) +
             shortenPath(g.location, cwd));

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

@@ -181,7 +181,7 @@ const SCORE_STOPWORDS = new Set([
     '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',
+    'there', 'here', 'some', 'any', 'all', 'also', 'please', 'about', 'project',
     // question words
     'how', 'what', 'which', 'where', 'when', 'who', 'why',
     // asking / request verbs ("find a skill that handles …")
@@ -191,6 +191,7 @@ const SCORE_STOPWORDS = new Set([
     // AIWG meta-type nouns — zero discriminating signal in a discover query
     'aiwg', 'skill', 'skills', 'agent', 'agents', 'command', 'commands',
     'rule', 'rules', 'schema', 'schemas', 'flow', 'flows', 'workflow', 'workflows',
+    'template', 'templates',
 ]);
 /**
  * Tokenize a query phrase into lowercased keywords for multi-word
@@ -200,8 +201,18 @@ const SCORE_STOPWORDS = new Set([
 function tokenize(text) {
     return text
         .toLowerCase()
-        .split(/[^a-z0-9-]+/)
-        .filter(t => t.length > 1 && !SCORE_STOPWORDS.has(t));
+        .split(/[^a-z0-9]+/)
+        .filter(t => t.length > 1 && !SCORE_STOPWORDS.has(t))
+        .map(token => token.length > 4 && token.endsWith('s') && !token.endsWith('ss')
+        ? token.slice(0, -1)
+        : token);
+}
+function matchedFieldTokens(queryTokens, field) {
+    const fieldTokens = new Set(tokenize(field));
+    return queryTokens.filter(token => fieldTokens.has(token));
+}
+function fieldContainsQuery(field, queryTokens) {
+    return containsTokenSequence(tokenize(field), queryTokens);
 }
 /**
  * Score a metadata entry against a keyword query.
@@ -297,6 +308,7 @@ function scoreEntryDetailed(entry, text, opts = {}) {
     const personaIdentitySuppressed = diagnoseFacetActivations(text).some((activation) => activation.facet === 'persona-identity' && activation.status === 'suppressed');
     let score = 0;
     const matches = [];
+    const creditedTokens = new Set();
     const finish = (uncappedScore = score, cap = 1) => ({
         score: Math.min(uncappedScore, cap),
         diagnostic: {
@@ -311,6 +323,17 @@ function scoreEntryDetailed(entry, text, opts = {}) {
         score += contribution;
         matches.push({ ...match, contribution });
     };
+    const addTokenMatch = (contributionPerToken, hits, match) => {
+        const newlyMatched = hits.filter(token => !creditedTokens.has(token));
+        if (newlyMatched.length === 0)
+            return;
+        newlyMatched.forEach(token => creditedTokens.add(token));
+        addMatch(contributionPerToken * newlyMatched.length, {
+            ...match,
+            matched_tokens: newlyMatched,
+            query_token_coverage: tokens.length > 0 ? newlyMatched.length / tokens.length : 0,
+        });
+    };
     // 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
@@ -422,14 +445,12 @@ function scoreEntryDetailed(entry, text, opts = {}) {
                 });
             }
             else if (useMultiToken) {
-                const hits = tokens.filter(t => trigger.includes(t));
+                const hits = matchedFieldTokens(tokens, trigger);
                 if (overlapOK(hits.length)) {
-                    addMatch(0.06 * 4 * (hits.length / tokens.length), {
+                    addTokenMatch(0.1 * 4, hits, {
                         field: 'trigger',
                         match: 'token-overlap',
                         value: trigger,
-                        matched_tokens: hits,
-                        query_token_coverage: hits.length / tokens.length,
                     });
                 }
             }
@@ -437,7 +458,7 @@ function scoreEntryDetailed(entry, text, opts = {}) {
     }
     // Capability description (2x weight) — full phrase first, then tokens
     if (capabilityLower) {
-        if (capabilityLower.includes(lower)) {
+        if (fieldContainsQuery(capabilityLower, tokens)) {
             addMatch(0.2 * 2, {
                 field: 'capability',
                 match: 'contained-phrase',
@@ -445,20 +466,18 @@ function scoreEntryDetailed(entry, text, opts = {}) {
             });
         }
         else if (useMultiToken) {
-            const hits = tokens.filter(t => capabilityLower.includes(t));
+            const hits = matchedFieldTokens(tokens, capabilityLower);
             if (overlapOK(hits.length)) {
-                addMatch(0.1 * 2 * (hits.length / tokens.length), {
+                addTokenMatch(0.1 * 2, hits, {
                     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)) {
+    if (fieldContainsQuery(titleLower, tokens)) {
         addMatch(0.3 * 3, {
             field: 'title',
             match: titleLower === lower ? 'exact' : 'contained-phrase',
@@ -469,93 +488,83 @@ function scoreEntryDetailed(entry, text, opts = {}) {
         }
     }
     else if (useMultiToken) {
-        const hits = tokens.filter(t => titleLower.includes(t));
+        const hits = matchedFieldTokens(tokens, titleLower);
         if (overlapOK(hits.length)) {
-            addMatch(0.08 * 3 * (hits.length / tokens.length), {
+            addTokenMatch(0.08 * 3, hits, {
                 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)) {
+        if (fieldContainsQuery(tag, tokens)) {
             addMatch(0.2 * 2, { field: 'tag', match: 'contained-phrase', value: tag });
         }
         else if (useMultiToken) {
-            const hits = tokens.filter(t => tag.includes(t));
+            const hits = matchedFieldTokens(tokens, tag);
             if (overlapOK(hits.length)) {
-                addMatch(0.05 * 2 * (hits.length / tokens.length), {
+                addTokenMatch(0.05 * 2, hits, {
                     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)) {
+    if (fieldContainsQuery(searchTermsLower, tokens)) {
         addMatch(0.18 * 1.5, { field: 'search_terms', match: 'contained-phrase' });
     }
     else if (useMultiToken) {
-        const hits = tokens.filter(t => searchTermsLower.includes(t));
+        const hits = matchedFieldTokens(tokens, searchTermsLower);
         if (overlapOK(hits.length)) {
-            addMatch(0.06 * 1.5 * (hits.length / tokens.length), {
+            addTokenMatch(0.06 * 1.5, hits, {
                 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)) {
+    if (fieldContainsQuery(kindLower, tokens)) {
         addMatch(0.15, { field: 'kind', match: 'contained-phrase', value: entry.kind });
     }
-    if (sourceTypeLower.includes(lower)) {
+    if (fieldContainsQuery(sourceTypeLower, tokens)) {
         addMatch(0.08, { field: 'source_type', match: 'contained-phrase', value: entry.sourceType });
     }
     // Summary (1x weight)
-    if (summaryLower.includes(lower)) {
+    if (fieldContainsQuery(summaryLower, tokens)) {
         addMatch(0.15, { field: 'summary', match: 'contained-phrase' });
     }
     else if (useMultiToken) {
-        const hits = tokens.filter(t => summaryLower.includes(t));
+        const hits = matchedFieldTokens(tokens, summaryLower);
         if (overlapOK(hits.length)) {
-            addMatch(0.04 * (hits.length / tokens.length), {
+            addTokenMatch(0.04, hits, {
                 field: 'summary',
                 match: 'token-overlap',
-                matched_tokens: hits,
-                query_token_coverage: hits.length / tokens.length,
             });
         }
     }
     // Path (0.5x weight)
-    if (pathLower.includes(lower)) {
+    if (fieldContainsQuery(pathLower, tokens)) {
         addMatch(0.1, { field: 'path', match: 'contained-phrase', value: entry.path });
     }
     else if (useMultiToken) {
-        const hits = tokens.filter(t => pathLower.includes(t));
+        const hits = matchedFieldTokens(tokens, pathLower);
         if (overlapOK(hits.length)) {
-            addMatch(0.03 * (hits.length / tokens.length), {
+            addTokenMatch(0.03, hits, {
                 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)) {
+    if (fieldContainsQuery(typeLower, tokens)) {
         addMatch(0.1, { field: 'type', match: 'contained-phrase', value: entry.type });
     }
     return finish();
@@ -1078,36 +1087,27 @@ export async function discoverCapability(cwd, params) {
     // 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 });
+    // #154 — a strict result anywhere in the corpus must not suppress relevant
+    // partial matches for a natural-language query. Score the relaxed pass on
+    // matched terms (unmatched terms do not divide the score), apply a noise
+    // floor, and union it with strict matches before ranking. Word-boundary
+    // token matching keeps this from resurrecting substring noise such as UX in
+    // Linux.
+    const RELAXED_MIN_SCORE = 0.02;
+    const strictPaths = new Set(strictScored.map(result => result.entry.path));
+    const combinedByPath = new Map(strictScored.map(result => [result.entry.path, result]));
+    for (const entry of candidates) {
+        const detailed = scoreEntryDetailed(entry, params.phrase, { relaxOverlap: true });
+        if (detailed.score < RELAXED_MIN_SCORE)
+            continue;
+        const existing = combinedByPath.get(entry.path);
+        if (!existing || detailed.score > existing.score) {
+            combinedByPath.set(entry.path, { entry, score: detailed.score });
             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 scored = dedupeDiscoverResults(await applyFacetFusion(Array.from(combinedByPath.values()).sort(compareDiscoverResults), candidates, params.phrase)).slice(0, limit);
+    const relaxed = scored.some(result => !strictPaths.has(result.entry.path));
     const queryTimeMs = Date.now() - startTime;
     /**
      * Resolve a stored framework-graph path to an absolute AIWG_ROOT

package/dist/src/artifacts/stats.js

@@ -7,7 +7,7 @@
  * @source @src/artifacts/types.ts
  * @tests @test/unit/artifacts/stats.test.ts
  */
-import { GRAPH_CONFIGS, loadUserGraphConfigs } from './types.js';
+import { GRAPH_CONFIGS, loadGlobalGraphConfigs, loadUserGraphConfigs, resolveGraphBackendType } from './types.js';
 import { loadIndexStats, loadGraphIndexFile } from './index-reader.js';
 import { collectGraphIndexFiles, indexPathFor } from './index-files.js';
 /** Calculate coverage over the same current file set used by the index builder. */
@@ -30,6 +30,8 @@ async function calculateCoverage(cwd, stats, graphType) {
  */
 export async function showStats(cwd, options = {}) {
     const { graph } = options;
+    loadUserGraphConfigs(cwd);
+    loadGlobalGraphConfigs();
     if (graph) {
         // Single graph mode
         const stats = loadGraphIndexFile(cwd, 'stats.json', graph);
@@ -42,7 +44,6 @@ export async function showStats(cwd, options = {}) {
         return;
     }
     // No graph specified: show all graphs with defaultBuild=true
-    loadUserGraphConfigs(cwd);
     const graphTypes = Object.entries(GRAPH_CONFIGS)
         .filter(([, config]) => config.defaultBuild)
         .map(([name]) => name);
@@ -70,6 +71,7 @@ export async function showStats(cwd, options = {}) {
             const coverage = await calculateCoverage(cwd, s, type);
             combined[type] = {
                 ...s,
+                backend: resolveGraphBackendType(type),
                 coverage,
             };
         }
@@ -90,6 +92,7 @@ async function renderStats(cwd, stats, options, graphType) {
         const coverage = await calculateCoverage(cwd, stats, graphType);
         console.log(JSON.stringify({
             ...stats,
+            backend: resolveGraphBackendType(graphType),
             coverage,
         }, null, 2));
         return;
@@ -100,6 +103,7 @@ async function renderStats(cwd, stats, options, graphType) {
     console.log(`Index version: ${stats.version}`);
     console.log(`Last built:    ${stats.builtAt}`);
     console.log(`Build time:    ${stats.buildTimeMs}ms`);
+    console.log(`Graph backend: ${resolveGraphBackendType(graphType)}`);
     console.log('');
     // By phase
     console.log('Artifacts by Phase:');
@@ -128,6 +132,9 @@ async function renderStats(cwd, stats, options, graphType) {
     // Dependency graph
     console.log('Dependency Graph:');
     console.log(`  Total edges:        ${stats.graphMetrics.totalEdges}`);
+    if (stats.graphMetrics.markdownLinkEdges !== undefined) {
+        console.log(`  Markdown link edges:${String(stats.graphMetrics.markdownLinkEdges).padStart(3)}`);
+    }
     if (stats.graphMetrics.canonicalEdges !== undefined) {
         console.log(`  Canonical edges:    ${stats.graphMetrics.canonicalEdges}`);
         console.log(`  Outgoing declares:  ${stats.graphMetrics.outgoingDeclarations}`);

package/dist/src/artifacts/types.js

@@ -104,7 +104,7 @@ export const INDEX_VERSION = '1.0.0';
  * making the serialized index schema incompatible; a mismatch simply forces a
  * one-time content re-extraction during the next incremental build.
  */
-export const INDEX_EXTRACTOR_VERSION = '2026.07.21.2';
+export const INDEX_EXTRACTOR_VERSION = '2026.08.24.1';
 /**
  * Built-in graph definitions
  */
@@ -195,6 +195,11 @@ export const BUILTIN_GRAPH_CONFIGS = {
  * @implements #426
  */
 export const GRAPH_CONFIGS = { ...BUILTIN_GRAPH_CONFIGS };
+let projectGraphBackend;
+/** Resolve backend precedence: graph override, project default, then JSON. */
+export function resolveGraphBackendType(graph) {
+    return (graph ? GRAPH_CONFIGS[graph]?.graphBackend : undefined) ?? projectGraphBackend ?? 'json';
+}
 function freshBuiltinGraphConfig(name) {
     const config = BUILTIN_GRAPH_CONFIGS[name];
     return {
@@ -459,6 +464,7 @@ export function loadUserGraphConfigs(cwd, diagnostics) {
     // Reset on every project load so a prior cwd cannot leak its override or
     // detected Python package roots into a later build in the same process.
     GRAPH_CONFIGS.codebase = detectPythonCodebaseConfig(cwd, freshBuiltinGraphConfig('codebase'));
+    projectGraphBackend = undefined;
     // Load module-declared graphs first (frameworks/addons)
     const moduleLoaded = loadModuleGraphConfigs(cwd, diagnostics);
     const loaded = [...moduleLoaded];
@@ -469,12 +475,16 @@ export function loadUserGraphConfigs(cwd, diagnostics) {
     let graphs;
     let graphOverrides;
     let fromDeprecatedYaml = false;
+    let canonicalIndexPresent = false;
     // (a) Canonical: .aiwg/aiwg.config (JSON).
     try {
         const aiwgConfigPath = projectControlPath(cwd, 'aiwg.config');
         if (fs.existsSync(aiwgConfigPath)) {
             const parsed = JSON.parse(fs.readFileSync(aiwgConfigPath, 'utf-8'));
             const idx = parsed.index;
+            canonicalIndexPresent = idx !== undefined;
+            if (idx?.graphBackend === 'json' || idx?.graphBackend === 'graphology' || idx?.graphBackend === 'sqlite')
+                projectGraphBackend = idx.graphBackend;
             const g = idx?.graphs;
             if (g && typeof g === 'object')
                 graphs = g;
@@ -493,12 +503,14 @@ export function loadUserGraphConfigs(cwd, diagnostics) {
         });
     }
     // (b) Fallback: legacy .aiwg/config.yaml.
-    if (!graphs && !graphOverrides) {
+    if (!canonicalIndexPresent && !graphs && !graphOverrides) {
         try {
             const configPath = projectAiwgPath(cwd, 'config.yaml');
             if (fs.existsSync(configPath)) {
                 const config = loadYaml(fs.readFileSync(configPath, 'utf-8'));
                 const idx = config?.index;
+                if (idx?.graphBackend === 'json' || idx?.graphBackend === 'graphology' || idx?.graphBackend === 'sqlite')
+                    projectGraphBackend = idx.graphBackend;
                 const g = idx?.graphs;
                 if (g && typeof g === 'object') {
                     graphs = g;

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

@@ -71,6 +71,8 @@ function displayHelp() {
         ['runtime-info', 'Show runtime environment summary'],
         ['runtime-info --discover', 'Full tool discovery and catalog generation'],
         ['runtime-info --check <tool>', 'Check specific tool availability'],
+        ['runtime-info --transports', 'Show configured transport capabilities separately from providers'],
+        ['uhp <operation> --profile <name>', 'Inspect or smoke-test an explicit experimental UHP endpoint profile'],
     ]);
     helpGroup('CATALOG', [
         ['catalog list', 'List all models in catalog'],